@intentius/chant-lexicon-k8s 0.0.12 → 0.0.14

package/dist/skills/chant-k8s.md

@@ -126,20 +126,6 @@ kubectl port-forward pod/<pod-name> 8080:8080
 | CreateContainerError | Container config issue | `kubectl describe pod` → Events | Check volume mounts, configmap/secret refs, security context |
 | Init:CrashLoopBackOff | Init container failing | `kubectl logs -c <init-container>` | Fix init container command, check dependencies |
 
-### Resource inspection
-
-```bash
-# Get all resources in namespace
-kubectl get all -n <namespace>
-
-# YAML output for debugging
-kubectl get deployment/my-app -o yaml
-
-# Check resource usage
-kubectl top pods -l app.kubernetes.io/name=my-app
-kubectl top nodes
-```
-
 ## Production safety
 
 ### Pre-apply validation
@@ -155,22 +141,6 @@ kubectl apply -f manifests.yaml --dry-run=server
 kubectl apply -f manifests.yaml --dry-run=client
 ```
 
-### Rollback
-
-```bash
-# Check rollout history
-kubectl rollout history deployment/my-app
-
-# Undo last rollout
-kubectl rollout undo deployment/my-app
-
-# Roll back to a specific revision
-kubectl rollout undo deployment/my-app --to-revision=2
-
-# Watch rollout progress
-kubectl rollout status deployment/my-app --timeout=300s
-```
-
 ### Deployment strategies
 
 - **RollingUpdate** (default): Gradually replaces pods. Set `maxSurge` and `maxUnavailable`.
@@ -178,157 +148,42 @@ kubectl rollout status deployment/my-app --timeout=300s
 - **Canary**: Deploy a second Deployment with 1 replica + same selector labels. Route percentage via Ingress annotations or service mesh.
 - **Blue/Green**: Two full Deployments (blue/green), switch Service selector between them.
 
-## Composites
-
-Composites are higher-level functions that produce multiple coordinated K8s resources from a single call. They return plain prop objects — not class instances — that you pass to generated constructors or serialize directly.
-
-### WebApp — Deployment + Service + optional Ingress
-
-```typescript
-import { WebApp } from "@intentius/chant-lexicon-k8s";
-
-const { deployment, service, ingress } = WebApp({
-  name: "frontend",
-  image: "frontend:1.0",
-  port: 3000,
-  replicas: 3,
-  ingressHost: "frontend.example.com",
-  ingressTlsSecret: "frontend-tls",
-});
-```
-
-### StatefulApp — StatefulSet + headless Service + PVC
-
-```typescript
-import { StatefulApp } from "@intentius/chant-lexicon-k8s";
-
-const { statefulSet, service } = StatefulApp({
-  name: "postgres",
-  image: "postgres:16",
-  storageSize: "20Gi",
-  env: [{ name: "POSTGRES_DB", value: "mydb" }],
-});
-```
-
-### CronWorkload — CronJob + ServiceAccount + Role + RoleBinding
-
-```typescript
-import { CronWorkload } from "@intentius/chant-lexicon-k8s";
-
-const { cronJob, serviceAccount, role, roleBinding } = CronWorkload({
-  name: "db-backup",
-  image: "postgres:16",
-  schedule: "0 2 * * *",
-  command: ["pg_dump", "-h", "postgres", "mydb"],
-  rbacRules: [{ apiGroups: [""], resources: ["secrets"], verbs: ["get"] }],
-});
-```
-
-### AutoscaledService — Deployment + Service + HPA + PDB
-
-Production HTTP service with autoscaling, health probes, and optional topology spreading.
-
-```typescript
-import { AutoscaledService } from "@intentius/chant-lexicon-k8s";
-
-const { deployment, service, hpa, pdb } = AutoscaledService({
-  name: "api",
-  image: "api:2.0",
-  port: 8080,
-  maxReplicas: 10,
-  minReplicas: 3,
-  cpuRequest: "200m",
-  memoryRequest: "256Mi",
-  cpuLimit: "1",
-  memoryLimit: "1Gi",
-  // Probe paths — defaults: /healthz and /readyz
-  livenessPath: "/healthz",
-  readinessPath: "/readyz",
-  // Zone-aware topology spreading (default: false)
-  topologySpread: true,
-  // Custom: topologySpread: { maxSkew: 2, topologyKey: "kubernetes.io/hostname" }
-});
-```
-
-Key features:
-- **Probe paths**: `livenessPath` (default `/healthz`) and `readinessPath` (default `/readyz`) — override for apps that don't serve those routes
-- **Topology spread**: `topologySpread: true` adds zone-aware spreading (maxSkew=1, DoNotSchedule); pass an object for custom key/skew
-- **PDB minAvailable**: accepts number or string percentage (e.g., `"50%"`)
-
-### WorkerPool — Deployment + RBAC + optional ConfigMap + optional HPA
-
-Background queue workers with optional RBAC and autoscaling.
-
-```typescript
-import { WorkerPool } from "@intentius/chant-lexicon-k8s";
-
-const { deployment, serviceAccount, role, roleBinding, configMap, hpa } = WorkerPool({
-  name: "email-worker",
-  image: "worker:1.0",
-  command: ["bundle", "exec", "sidekiq"],
-  config: { REDIS_URL: "redis://redis:6379", QUEUE: "emails" },
-  autoscaling: { minReplicas: 2, maxReplicas: 20, targetCPUPercent: 60 },
-});
-```
-
-Key features:
-- **RBAC opt-out**: Pass `rbacRules: []` to skip ServiceAccount/Role/RoleBinding creation entirely. Omitting `rbacRules` (undefined) creates default rules for secrets/configmaps.
-- `serviceAccount`, `role`, `roleBinding` are optional in the result — check before use
-
-### NamespaceEnv — Namespace + ResourceQuota + LimitRange + NetworkPolicy
-
-Multi-tenant namespace provisioning with resource guardrails and network isolation.
-
-```typescript
-import { NamespaceEnv } from "@intentius/chant-lexicon-k8s";
-
-const { namespace, resourceQuota, limitRange, networkPolicy } = NamespaceEnv({
-  name: "team-alpha",
-  cpuQuota: "8",
-  memoryQuota: "16Gi",
-  maxPods: 50,
-  defaultCpuRequest: "100m",
-  defaultMemoryRequest: "128Mi",
-  defaultCpuLimit: "500m",
-  defaultMemoryLimit: "512Mi",
-  defaultDenyIngress: true,
-  defaultDenyEgress: true,
-});
-```
-
-Key features:
-- **Quota-without-limits warning**: Setting ResourceQuota without LimitRange defaults emits a warning — pods without explicit resource requests will fail to schedule
-- **Network policies**: `defaultDenyIngress` (default true), `defaultDenyEgress` (default false) — can be combined or used individually
-
-### NodeAgent — DaemonSet + ServiceAccount + ClusterRole + ClusterRoleBinding + optional ConfigMap
-
-Per-node agents (log collectors, security scanners, monitoring exporters).
-
-```typescript
-import { NodeAgent } from "@intentius/chant-lexicon-k8s";
-
-const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap } = NodeAgent({
-  name: "log-collector",
-  image: "fluentd:v1.16",
-  port: 24224,
-  hostPaths: [
-    { name: "varlog", hostPath: "/var/log", mountPath: "/var/log" },
-  ],
-  config: { "fluent.conf": "..." },
-  rbacRules: [{ apiGroups: [""], resources: ["pods", "namespaces"], verbs: ["get", "list", "watch"] }],
-  cpuRequest: "50m",       // default: 50m
-  memoryRequest: "64Mi",   // default: 64Mi
-  cpuLimit: "200m",        // default: 200m
-  memoryLimit: "128Mi",    // default: 128Mi
-  namespace: "monitoring",
-});
-```
-
-Key features:
-- **Container resources**: Always set with sensible defaults (50m/64Mi requests, 200m/128Mi limits) — override per-agent
-- **Host paths**: Mounted read-only by default; set `readOnly: false` to enable writes
-- **Tolerations**: `tolerateAllTaints: true` (default) ensures agent runs on every node
-- Uses **ClusterRole/ClusterRoleBinding** (cluster-scoped) for node-level access
+## Choosing the Right Composite
+
+Composites are higher-level functions that produce multiple coordinated K8s resources from a single call. They return plain prop objects — not class instances.
+
+### Decision Tree
+
+| Need | Composite | Resources |
+|------|-----------|-----------|
+| Stateless web app | **WebApp** | Deployment + Service + optional Ingress + optional PDB |
+| Stateful database/cache | **StatefulApp** | StatefulSet + headless Service + PVC + optional PDB |
+| Production HTTP service with autoscaling | **AutoscaledService** | Deployment + Service + HPA + PDB |
+| Background queue workers | **WorkerPool** | Deployment + RBAC + optional ConfigMap + optional HPA + optional PDB |
+| Scheduled jobs | **CronWorkload** | CronJob + RBAC |
+| One-shot batch jobs | **BatchJob** | Job + optional RBAC |
+| App with ConfigMap/Secret mounts | **ConfiguredApp** | Deployment + Service + optional ConfigMap |
+| Multi-container sidecar patterns | **SidecarApp** | Deployment + Service |
+| App with Prometheus monitoring | **MonitoredService** | Deployment + Service + ServiceMonitor + optional PrometheusRule |
+| App with fine-grained network policies | **NetworkIsolatedApp** | Deployment + Service + NetworkPolicy |
+| Namespace with quotas and isolation | **NamespaceEnv** | Namespace + ResourceQuota + LimitRange + NetworkPolicy |
+| Per-node agent (custom) | **NodeAgent** | DaemonSet + RBAC + optional ConfigMap |
+| Multi-host TLS Ingress (cert-manager) | **SecureIngress** | Ingress + optional Certificate |
+| EKS IRSA ServiceAccount | **IrsaServiceAccount** | ServiceAccount + optional RBAC |
+| AWS ALB Ingress | **AlbIngress** | Ingress with ALB annotations |
+| EBS StorageClass | **EbsStorageClass** | StorageClass (ebs.csi.aws.com) |
+| EFS StorageClass | **EfsStorageClass** | StorageClass (efs.csi.aws.com) |
+| Fluent Bit for CloudWatch | **FluentBitAgent** | DaemonSet + RBAC + ConfigMap |
+| ExternalDNS for Route53 | **ExternalDnsAgent** | Deployment + IRSA SA + ClusterRole |
+| ADOT for CloudWatch/X-Ray | **AdotCollector** | DaemonSet + RBAC + ConfigMap |
+
+### Hardening options (available on Deployment-based composites)
+
+- `minAvailable` — creates a PodDisruptionBudget (WebApp, StatefulApp, WorkerPool; AutoscaledService always has one)
+- `initContainers` — run before main containers (WebApp, StatefulApp, AutoscaledService, ConfiguredApp, SidecarApp)
+- `securityContext` — container security settings (WebApp, StatefulApp, AutoscaledService, WorkerPool)
+- `terminationGracePeriodSeconds` — graceful shutdown (WebApp, StatefulApp, AutoscaledService, WorkerPool)
+- `priorityClassName` — pod scheduling priority (WebApp, StatefulApp, AutoscaledService, WorkerPool)
 
 ### Common patterns across all composites
 
@@ -337,49 +192,6 @@ Key features:
 - Pass `namespace: "prod"` to set namespace on all namespaced resources
 - Pass `env: [{ name: "KEY", value: "val" }]` for container environment variables
 
-## Namespace management
-
-Use the **NamespaceEnv** composite (above) to manage namespaces declaratively. For manual kubectl management:
-
-```bash
-# Create namespace
-kubectl create namespace my-project
-
-# Set default resource quotas
-kubectl apply -f - <<EOF
-apiVersion: v1
-kind: ResourceQuota
-metadata:
-  name: default-quota
-  namespace: my-project
-spec:
-  hard:
-    requests.cpu: "4"
-    requests.memory: 8Gi
-    limits.cpu: "8"
-    limits.memory: 16Gi
-    pods: "20"
-EOF
-
-# Set default container limits via LimitRange
-kubectl apply -f - <<EOF
-apiVersion: v1
-kind: LimitRange
-metadata:
-  name: default-limits
-  namespace: my-project
-spec:
-  limits:
-  - default:
-      cpu: 500m
-      memory: 256Mi
-    defaultRequest:
-      cpu: 100m
-      memory: 128Mi
-    type: Container
-EOF
-```
-
 ## Troubleshooting reference table
 
 | Symptom | Likely cause | Resolution |
@@ -388,11 +200,8 @@ EOF
 | Pod stuck in Pending | PVC not bound | Check StorageClass exists, PV available |
 | Pod stuck in Pending | Node selector/affinity mismatch | Verify node labels match selectors |
 | Pod stuck in ContainerCreating | ConfigMap/Secret not found | Ensure referenced ConfigMaps/Secrets exist |
-| Pod stuck in ContainerCreating | Volume mount failure | Check PVC status, CSI driver health |
 | Service returns 503 | No ready endpoints | Check pod readiness probes, selector match |
-| Service returns 503 | Wrong port configuration | Verify targetPort matches containerPort |
 | Ingress returns 404 | Backend service not found | Check Ingress rules, service name/port |
-| Ingress returns 404 | Wrong path matching | Check pathType (Prefix vs Exact) |
 | HPA not scaling | Metrics server not installed | Install metrics-server |
 | HPA not scaling | Resource requests not set | Add CPU/memory requests to containers |
 | CronJob not running | Invalid cron expression | Validate cron syntax (5-field format) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "license": "Apache-2.0",
   "type": "module",
   "files": ["src/", "dist/"],
@@ -22,7 +22,7 @@
   "prepack": "bun run generate && bun run bundle && bun run validate"
 },
 "dependencies": {
-  "@intentius/chant": "0.0.11"
+  "@intentius/chant": "0.0.13"
 },
 "devDependencies": {
   "typescript": "^5.9.3"

package/src/codegen/docs.ts

@@ -18,7 +18,7 @@ function serviceFromType(resourceType: string): string {
 
 const overview = `The **Kubernetes** lexicon provides typed constructors for Kubernetes resource
 manifests. It covers Deployments, Services, ConfigMaps, StatefulSets, Jobs,
-Ingress, RBAC, and 50+ additional resource and property types.
+Ingress, RBAC, and 147 resources and 50 property types.
 
 New? Start with the [Getting Started](/chant/lexicons/k8s/getting-started/) guide.
 
@@ -64,7 +64,7 @@ export const service = new Service({
 });
 \`\`\`
 
-The lexicon provides **50+ resource types** (Deployment, Service, ConfigMap, StatefulSet, and more), **35+ property types** (Container, Probe, Volume, SecurityContext, etc.), and composites (WebApp, StatefulApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent) for common patterns.
+The lexicon provides **147 resource types** (Deployment, Service, ConfigMap, StatefulSet, and more), **50 property types** (Container, Probe, Volume, SecurityContext, etc.), and composites (WebApp, StatefulApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent) for common patterns.
 `;
 
 const outputFormat = `The Kubernetes lexicon serializes resources into **multi-document YAML** with
@@ -76,7 +76,7 @@ structure: \`apiVersion\`, \`kind\`, \`metadata\`, and \`spec\`.
 Run \`chant build\` to produce Kubernetes manifests from your declarations:
 
 \`\`\`bash
-chant build
+chant build src/ --output dist/manifests.yaml
 # Writes dist/manifests.yaml
 \`\`\`
 
@@ -134,7 +134,7 @@ export async function generateDocs(opts?: { verbose?: boolean }): Promise<void>
     overview,
     outputFormat,
     serviceFromType,
-    suppressPages: ["pseudo-parameters"],
+    suppressPages: ["pseudo-parameters", "rules"],
     extraPages: [
       {
         slug: "getting-started",

package/src/composites/adot-collector.ts

@@ -0,0 +1,239 @@
+/**
+ * AdotCollector composite — DaemonSet + RBAC + ConfigMap for AWS Distro for OpenTelemetry.
+ *
+ * @eks ADOT collector for CloudWatch and X-Ray. NodeAgent specialization
+ * with pre-configured pipelines for AWS observability.
+ */
+
+export interface AdotCollectorProps {
+  /** AWS region. */
+  region: string;
+  /** EKS cluster name. */
+  clusterName: string;
+  /** Exporters to enable (default: ["cloudwatch", "xray"]). */
+  exporters?: ("cloudwatch" | "xray" | "prometheus")[];
+  /** Agent name (default: "adot-collector"). */
+  name?: string;
+  /** ADOT image (default: "public.ecr.aws/aws-observability/aws-otel-collector:latest"). */
+  image?: string;
+  /** Namespace (default: "amazon-metrics"). */
+  namespace?: string;
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** CPU request (default: "100m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "256Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "500m"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "512Mi"). */
+  memoryLimit?: string;
+  /** IAM Role ARN for IRSA (adds eks.amazonaws.com/role-arn annotation to ServiceAccount). */
+  iamRoleArn?: string;
+}
+
+export interface AdotCollectorResult {
+  daemonSet: Record<string, unknown>;
+  serviceAccount: Record<string, unknown>;
+  clusterRole: Record<string, unknown>;
+  clusterRoleBinding: Record<string, unknown>;
+  configMap: Record<string, unknown>;
+}
+
+/**
+ * Create an AdotCollector composite — returns prop objects for
+ * a DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, and ConfigMap.
+ *
+ * @eks
+ * @example
+ * ```ts
+ * import { AdotCollector } from "@intentius/chant-lexicon-k8s";
+ *
+ * const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap } = AdotCollector({
+ *   region: "us-east-1",
+ *   clusterName: "my-cluster",
+ *   exporters: ["cloudwatch", "xray"],
+ * });
+ * ```
+ */
+export function AdotCollector(props: AdotCollectorProps): AdotCollectorResult {
+  const {
+    region,
+    clusterName,
+    exporters = ["cloudwatch", "xray"],
+    name = "adot-collector",
+    image = "public.ecr.aws/aws-observability/aws-otel-collector:latest",
+    namespace = "amazon-metrics",
+    labels: extraLabels = {},
+    cpuRequest = "100m",
+    memoryRequest = "256Mi",
+    cpuLimit = "500m",
+    memoryLimit = "512Mi",
+    iamRoleArn,
+  } = props;
+
+  const saName = `${name}-sa`;
+  const clusterRoleName = `${name}-role`;
+  const bindingName = `${name}-binding`;
+  const configMapName = `${name}-config`;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+
+  // Build ADOT config YAML
+  const exporterConfigs: string[] = [];
+  const exporterNames: string[] = [];
+
+  if (exporters.includes("cloudwatch")) {
+    exporterConfigs.push(`  awsemf:
+    region: ${region}
+    namespace: ContainerInsights
+    log_group_name: '/aws/containerinsights/${clusterName}/performance'
+    dimension_rollup_option: NoDimensionRollup`);
+    exporterNames.push("awsemf");
+  }
+
+  if (exporters.includes("xray")) {
+    exporterConfigs.push(`  awsxray:
+    region: ${region}`);
+    exporterNames.push("awsxray");
+  }
+
+  if (exporters.includes("prometheus")) {
+    exporterConfigs.push(`  prometheusremotewrite:
+    endpoint: http://prometheus:9090/api/v1/write`);
+    exporterNames.push("prometheusremotewrite");
+  }
+
+  const adotConfig = `receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 30s
+    send_batch_size: 8192
+
+exporters:
+${exporterConfigs.join("\n")}
+
+service:
+  pipelines:
+    metrics:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [${exporterNames.join(", ")}]
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [${exporterNames.filter((e) => e !== "awsemf").join(", ") || "awsxray"}]
+`;
+
+  const container: Record<string, unknown> = {
+    name,
+    image,
+    command: ["--config=/etc/adot/config.yaml"],
+    ports: [
+      { containerPort: 4317, name: "otlp-grpc" },
+      { containerPort: 4318, name: "otlp-http" },
+    ],
+    resources: {
+      requests: { cpu: cpuRequest, memory: memoryRequest },
+      limits: { cpu: cpuLimit, memory: memoryLimit },
+    },
+    volumeMounts: [
+      { name: "config", mountPath: "/etc/adot", readOnly: true },
+    ],
+  };
+
+  const daemonSetProps: Record<string, unknown> = {
+    metadata: {
+      name,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+    },
+    spec: {
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          containers: [container],
+          volumes: [
+            { name: "config", configMap: { name: configMapName } },
+          ],
+          tolerations: [{ operator: "Exists" }],
+        },
+      },
+    },
+  };
+
+  const serviceAccountProps: Record<string, unknown> = {
+    metadata: {
+      name: saName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+      ...(iamRoleArn ? { annotations: { "eks.amazonaws.com/role-arn": iamRoleArn } } : {}),
+    },
+  };
+
+  const clusterRoleProps: Record<string, unknown> = {
+    metadata: {
+      name: clusterRoleName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    rules: [
+      { apiGroups: [""], resources: ["pods", "nodes", "endpoints"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["apps"], resources: ["replicasets"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["batch"], resources: ["jobs"], verbs: ["get", "list", "watch"] },
+      { apiGroups: [""], resources: ["nodes/proxy"], verbs: ["get"] },
+      { apiGroups: [""], resources: ["nodes/stats", "configmaps", "events"], verbs: ["create", "get"] },
+      { apiGroups: [""], resources: ["configmaps"], verbs: ["get", "update", "create"], resourceNames: ["otel-container-insight-clusterleader"] },
+    ],
+  };
+
+  const clusterRoleBindingProps: Record<string, unknown> = {
+    metadata: {
+      name: bindingName,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+    },
+    roleRef: {
+      apiGroup: "rbac.authorization.k8s.io",
+      kind: "ClusterRole",
+      name: clusterRoleName,
+    },
+    subjects: [
+      {
+        kind: "ServiceAccount",
+        name: saName,
+        namespace,
+      },
+    ],
+  };
+
+  const configMapProps: Record<string, unknown> = {
+    metadata: {
+      name: configMapName,
+      namespace,
+      labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+    },
+    data: {
+      "config.yaml": adotConfig,
+    },
+  };
+
+  return {
+    daemonSet: daemonSetProps,
+    serviceAccount: serviceAccountProps,
+    clusterRole: clusterRoleProps,
+    clusterRoleBinding: clusterRoleBindingProps,
+    configMap: configMapProps,
+  };
+}