@intentius/chant-lexicon-k8s 0.0.12

package/dist/skills/chant-k8s.md

@@ -0,0 +1,433 @@
+---
+skill: chant-k8s
+description: Build, validate, and deploy Kubernetes manifests from a chant project
+user-invocable: true
+---
+
+# Kubernetes Operational Playbook
+
+## How chant and Kubernetes relate
+
+chant is a **synthesis-only** tool — it compiles TypeScript source files into Kubernetes YAML manifests. chant does NOT call the Kubernetes API. Your job as an agent is to bridge the two:
+
+- Use **chant** for: build, lint, diff (local YAML comparison)
+- Use **kubectl / k8s API** for: apply, rollback, monitoring, troubleshooting
+
+The source of truth for infrastructure is the TypeScript in `src/`. The generated YAML manifests are intermediate artifacts — never edit them by hand.
+
+## Scaffolding a new project
+
+### Initialize with a template
+
+```bash
+chant init --lexicon k8s                          # default: Deployment + Service
+chant init --lexicon k8s --template microservice   # Deployment + Service + HPA + PDB
+chant init --lexicon k8s --template stateful       # StatefulSet + PVC + Service
+```
+
+### Available templates
+
+| Template | What it generates | Best for |
+|----------|-------------------|----------|
+| *(default)* | Deployment + Service | Simple stateless apps |
+| `microservice` | Deployment + Service + HPA + PDB | Production microservices |
+| `stateful` | StatefulSet + PVC + headless Service | Databases, caches |
+
+## Build and validate
+
+### Build manifests
+
+```bash
+chant build src/ --output manifests.yaml
+```
+
+Options:
+- `--format yaml` — emit YAML (default for K8s)
+- `--watch` — rebuild on source changes
+- `--output <path>` — write to a specific file
+
+### Lint the source
+
+```bash
+chant lint src/
+```
+
+### What each step catches
+
+| Step | Catches | When to run |
+|------|---------|-------------|
+| `chant lint` | Hardcoded namespaces (WK8001) | Every edit |
+| `chant build` | Post-synth: secrets in env (WK8005), latest tags (WK8006), API keys (WK8041), missing probes (WK8301), no resource limits (WK8201), privileged containers (WK8202), and more | Before apply |
+| `kubectl --dry-run=server` | K8s API validation: schema errors, admission webhooks | Before production apply |
+
+## Deploying to Kubernetes
+
+### Apply manifests
+
+```bash
+# Build
+chant build src/ --output manifests.yaml
+
+# Dry run first
+kubectl apply -f manifests.yaml --dry-run=server
+
+# Apply
+kubectl apply -f manifests.yaml
+```
+
+### Check rollout status
+
+```bash
+kubectl rollout status deployment/my-app
+```
+
+### Rollback
+
+```bash
+kubectl rollout undo deployment/my-app
+kubectl rollout undo deployment/my-app --to-revision=2
+```
+
+## Debugging strategies
+
+### Check pod status and events
+
+```bash
+# Overview
+kubectl get pods -l app.kubernetes.io/name=my-app
+kubectl get events --sort-by=.lastTimestamp -n <namespace>
+
+# Deep dive into a specific pod
+kubectl describe pod <pod-name>
+
+# Logs (current and previous crash)
+kubectl logs <pod-name>
+kubectl logs <pod-name> --previous
+kubectl logs <pod-name> -c <container-name>  # specific container
+kubectl logs deployment/my-app --all-containers
+
+# Debug containers (K8s 1.25+)
+kubectl debug <pod-name> -it --image=busybox --target=<container>
+
+# Port-forwarding for local testing
+kubectl port-forward svc/my-app 8080:80
+kubectl port-forward pod/<pod-name> 8080:8080
+```
+
+### Common error patterns
+
+| Status | Meaning | Diagnostic command | Typical fix |
+|--------|---------|-------------------|-------------|
+| Pending | Not scheduled | `kubectl describe pod` → Events | Check resource requests, node selectors, taints, PVC binding |
+| CrashLoopBackOff | App crashing on start | `kubectl logs --previous` | Fix app startup, check probe config, increase initialDelaySeconds |
+| ImagePullBackOff | Image not found | `kubectl describe pod` → Events | Verify image name/tag, check imagePullSecrets, registry auth |
+| OOMKilled | Out of memory | `kubectl describe pod` → Last State | Increase memory limit, profile app memory usage |
+| Evicted | Node disk/memory pressure | `kubectl describe node` | Increase limits, add node capacity, check for log/tmp bloat |
+| 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
+
+```bash
+# Always diff before applying
+kubectl diff -f manifests.yaml
+
+# Server-side dry run (validates with admission webhooks)
+kubectl apply -f manifests.yaml --dry-run=server
+
+# Client-side dry run (fast, but no webhook validation)
+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`.
+- **Recreate**: All pods terminated before new ones created. Use for stateful apps that cannot run multiple versions.
+- **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
+
+### Common patterns across all composites
+
+- All resources carry `app.kubernetes.io/name`, `app.kubernetes.io/managed-by: chant`, and `app.kubernetes.io/component` labels
+- Pass `labels: { team: "platform" }` to add extra labels to all resources
+- 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 |
+|---------|-------------|------------|
+| Pod stuck in Pending | Insufficient CPU/memory on nodes | Scale up cluster or reduce resource requests |
+| 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) |
+| NetworkPolicy blocking | Default deny applied | Add explicit allow rules for required traffic |
+| RBAC permission denied | Missing Role/RoleBinding | Check ServiceAccount bindings and verb permissions |
+
+## Quick reference
+
+```bash
+# Build
+chant build src/ --output manifests.yaml
+
+# Lint
+chant lint src/
+
+# Validate
+kubectl apply -f manifests.yaml --dry-run=server
+
+# Diff
+kubectl diff -f manifests.yaml
+
+# Apply
+kubectl apply -f manifests.yaml
+
+# Status
+kubectl get pods,svc,deploy
+
+# Logs
+kubectl logs deployment/my-app
+
+# Rollback
+kubectl rollout undo deployment/my-app
+
+# Debug
+kubectl describe pod <name>
+kubectl logs <name> --previous
+kubectl get events --sort-by=.lastTimestamp
+```