@intentius/chant-lexicon-k8s 0.0.13 → 0.0.15

package/dist/integrity.json

@@ -1,32 +1,37 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "4ed66408d8e29abe",
+    "manifest.json": "490e9ca9417db298",
     "meta.json": "1ce194f36f9b5f90",
     "types/index.d.ts": "beec4cc869064186",
     "rules/hardcoded-namespace.ts": "54b216c71018e101",
-    "rules/wk8006.ts": "6e04f754f79f076e",
     "rules/wk8201.ts": "4dbbd20e21b5fa04",
-    "rules/wk8103.ts": "e5d6a506d966e312",
-    "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
+    "rules/wk8204.ts": "9244d6fdd6d2f7d",
     "rules/wk8301.ts": "283265ab0c5b8511",
-    "rules/wk8105.ts": "8dbcfe399f23656a",
+    "rules/wk8306.ts": "5338575bfb0f9251",
+    "rules/wk8102.ts": "78d4aac387107b56",
+    "rules/wk8305.ts": "5c4b9482a0f3b91d",
     "rules/wk8101.ts": "f8ffcf6e5c89076b",
     "rules/wk8302.ts": "a80d1eab37c0dbe4",
+    "rules/wk8005.ts": "a9a1b93b80f3aa51",
+    "rules/wk8209.ts": "820df53f304e0a59",
     "rules/wk8203.ts": "f5bf17539c0428c5",
-    "rules/wk8042.ts": "6064c84481ae8551",
-    "rules/wk8202.ts": "6bd950ae2128256c",
-    "rules/wk8207.ts": "6f2bc621d530afa2",
     "rules/wk8104.ts": "94bd75c16b8d50b7",
+    "rules/wk8303.ts": "c545464e2af8fbb9",
+    "rules/wk8103.ts": "e5d6a506d966e312",
     "rules/wk8205.ts": "d000527c6371a05",
+    "rules/wk8042.ts": "6064c84481ae8551",
+    "rules/wk8006.ts": "6e04f754f79f076e",
     "rules/wk8041.ts": "4df512c93caaef50",
-    "rules/wk8102.ts": "78d4aac387107b56",
-    "rules/wk8005.ts": "a9a1b93b80f3aa51",
-    "rules/wk8303.ts": "c545464e2af8fbb9",
-    "rules/wk8204.ts": "31c3f8eac8455795",
+    "rules/wk8304.ts": "f51bf894c5a08dbe",
+    "rules/wk8202.ts": "6bd950ae2128256c",
     "rules/wk8208.ts": "1133f9e53c174ae9",
-    "rules/wk8209.ts": "820df53f304e0a59",
-    "skills/chant-k8s.md": "f1c4ed163f8fa84c"
+    "rules/wk8105.ts": "8dbcfe399f23656a",
+    "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
+    "rules/wk8207.ts": "6f2bc621d530afa2",
+    "skills/chant-k8s.md": "c7db82c3ba37c78",
+    "skills/chant-k8s-eks.md": "f79f31f058c7f2ed",
+    "skills/chant-k8s-patterns.md": "c5151ed799145c4b"
   },
-  "composite": "c630f44a73860007"
+  "composite": "2a6c7f09f87d9a38"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/rules/wk8204.ts

@@ -4,6 +4,10 @@
  * Containers should set securityContext.runAsNonRoot to true at either
  * the container level or pod level. Running as root inside a container
  * increases the blast radius of a container breakout.
+ *
+ * Additionally warns when runAsNonRoot: true is set but no explicit
+ * runAsUser is provided — without a numeric UID, K8s relies on the
+ * image's USER directive, which may be root (UID 0).
  */
 
 import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
@@ -30,13 +34,17 @@ export const wk8204: PostSynthCheck = {
         // Check pod-level securityContext
         const podSecCtx = podSpec.securityContext as Record<string, unknown> | undefined;
         const podRunAsNonRoot = podSecCtx?.runAsNonRoot === true;
+        const podRunAsUser = podSecCtx?.runAsUser;
 
         const containers = extractContainers(manifest);
         for (const container of containers) {
           const secCtx = container.securityContext;
           const containerRunAsNonRoot = secCtx?.runAsNonRoot === true;
+          const containerRunAsUser = secCtx?.runAsUser;
+
+          const hasRunAsNonRoot = podRunAsNonRoot || containerRunAsNonRoot;
 
-          if (!podRunAsNonRoot && !containerRunAsNonRoot) {
+          if (!hasRunAsNonRoot) {
             diagnostics.push({
               checkId: "WK8204",
               severity: "warning",
@@ -44,6 +52,30 @@ export const wk8204: PostSynthCheck = {
               entity: resourceName,
               lexicon: "k8s",
             });
+            continue;
+          }
+
+          // runAsNonRoot is true — check for explicit runAsUser
+          const effectiveRunAsUser = containerRunAsUser ?? podRunAsUser;
+
+          if (effectiveRunAsUser === 0) {
+            // Contradictory: runAsNonRoot: true + runAsUser: 0
+            diagnostics.push({
+              checkId: "WK8204",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has runAsNonRoot: true but runAsUser: 0 — these settings are contradictory and the container will fail to start`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          } else if (effectiveRunAsUser === undefined || effectiveRunAsUser === null) {
+            // runAsNonRoot: true but no explicit UID
+            diagnostics.push({
+              checkId: "WK8204",
+              severity: "warning",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has runAsNonRoot: true but no explicit runAsUser — set a numeric UID to ensure the container doesn't run as root`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
           }
         }
       }

package/dist/rules/wk8304.ts

@@ -0,0 +1,70 @@
+/**
+ * WK8304: SSL Redirect Without Certificate
+ *
+ * Flags Ingress resources that have `alb.ingress.kubernetes.io/ssl-redirect`
+ * annotation set but are missing `alb.ingress.kubernetes.io/certificate-arn`
+ * or don't have HTTPS in their listen-ports.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+
+export const wk8304: PostSynthCheck = {
+  id: "WK8304",
+  description: "SSL redirect without certificate — ssl-redirect annotation requires a valid certificate-arn and HTTPS listen-ports",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "Ingress") continue;
+
+        const annotations = manifest.metadata?.annotations as Record<string, string> | undefined;
+        if (!annotations) continue;
+
+        const sslRedirect = annotations["alb.ingress.kubernetes.io/ssl-redirect"];
+        if (!sslRedirect) continue;
+
+        const resourceName = manifest.metadata?.name ?? "Ingress";
+        const certArn = annotations["alb.ingress.kubernetes.io/certificate-arn"];
+
+        if (!certArn) {
+          diagnostics.push({
+            checkId: "WK8304",
+            severity: "warning",
+            message: `Ingress "${resourceName}" has ssl-redirect annotation but no certificate-arn — HTTPS redirect will fail without a TLS certificate`,
+            entity: resourceName,
+            lexicon: "k8s",
+          });
+          continue;
+        }
+
+        // Check listen-ports includes HTTPS
+        const listenPorts = annotations["alb.ingress.kubernetes.io/listen-ports"];
+        if (listenPorts) {
+          try {
+            const ports = JSON.parse(listenPorts) as Array<Record<string, number>>;
+            const hasHttps = ports.some((p) => "HTTPS" in p);
+            if (!hasHttps) {
+              diagnostics.push({
+                checkId: "WK8304",
+                severity: "warning",
+                message: `Ingress "${resourceName}" has ssl-redirect but listen-ports does not include HTTPS`,
+                entity: resourceName,
+                lexicon: "k8s",
+              });
+            }
+          } catch {
+            // Can't parse listen-ports — skip this check
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/rules/wk8305.ts

@@ -0,0 +1,115 @@
+/**
+ * WK8305: Ingress Port Not Matching Service
+ *
+ * Flags Ingress backends whose `service.port.number` does not match
+ * any declared port on the referenced Service in the manifest set.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests } from "./k8s-helpers";
+import type { K8sManifest } from "./k8s-helpers";
+
+export const wk8305: PostSynthCheck = {
+  id: "WK8305",
+  description: "Ingress port not matching Service — backend port must match a declared Service port",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      // Build a map of Service name+namespace → set of port numbers
+      const servicePorts = collectServicePorts(manifests);
+
+      for (const manifest of manifests) {
+        if (manifest.kind !== "Ingress") continue;
+
+        const ingressName = manifest.metadata?.name ?? "Ingress";
+        const ingressNamespace = manifest.metadata?.namespace ?? "default";
+        const spec = manifest.spec;
+        if (!spec) continue;
+
+        const rules = spec.rules as Array<Record<string, unknown>> | undefined;
+        if (!rules) continue;
+
+        for (const rule of rules) {
+          const http = rule.http as Record<string, unknown> | undefined;
+          if (!http) continue;
+
+          const paths = http.paths as Array<Record<string, unknown>> | undefined;
+          if (!paths) continue;
+
+          for (const pathEntry of paths) {
+            const backend = pathEntry.backend as Record<string, unknown> | undefined;
+            if (!backend) continue;
+
+            const service = backend.service as Record<string, unknown> | undefined;
+            if (!service) continue;
+
+            const svcName = service.name as string | undefined;
+            const port = service.port as Record<string, unknown> | undefined;
+            const portNumber = port?.number as number | undefined;
+
+            if (!svcName || portNumber === undefined) continue;
+
+            // Look up the Service in the manifest set
+            const key = `${ingressNamespace}/${svcName}`;
+            const knownPorts = servicePorts.get(key);
+
+            // Skip if the Service is not in the manifest set (external service)
+            if (!knownPorts) continue;
+
+            if (!knownPorts.has(portNumber)) {
+              diagnostics.push({
+                checkId: "WK8305",
+                severity: "warning",
+                message: `Ingress "${ingressName}" references Service "${svcName}" port ${portNumber}, but the Service only declares ports [${[...knownPorts].join(", ")}]`,
+                entity: ingressName,
+                lexicon: "k8s",
+              });
+            }
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};
+
+/**
+ * Collect port numbers from all Service manifests, keyed by namespace/name.
+ */
+function collectServicePorts(manifests: K8sManifest[]): Map<string, Set<number>> {
+  const result = new Map<string, Set<number>>();
+
+  for (const manifest of manifests) {
+    if (manifest.kind !== "Service") continue;
+
+    const name = manifest.metadata?.name;
+    const namespace = manifest.metadata?.namespace ?? "default";
+    if (!name) continue;
+
+    const key = `${namespace}/${name}`;
+    const ports = new Set<number>();
+
+    const spec = manifest.spec;
+    if (spec) {
+      const specPorts = spec.ports as Array<Record<string, unknown>> | undefined;
+      if (specPorts) {
+        for (const p of specPorts) {
+          const port = p.port as number | undefined;
+          if (port !== undefined) {
+            ports.add(port);
+          }
+        }
+      }
+    }
+
+    result.set(key, ports);
+  }
+
+  return result;
+}

package/dist/rules/wk8306.ts

@@ -0,0 +1,50 @@
+/**
+ * WK8306: Container Command Starts With Flag
+ *
+ * If `command[0]` starts with `-` or `--`, it's almost certainly a mistake —
+ * the first element should be the binary/entrypoint, flags belong in `args`.
+ * This causes OCI runtime errors because the container runtime tries to
+ * execute the flag as a binary.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { getPrimaryOutput, parseK8sManifests, extractContainers, WORKLOAD_KINDS } from "./k8s-helpers";
+
+export const wk8306: PostSynthCheck = {
+  id: "WK8306",
+  description: "Container command starts with flag — first element should be a binary, not a flag",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [, output] of ctx.outputs) {
+      const yaml = getPrimaryOutput(output);
+      const manifests = parseK8sManifests(yaml);
+
+      for (const manifest of manifests) {
+        if (!manifest.kind || !WORKLOAD_KINDS.has(manifest.kind)) continue;
+
+        const resourceName = manifest.metadata?.name ?? manifest.kind;
+        const containers = extractContainers(manifest);
+
+        for (const container of containers) {
+          const command = (container as Record<string, unknown>).command as unknown[] | undefined;
+          if (!Array.isArray(command) || command.length === 0) continue;
+
+          const firstArg = String(command[0]);
+          if (firstArg.startsWith("-")) {
+            diagnostics.push({
+              checkId: "WK8306",
+              severity: "error",
+              message: `Container "${container.name ?? "(unnamed)"}" in ${manifest.kind} "${resourceName}" has command[0]="${firstArg}" which starts with a flag — the first element should be the binary, flags belong in args`,
+              entity: resourceName,
+              lexicon: "k8s",
+            });
+          }
+        }
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/dist/skills/chant-k8s-eks.md

@@ -0,0 +1,156 @@
+---
+skill: chant-k8s-eks
+description: EKS-specific Kubernetes patterns and composites
+user-invocable: true
+---
+
+# EKS Kubernetes Patterns
+
+## EKS Composites Overview
+
+These composites produce K8s YAML with EKS-specific annotations and configurations.
+
+### IrsaServiceAccount — ServiceAccount with IAM Role annotation
+
+```typescript
+import { IrsaServiceAccount } from "@intentius/chant-lexicon-k8s";
+
+const { serviceAccount, role, roleBinding } = IrsaServiceAccount({
+  name: "app-sa",
+  iamRoleArn: "arn:aws:iam::123456789012:role/my-app-role",
+  rbacRules: [
+    { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+  ],
+  namespace: "prod",
+});
+```
+
+### AlbIngress — Ingress with AWS ALB Controller annotations
+
+```typescript
+import { AlbIngress } from "@intentius/chant-lexicon-k8s";
+
+const { ingress } = AlbIngress({
+  name: "api-ingress",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+    },
+  ],
+  scheme: "internet-facing",
+  certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
+  groupName: "shared-alb",
+  healthCheckPath: "/healthz",
+});
+```
+
+Features:
+- Auto-sets `alb.ingress.kubernetes.io/*` annotations
+- SSL redirect enabled by default when `certificateArn` set
+- `groupName` for shared ALB across multiple Ingresses
+- `wafAclArn` for WAFv2 integration
+
+### EbsStorageClass — StorageClass for EBS CSI
+
+```typescript
+import { EbsStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = EbsStorageClass({
+  name: "gp3-encrypted",
+  type: "gp3",
+  encrypted: true,
+  iops: "3000",
+  throughput: "125",
+});
+```
+
+### EfsStorageClass — StorageClass for EFS CSI (ReadWriteMany)
+
+```typescript
+import { EfsStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = EfsStorageClass({
+  name: "efs-shared",
+  fileSystemId: "fs-12345678",
+});
+```
+
+Use EFS when you need ReadWriteMany (shared across pods/nodes). Use EBS for ReadWriteOnce (single pod).
+
+### FluentBitAgent — DaemonSet for CloudWatch logging
+
+```typescript
+import { FluentBitAgent } from "@intentius/chant-lexicon-k8s";
+
+const result = FluentBitAgent({
+  logGroup: "/aws/eks/my-cluster/containers",
+  region: "us-east-1",
+  clusterName: "my-cluster",
+});
+```
+
+### ExternalDnsAgent — ExternalDNS for Route53
+
+```typescript
+import { ExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
+
+const result = ExternalDnsAgent({
+  iamRoleArn: "arn:aws:iam::123456789012:role/external-dns-role",
+  domainFilters: ["example.com"],
+  txtOwnerId: "my-cluster",
+});
+```
+
+### AdotCollector — ADOT for CloudWatch/X-Ray
+
+```typescript
+import { AdotCollector } from "@intentius/chant-lexicon-k8s";
+
+const result = AdotCollector({
+  region: "us-east-1",
+  clusterName: "my-cluster",
+  exporters: ["cloudwatch", "xray"],
+});
+```
+
+## Pod Identity vs IRSA
+
+| Feature | IRSA | Pod Identity |
+|---------|------|-------------|
+| K8s annotation needed | Yes (`eks.amazonaws.com/role-arn`) | No |
+| Composite available | **IrsaServiceAccount** | None needed |
+| Setup | OIDC provider + IAM role trust policy | EKS Pod Identity Agent add-on + association |
+| When to use | Existing clusters, broad compatibility | New clusters (EKS 1.28+), simpler management |
+
+For Pod Identity, no K8s-side composite is needed — configure the association via AWS API/CloudFormation and use a plain ServiceAccount.
+
+## Karpenter
+
+Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter NodePool and EC2NodeClass are simple CRDs — use CRD import rather than composites:
+
+```bash
+# Import Karpenter CRDs into your chant project
+chant import --url https://raw.githubusercontent.com/aws/karpenter/main/pkg/apis/crds/karpenter.sh_nodepools.yaml
+```
+
+## Fargate Considerations
+
+When running on EKS Fargate:
+- **No DaemonSets** — FluentBitAgent and AdotCollector cannot run on Fargate nodes
+- **No hostPath volumes** — use EFS for shared storage
+- **No privileged containers** — security context restrictions apply
+- For Fargate logging, use the built-in Fluent Bit log router (Fargate logging configuration)
+
+## EKS Add-ons
+
+Common add-ons managed via AWS (not K8s manifests):
+- **vpc-cni** — Amazon VPC CNI plugin
+- **coredns** — Cluster DNS
+- **kube-proxy** — Network proxy
+- **aws-ebs-csi-driver** — EBS CSI driver (required for EbsStorageClass)
+- **aws-efs-csi-driver** — EFS CSI driver (required for EfsStorageClass)
+- **adot** — AWS Distro for OpenTelemetry (alternative to AdotCollector composite)
+- **aws-guardduty-agent** — Runtime threat detection
+
+Configure add-ons via the AWS lexicon (`@intentius/chant-lexicon-aws`) CloudFormation resources.