@intentius/behold 0.7.0 → 0.9.0

package/example-argo-estate/README.md

@@ -0,0 +1,71 @@
+# argo-estate — behold's Argo CD estate demo (#235)
+
+Three chant projects served as one composed estate, the Argo mirror of
+[example-flux-estate](../example-flux-estate):
+
+- **control-plane/** — the Argo machinery: an `AppProject` fencing which repo
+  and which namespaces the estate may deploy, and one `Application` per app
+  syncing that app's committed manifests from behold's own public repo. Argo's
+  controller does the applying; this project never applies a workload itself.
+- **app-a/**, **app-b/** — small web workloads in namespaces `app-a` and
+  `app-b`, the namespaces the Applications name as their sync destinations.
+
+```sh
+npx @intentius/behold demo argo-estate
+```
+
+The demo path is **declared only** — no cluster, no Argo install, no Docker. It
+copies out, `npm install`s, and serves. (There is a live lane, but it is an
+acceptance run rather than part of the demo: see "Live" below.) What to look
+at:
+
+- The **estate**: per-project boundary boxes, and the `project` edges joining
+  both Applications to the AppProject they name (behold#222) — the join chant
+  lints as ARGO002, so an estate whose lint passes cannot be drawn wrong.
+  The entity graph carries them at the attributes tier (`?detail=3`).
+- The **logical lens** (zoom: logical): cluster ⊃ `namespace app-a` and
+  `namespace app-b`, each holding that app's Deployment + Service, plus
+  `namespace argocd` holding both Applications and the AppProject — drawn
+  even though the control plane declares no `Namespace` object anywhere. The
+  app namespaces come from each Application's `spec.destination.namespace`; a
+  namespace Argo will own objects in is a namespace the estate is committed
+  to, and behold#224 taught the composed estate to draw that projection.
+  Serve `control-plane` alone (`behold serve control-plane`, zoom: logical)
+  and the same boxes appear empty — the destination harvest still names them,
+  but there is nothing from app-a/app-b in the graph to fill them with.
+
+That alone-vs-composed split is the Argo/Flux difference worth noticing:
+flux-estate's control plane must declare the app namespaces itself (a
+Kustomization's `targetNamespace` must already exist), while here
+`CreateNamespace=true` means Argo makes them — so the box exists on the
+strength of the destination alone.
+
+Argo's ordering is the `argocd.argoproj.io/sync-wave` annotation, so unlike
+Flux's `dependsOn` (behold#223) there is no edge to draw for it: app-a is wave
+0, app-b wave 1, and the picture says nothing about it.
+
+The app `manifests/` are committed `chant build` output — the path each
+Application syncs. Changing an app's source means a rebuild (`npm run build` in
+the app), and the rebuilt manifests have to be on `main` before Argo can sync
+them. `chant build` in the control plane warns ARGO005 on both Applications:
+`source.path` is repo-relative (that's what Argo resolves it against), not
+relative to the build root, so it doesn't resolve locally. Fine here, and the
+check's own message says so.
+
+## Live
+
+Nothing above needs a cluster, but the estate as committed does reconcile
+against a real one — the Applications point at this repo on `main` and the app
+`manifests/` are already there, so an Argo CD install has everything it needs.
+`just e2e-argo-estate` (behold#269) is that run: a scratch k3d cluster, Argo
+from the pinned `core-install` manifest, the control plane applied once, and
+then the composed estate served against the result — the destination-namespace
+boxes filled with live cards, #238's health verdicts read off each
+Application's health/sync pair, and the unhappy arm (an Application pointed at
+a path that does not exist, then restored). It creates and deletes its own
+cluster and touches no other context.
+
+Each member's `chant.config.ts` therefore binds a `local` profile to the
+context `k3d-behold-argo-demo`, which is what that run aliases its scratch
+cluster to. Serving without `--env` — what `behold demo argo-estate` does —
+reads none of it.

package/example-argo-estate/app-a/chant.config.ts

@@ -0,0 +1,18 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project A. Argo syncs its committed manifests/ (chant build output) from
+// the repo; this project applies nothing itself. behold serves it as part of
+// the estate, and the live overlay reads the cluster through the same binding
+// as every other member — see ../control-plane/chant.config.ts.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "argo-app-a" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-argo-estate/app-a/manifests/app.yaml

@@ -0,0 +1,54 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: argo-app-a
+    app: app-a
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: app-a
+  template:
+    metadata:
+      labels:
+        app: app-a
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-a
+  namespace: app-a
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: argo-app-a
+spec:
+  selector:
+    app: app-a
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-argo-estate/app-a/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-argo-app-a",
+  "private": true,
+  "type": "module",
+  "description": "App project A: a small web workload in namespace app-a, synced by the control plane's Argo Application.",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
+  }
+}

package/example-argo-estate/app-a/src/app.ts

@@ -0,0 +1,35 @@
+// App A: one small web workload, namespace declared on every object — the same
+// namespace the control plane's Application names as its sync destination.
+// That agreement is the point: behold draws the namespace box from the
+// Application's destination and fills it with these cards.
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-a" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-a", namespace: "app-a", labels },
+  spec: {
+    replicas: 1,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-a", namespace: "app-a" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-argo-estate/app-a/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }

package/example-argo-estate/app-b/chant.config.ts

@@ -0,0 +1,18 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// App project B — same shape as app-a, second sync wave. Unlike flux-estate's
+// app-b this one declares its own namespace on every object (Argo has no
+// targetNamespace to stamp one at apply time), so a live read resolves it
+// straight away. See ../control-plane/chant.config.ts for the binding.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "argo-app-b" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-argo-estate/app-b/manifests/app.yaml

@@ -0,0 +1,54 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: app-b
+  namespace: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: argo-app-b
+    app: app-b
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: app-b
+  template:
+    metadata:
+      labels:
+        app: app-b
+    spec:
+      containers:
+        - name: web
+          image: nginxinc/nginx-unprivileged:1.27-alpine
+          ports:
+            - containerPort: 8080
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 101
+            allowPrivilegeEscalation: false
+            capabilities:
+              drop:
+                - ALL
+          resources:
+            requests:
+              cpu: '25m'
+              memory: '32Mi'
+            limits:
+              cpu: '100m'
+              memory: '64Mi'
+
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: app-b
+  namespace: app-b
+  labels:
+    app.kubernetes.io/managed-by: chant
+    chant.intentius.io/stack: argo-app-b
+spec:
+  selector:
+    app: app-b
+  ports:
+    - port: 80
+      targetPort: 8080

package/example-argo-estate/app-b/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-argo-app-b",
+  "private": true,
+  "type": "module",
+  "description": "App project B: the same workload in namespace app-b, synced one wave later.",
+  "scripts": {
+    "build": "chant build src -o manifests/app.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
+  }
+}

package/example-argo-estate/app-b/src/app.ts

@@ -0,0 +1,34 @@
+// App B: the same workload in namespace app-b, the estate's second sync wave.
+// Two apps rather than one so the AppProject has more than a single Application
+// hanging off it — the fan-out is what an app-of-apps picture is for.
+import { Deployment, Service } from "@intentius/chant-lexicon-k8s";
+
+const labels = { app: "app-b" };
+const image = "nginxinc/nginx-unprivileged:1.27-alpine";
+
+export const deployment = new Deployment({
+  metadata: { name: "app-b", namespace: "app-b", labels },
+  spec: {
+    replicas: 2,
+    selector: { matchLabels: labels },
+    template: {
+      metadata: { labels },
+      spec: {
+        containers: [
+          {
+            name: "web",
+            image,
+            ports: [{ containerPort: 8080 }],
+            securityContext: { runAsNonRoot: true, runAsUser: 101, allowPrivilegeEscalation: false, capabilities: { drop: ["ALL"] } },
+            resources: { requests: { cpu: "25m", memory: "32Mi" }, limits: { cpu: "100m", memory: "64Mi" } },
+          },
+        ],
+      },
+    },
+  },
+});
+
+export const service = new Service({
+  metadata: { name: "app-b", namespace: "app-b" },
+  spec: { selector: labels, ports: [{ port: 80, targetPort: 8080 }] },
+});

package/example-argo-estate/app-b/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }

package/example-argo-estate/control-plane/chant.config.ts

@@ -0,0 +1,29 @@
+import type { ChantConfig } from "@intentius/chant";
+import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+
+// The estate's control plane: it declares the Argo machinery (an AppProject +
+// one Application per app), and Argo's application controller deploys the app
+// projects — this project never applies a workload itself.
+//
+// `npx @intentius/behold demo argo-estate` still needs no cluster: it serves
+// the source graph with no `--env`, and nothing below is read on that path.
+// The `local` profile exists for the live lane (behold#269,
+// `just e2e-argo-estate`), which stands up a scratch k3d cluster and aliases
+// its context to the name pinned here — so a live read resolves the DECLARED
+// binding and can never observe whatever kubectl context happens to be
+// ambient (chant#1100).
+//
+// Deliberately no `ownership.env`: the app members' committed manifests/ are
+// what Argo syncs from `main`, so a label that changes their build output
+// would have to be merged before any live run could agree with the cluster.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  environments: ["local"],
+  ownership: { stack: "argo-control-plane" },
+  k8s: {
+    profiles: {
+      local: { context: "k3d-behold-argo-demo" },
+    },
+  } satisfies K8sChantConfig,
+} satisfies ChantConfig;

package/example-argo-estate/control-plane/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "behold-example-argo-control-plane",
+  "private": true,
+  "type": "module",
+  "description": "The estate's control plane: the Argo CD CRs (an AppProject + one Application per app project).",
+  "scripts": {
+    "build": "chant build src -o dist/control-plane.yaml --format yaml"
+  },
+  "dependencies": {
+    "@intentius/chant": "^0.44.6",
+    "@intentius/chant-lexicon-k8s": "^0.44.6"
+  }
+}

package/example-argo-estate/control-plane/src/argo.ts

@@ -0,0 +1,69 @@
+// The control plane, Argo-style: one AppProject that fences what the estate is
+// allowed to deploy, and one Application per app project, each syncing that
+// app's committed manifests from this repo. Argo's application controller does
+// the applying — this project never applies a workload itself.
+//
+// Written with the raw declarables rather than the ArgoAppFor composite on
+// purpose: the two fields the whole demo is about, `spec.project` and
+// `spec.destination.namespace`, are the ones a stranger reading Argo YAML
+// already knows by sight, and here they sit in the source verbatim. (For real
+// estates the composite is fewer lines: ArgoAppFor("app-a", { repo, path,
+// project, destination }) renders this same Application.)
+import { AppProject, Application } from "@intentius/chant-lexicon-k8s";
+
+const REPO = "https://github.com/INTENTIUS/behold";
+// The in-cluster target every Argo install has. Naming it (rather than a
+// registered cluster Secret) is what keeps this estate a one-cluster story.
+const IN_CLUSTER = "https://kubernetes.default.svc";
+
+// The fence: which repo the apps may sync from, and which namespaces Argo may
+// own objects in. Both Applications name it in spec.project — the join behold
+// draws (behold#222) and chant lints as ARGO002.
+export const project = new AppProject({
+  metadata: { name: "estate", namespace: "argocd" },
+  spec: {
+    description: "behold's demo estate: two app projects, one cluster.",
+    sourceRepos: [REPO],
+    destinations: [
+      { server: IN_CLUSTER, namespace: "app-a" },
+      { server: IN_CLUSTER, namespace: "app-b" },
+    ],
+    // CreateNamespace=true below means Argo creates the destination namespaces,
+    // so the project has to permit that one cluster-scoped kind.
+    clusterResourceWhitelist: [{ group: "", kind: "Namespace" }],
+  },
+});
+
+export const appA = new Application({
+  metadata: {
+    name: "app-a",
+    namespace: "argocd",
+    // Argo's ordering idiom is a wave annotation, not a reference — so unlike
+    // Flux's dependsOn (behold#223) there is no edge to draw for it. app-a
+    // syncs first; app-b follows.
+    annotations: { "argocd.argoproj.io/sync-wave": "0" },
+  },
+  spec: {
+    project: "estate",
+    source: { repoURL: REPO, targetRevision: "main", path: "example-argo-estate/app-a/manifests" },
+    // The namespace Argo will own objects in. app-a's own objects declare it
+    // too, so the box behold draws holds the app's cards; declaring it here is
+    // what makes the box a fact about the CONTROL PLANE's graph as well.
+    destination: { server: IN_CLUSTER, namespace: "app-a" },
+    syncPolicy: { automated: { prune: true, selfHeal: true }, syncOptions: ["CreateNamespace=true"] },
+  },
+});
+
+export const appB = new Application({
+  metadata: {
+    name: "app-b",
+    namespace: "argocd",
+    annotations: { "argocd.argoproj.io/sync-wave": "1" },
+  },
+  spec: {
+    project: "estate",
+    source: { repoURL: REPO, targetRevision: "main", path: "example-argo-estate/app-b/manifests" },
+    destination: { server: IN_CLUSTER, namespace: "app-b" },
+    syncPolicy: { automated: { prune: true, selfHeal: true }, syncOptions: ["CreateNamespace=true"] },
+  },
+});

package/example-argo-estate/control-plane/tsconfig.json

@@ -0,0 +1 @@
+{ "compilerOptions": { "target": "ES2022", "module": "ESNext", "moduleResolution": "Bundler", "strict": true, "skipLibCheck": true, "noEmit": true }, "include": ["src/**/*", "ops/**/*", "chant.config.ts"] }