@intentius/chant-lexicon-k8s 0.124.31 → 0.124.33

package/dist/composites/worker-pool.js

@@ -0,0 +1,167 @@
+/**
+ * WorkerPool composite — Deployment + ServiceAccount + Role + RoleBinding + optional ConfigMap + optional HPA.
+ *
+ * A higher-level construct for background queue workers (Sidekiq, Celery, Bull)
+ * that need RBAC for secrets/configmaps and optional autoscaling, but no Service.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { Deployment, ServiceAccount, Role, RoleBinding, ConfigMap, HorizontalPodAutoscaler, PodDisruptionBudget, } from "../generated/index.js";
+/**
+ * Create a WorkerPool composite — returns prop objects for
+ * a Deployment, ServiceAccount, Role, RoleBinding, optional ConfigMap, and optional HPA.
+ *
+ * @example
+ * ```ts
+ * import { WorkerPool } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { deployment, serviceAccount, role, roleBinding } = WorkerPool({
+ *   name: "email-worker",
+ *   image: "worker:1.0",
+ *   command: ["bundle", "exec", "sidekiq"],
+ *   config: { REDIS_URL: "redis://redis:6379" },
+ * });
+ * ```
+ */
+export const WorkerPool = Composite((props) => {
+    const { name, image, command, args, replicas = 1, config, rbacRules, autoscaling, minAvailable, securityContext, terminationGracePeriodSeconds, priorityClassName, cpuRequest = "100m", memoryRequest = "128Mi", cpuLimit = "500m", memoryLimit = "256Mi", labels: extraLabels = {}, namespace, env, defaults: defs, } = props;
+    const saName = `${name}-sa`;
+    const roleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const configMapName = `${name}-config`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    // undefined → default RBAC rules; explicit [] → no RBAC resources
+    const createRbac = rbacRules === undefined || rbacRules.length > 0;
+    const effectiveRbacRules = rbacRules === undefined
+        ? [{ apiGroups: [""], resources: ["secrets", "configmaps"], verbs: ["get"] }]
+        : rbacRules;
+    const effectiveReplicas = autoscaling ? autoscaling.minReplicas : replicas;
+    const container = {
+        name,
+        image,
+        ...(command && { command }),
+        ...(args && { args }),
+        resources: {
+            limits: { cpu: cpuLimit, memory: memoryLimit },
+            requests: { cpu: cpuRequest, memory: memoryRequest },
+        },
+        ...(env && { env }),
+        ...(config && {
+            envFrom: [{ configMapRef: { name: configMapName } }],
+        }),
+        ...(securityContext && { securityContext }),
+    };
+    const podSpec = {
+        ...(createRbac && { serviceAccountName: saName }),
+        containers: [container],
+        ...(terminationGracePeriodSeconds !== undefined && { terminationGracePeriodSeconds }),
+        ...(priorityClassName && { priorityClassName }),
+    };
+    const deployment = new Deployment(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+        },
+        spec: {
+            replicas: effectiveReplicas,
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: podSpec,
+            },
+        },
+    }, defs?.deployment));
+    const result = { deployment };
+    if (createRbac) {
+        result.serviceAccount = new ServiceAccount(mergeDefaults({
+            metadata: {
+                name: saName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "worker" },
+            },
+        }, defs?.serviceAccount));
+        result.role = new Role(mergeDefaults({
+            metadata: {
+                name: roleName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            rules: effectiveRbacRules,
+        }, defs?.role));
+        result.roleBinding = new RoleBinding(mergeDefaults({
+            metadata: {
+                name: bindingName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            roleRef: {
+                apiGroup: "rbac.authorization.k8s.io",
+                kind: "Role",
+                name: roleName,
+            },
+            subjects: [
+                {
+                    kind: "ServiceAccount",
+                    name: saName,
+                    ...(namespace && { namespace }),
+                },
+            ],
+        }, defs?.roleBinding));
+    }
+    if (config) {
+        result.configMap = new ConfigMap(mergeDefaults({
+            metadata: {
+                name: configMapName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+            },
+            data: config,
+        }, defs?.configMap));
+    }
+    if (minAvailable !== undefined) {
+        result.pdb = new PodDisruptionBudget(mergeDefaults({
+            metadata: {
+                name,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "disruption-budget" },
+            },
+            spec: {
+                minAvailable,
+                selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            },
+        }, defs?.pdb));
+    }
+    if (autoscaling) {
+        const targetCPUPercent = autoscaling.targetCPUPercent ?? 70;
+        result.hpa = new HorizontalPodAutoscaler(mergeDefaults({
+            metadata: {
+                name,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "autoscaler" },
+            },
+            spec: {
+                scaleTargetRef: {
+                    apiVersion: "apps/v1",
+                    kind: "Deployment",
+                    name,
+                },
+                minReplicas: autoscaling.minReplicas,
+                maxReplicas: autoscaling.maxReplicas,
+                metrics: [
+                    {
+                        type: "Resource",
+                        resource: {
+                            name: "cpu",
+                            target: { type: "Utilization", averageUtilization: targetCPUPercent },
+                        },
+                    },
+                ],
+            },
+        }, defs?.hpa));
+    }
+    return result;
+}, "WorkerPool");

package/dist/composites/workload-identity-sa.js

@@ -0,0 +1,81 @@
+/**
+ * WorkloadIdentityServiceAccount composite — ServiceAccount + Workload Identity annotation + optional RBAC.
+ *
+ * @aks Creates a ServiceAccount with the `azure.workload.identity/client-id`
+ * annotation and `azure.workload.identity/use: "true"` label for AKS Workload Identity.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, Role, RoleBinding } from "../generated/index.js";
+/**
+ * Create a WorkloadIdentityServiceAccount composite — returns prop objects for
+ * a ServiceAccount with AKS Workload Identity annotation, and optional Role + RoleBinding.
+ *
+ * @aks
+ * @example
+ * ```ts
+ * import { WorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { serviceAccount, role, roleBinding } = WorkloadIdentityServiceAccount({
+ *   name: "app-sa",
+ *   clientId: "00000000-0000-0000-0000-000000000000",
+ *   rbacRules: [
+ *     { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+ *   ],
+ * });
+ * ```
+ */
+export const WorkloadIdentityServiceAccount = Composite((props) => {
+    const { name, clientId, rbacRules, labels: extraLabels = {}, namespace, defaults: defs, } = props;
+    const roleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: {
+                ...commonLabels,
+                "app.kubernetes.io/component": "service-account",
+                "azure.workload.identity/use": "true",
+            },
+            annotations: {
+                "azure.workload.identity/client-id": clientId,
+            },
+        },
+    }, defs?.serviceAccount));
+    const result = { serviceAccount };
+    if (rbacRules && rbacRules.length > 0) {
+        result.role = new Role(mergeDefaults({
+            metadata: {
+                name: roleName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            rules: rbacRules,
+        }, defs?.role));
+        result.roleBinding = new RoleBinding(mergeDefaults({
+            metadata: {
+                name: bindingName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            roleRef: {
+                apiGroup: "rbac.authorization.k8s.io",
+                kind: "Role",
+                name: roleName,
+            },
+            subjects: [
+                {
+                    kind: "ServiceAccount",
+                    name,
+                    ...(namespace && { namespace }),
+                },
+            ],
+        }, defs?.roleBinding));
+    }
+    return result;
+}, "WorkloadIdentityServiceAccount");

package/dist/composites/workload-identity-service-account.js

@@ -0,0 +1,77 @@
+/**
+ * WorkloadIdentityServiceAccount composite — ServiceAccount + GKE Workload Identity annotation + optional RBAC.
+ *
+ * @gke Creates a ServiceAccount with the `iam.gke.io/gcp-service-account`
+ * annotation for GKE Workload Identity Federation.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { ServiceAccount, Role, RoleBinding } from "../generated/index.js";
+/**
+ * Create a WorkloadIdentityServiceAccount composite — returns prop objects for
+ * a ServiceAccount with GKE Workload Identity annotation, and optional Role + RoleBinding.
+ *
+ * @gke
+ * @example
+ * ```ts
+ * import { WorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { serviceAccount, role, roleBinding } = WorkloadIdentityServiceAccount({
+ *   name: "app-sa",
+ *   gcpServiceAccountEmail: "sa@my-project.iam.gserviceaccount.com",
+ *   rbacRules: [
+ *     { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+ *   ],
+ * });
+ * ```
+ */
+export const WorkloadIdentityServiceAccount = Composite((props) => {
+    const { name, gcpServiceAccountEmail, rbacRules, labels: extraLabels = {}, namespace, defaults: defs, } = props;
+    const roleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name,
+            ...(namespace && { namespace }),
+            labels: { ...commonLabels, "app.kubernetes.io/component": "service-account" },
+            annotations: {
+                "iam.gke.io/gcp-service-account": gcpServiceAccountEmail,
+            },
+        },
+    }, defs?.serviceAccount));
+    const result = { serviceAccount };
+    if (rbacRules && rbacRules.length > 0) {
+        result.role = new Role(mergeDefaults({
+            metadata: {
+                name: roleName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            rules: rbacRules,
+        }, defs?.role));
+        result.roleBinding = new RoleBinding(mergeDefaults({
+            metadata: {
+                name: bindingName,
+                ...(namespace && { namespace }),
+                labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            roleRef: {
+                apiGroup: "rbac.authorization.k8s.io",
+                kind: "Role",
+                name: roleName,
+            },
+            subjects: [
+                {
+                    kind: "ServiceAccount",
+                    name,
+                    ...(namespace && { namespace }),
+                },
+            ],
+        }, defs?.roleBinding));
+    }
+    return result;
+}, "WorkloadIdentityServiceAccount");

package/dist/config-schema.js

@@ -0,0 +1,72 @@
+/**
+ * Runtime shape of the `k8s` namespace in `chant.config.ts` (#1344).
+ *
+ * `./config.ts` describes the namespace for readers and for the `satisfies
+ * K8sChantConfig` form it documents. What it could not do is make an unknown
+ * key fail: the project config schema is `.passthrough()`, so a typo in
+ * `k8s.profiles.prod.contxt` was accepted and ignored — and a missing cluster
+ * binding is the failure this lexicon most cares about, since a wrong-cluster
+ * read reports every declared resource as missing (#1100).
+ *
+ * The schema is the runtime half. It is checked against `K8sChantConfig` below,
+ * so the two descriptions of the namespace cannot drift.
+ */
+import { z } from "zod";
+export const k8sClusterProfileSchema = z.strictObject({
+    context: z.string(),
+});
+const kinds = z.array(z.string().min(1)).optional();
+/** A `k8s.crds` entry. Remote sources must carry their pin. */
+export const k8sProjectCrdSourceSchema = z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("file"), path: z.string().min(1), kinds }),
+    z.strictObject({
+        type: z.literal("url"),
+        url: z.string().url(),
+        sha256: z.string().regex(/^(sha256:)?[0-9a-f]{64}$/, "must be the hex sha256 of the URL's content"),
+        kinds,
+    }),
+    z.strictObject({
+        type: z.literal("helm"),
+        chart: z.string().min(1),
+        version: z.string().min(1),
+        digest: z.string().optional(),
+        chartSubdir: z.string().optional(),
+        kinds,
+    }),
+]);
+const jsonPatchOperationSchema = z.discriminatedUnion("op", [
+    z.strictObject({ op: z.literal("add"), path: z.string(), value: z.unknown() }),
+    z.strictObject({ op: z.literal("remove"), path: z.string() }),
+    z.strictObject({ op: z.literal("replace"), path: z.string(), value: z.unknown() }),
+    z.strictObject({ op: z.literal("move"), from: z.string(), path: z.string() }),
+    z.strictObject({ op: z.literal("copy"), from: z.string(), path: z.string() }),
+    z.strictObject({ op: z.literal("test"), path: z.string(), value: z.unknown() }),
+]);
+const renderedSelectorShape = {
+    kind: z.string().min(1),
+    name: z.string().min(1),
+    namespace: z.string().optional(),
+    apiVersion: z.string().optional(),
+};
+/** A `RenderedPatch` (#3566): a selector plus exactly one of `jsonPatch` and `merge`. */
+export const renderedPatchSchema = z.union([
+    z.strictObject({ ...renderedSelectorShape, jsonPatch: z.array(jsonPatchOperationSchema), merge: z.never().optional() }),
+    z.strictObject({ ...renderedSelectorShape, merge: z.record(z.string(), z.unknown()), jsonPatch: z.never().optional() }),
+]);
+export const k8sConfigSchema = z.strictObject({
+    profiles: z.record(z.string(), k8sClusterProfileSchema).optional(),
+    execCredentialPlugins: z.array(z.string()).optional(),
+    kustomize: z
+        .strictObject({
+        roots: z
+            .array(z.union([z.string(), z.strictObject({ path: z.string(), patches: z.array(renderedPatchSchema).optional() })]))
+            .optional(),
+    })
+        .optional(),
+    receipts: z
+        .strictObject({
+        namespace: z.string().optional(),
+    })
+        .optional(),
+    crds: z.array(k8sProjectCrdSourceSchema).optional(),
+});

package/dist/config.js

@@ -0,0 +1,59 @@
+/**
+ * K8s environment → cluster binding — chant #1100.
+ *
+ * Every cloud lexicon binds an environment to a scope: AWS resolves `<env>`
+ * to a CloudFormation stack, Azure treats `<env>` as the resource group.
+ * Before this, k8s bound
+ * nothing — `describeResources` shelled out to `kubectl get` with no
+ * `--context`, so `chant lifecycle diff prod --live` read whichever cluster
+ * `kubectl config current-context` happened to point at.
+ *
+ * Add this to `chant.config.ts` to pin an environment to a cluster:
+ *
+ * ```ts
+ * import type { K8sChantConfig } from "@intentius/chant-lexicon-k8s";
+ *
+ * export default {
+ *   lexicons: ["k8s"],
+ *   k8s: {
+ *     profiles: {
+ *       prod: { context: "prod-eks" },
+ *       staging: { context: "staging-eks" },
+ *     },
+ *   } satisfies K8sChantConfig,
+ * };
+ * ```
+ *
+ * `describeResources` (in `./describe-resources.ts`, and the GCP lexicon's
+ * Config Connector equivalent, which observes through the same kubectl path)
+ * resolves this via `@intentius/chant/kubectl-context`'s
+ * `resolveClusterTarget`:
+ *
+ * - A declared binding is passed explicitly to the typed client on every
+ *   read and write, regardless of what `kubectl` is ambiently pointed at
+ *   (#1488 — the binding is a selection, not a check). A bound context the
+ *   kubeconfig does not have fails with an error naming the context and the
+ *   `k8s.profiles.<env>.context` binding — never by falling back to ambient.
+ * - No binding for the environment keeps today's behavior — the ambient
+ *   context — but logs a visible note that nothing is pinned, so the
+ *   fallback is never silent. Read failures name the context that was read
+ *   and the missing binding.
+ *
+ * `ChantConfig` uses `.passthrough()` in its Zod schema so the `k8s` key is
+ * accepted at runtime without core changes, exactly like the `terraform` key
+ * (see `lexicons/terraform/src/config.ts`). The type side is the declaration
+ * merge at the bottom of this file — without it the snippet above compiles
+ * only until someone adds `satisfies ChantConfig`, which every example
+ * project does and which is the only thing type-checking the rest of the
+ * file (#1370).
+ *
+ * Deliberately out of scope here (see the issue for the full proposal):
+ * deriving the binding automatically from a declared `AWS::EKS::Cluster` /
+ * AKS / GKE cluster resource, and threading the resolved context into the
+ * Op write path (`op/activities/kubectl.ts`, `wait-for-ready.ts`) — both
+ * already accept an optional `context` a workflow author can pass, and can
+ * call `resolveClusterTarget` themselves to agree with what the read path
+ * resolved. This also keeps the binding available for #1073/#1074's future
+ * typed API client to inherit, rather than re-deriving it.
+ */
+export {};

package/dist/coverage.js

@@ -0,0 +1,27 @@
+/**
+ * Coverage analysis for the Kubernetes lexicon.
+ *
+ * Analyzes generated resources for coverage of property constraints,
+ * lifecycle attributes, and other dimensions.
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { computeCoverage, overallPct } from "@intentius/chant/codegen/coverage";
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+/**
+ * Analyze coverage of the K8s lexicon.
+ */
+export async function analyzeK8sCoverage(opts) {
+    const generatedDir = join(pkgDir, "src", "generated");
+    const lexiconJSON = readFileSync(join(generatedDir, "lexicon-k8s.json"), "utf-8");
+    const report = computeCoverage(lexiconJSON);
+    const pct = overallPct(report);
+    console.error(`K8s lexicon coverage: ${pct.toFixed(1)}%`);
+    console.error(`  Resources: ${report.resourceCount}`);
+    console.error(`  Property constraints: ${report.propertyPct.toFixed(1)}%`);
+    if (opts?.minOverall && pct < opts.minOverall) {
+        console.error(`Coverage ${pct.toFixed(1)}% is below minimum ${opts.minOverall}%`);
+        process.exit(1);
+    }
+}