@intentius/behold 0.7.0 → 0.8.0

package/example-argo-estate/README.md

@@ -0,0 +1,46 @@
+# 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
+```
+
+Unlike flux-estate this one is **declared only** — no cluster, no Argo install,
+no Docker. It copies out, `npm install`s, and serves. 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** on the control plane alone
+  (`behold serve control-plane`, zoom: logical): `namespace app-a` and
+  `namespace app-b` drawn as boxes even though the control plane declares no
+  `Namespace` object anywhere. They come from each Application's
+  `spec.destination.namespace` — a namespace Argo will own objects in is a
+  namespace the estate is committed to. Serve all three members and the apps'
+  Deployments and Services sit inside those boxes.
+
+That last one 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). `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.

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

@@ -0,0 +1,10 @@
+import type { ChantConfig } from "@intentius/chant";
+
+// App project A. Argo syncs its committed manifests/ (chant build output) from
+// the repo; this project applies nothing itself. Declared-only demo, so no
+// kube context is bound — see ../control-plane/chant.config.ts.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  ownership: { stack: "argo-app-a" },
+} 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.3",
+    "@intentius/chant-lexicon-k8s": "^0.44.3"
+  }
+}

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,9 @@
+import type { ChantConfig } from "@intentius/chant";
+
+// App project B — same shape as app-a, second sync wave. Declared-only demo,
+// so no kube context is bound; see ../control-plane/chant.config.ts.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  ownership: { stack: "argo-app-b" },
+} 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.3",
+    "@intentius/chant-lexicon-k8s": "^0.44.3"
+  }
+}

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,14 @@
+import type { ChantConfig } from "@intentius/chant";
+
+// The estate's control plane: it declares the Argo machinery (an AppProject +
+// one Application per app), and Argo's controller deploys the app projects —
+// this project never applies a workload itself.
+//
+// No k8s profile block, unlike the flux-estate demo's: argo-estate is the
+// DECLARED story only. Nothing here binds a kube context because nothing here
+// reads one — `behold demo argo-estate` needs no cluster and installs no Argo.
+export default {
+  lexicons: ["k8s"],
+  sourceDir: "src",
+  ownership: { stack: "argo-control-plane" },
+} 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.3",
+    "@intentius/chant-lexicon-k8s": "^0.44.3"
+  }
+}

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"] }