@intentius/chant-lexicon-k8s 0.0.18 → 0.0.24

package/src/skills/chant-k8s-security.md

@@ -0,0 +1,237 @@
+---
+skill: chant-k8s-security
+description: Kubernetes pod security, image scanning, network policies, and secrets management
+user-invocable: true
+---
+
+# Kubernetes Security Patterns
+
+## Pod Security
+
+### Security Context (container-level)
+
+All Deployment-based composites accept `securityContext` for hardened containers:
+
+```typescript
+import { WebApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service } = WebApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  securityContext: {
+    runAsNonRoot: true,
+    runAsUser: 1000,
+    readOnlyRootFilesystem: true,
+    allowPrivilegeEscalation: false,
+    capabilities: { drop: ["ALL"] },
+  },
+});
+```
+
+### Pod Security Standards
+
+Kubernetes enforces three levels via Pod Security Admission:
+
+| Level | What it blocks | When to use |
+|-------|---------------|-------------|
+| `privileged` | Nothing | System namespaces only |
+| `baseline` | hostNetwork, hostPID, privileged containers | Development |
+| `restricted` | Non-root, no capabilities, read-only root FS | Production |
+
+Apply to a namespace:
+
+```bash
+kubectl label namespace prod pod-security.kubernetes.io/enforce=restricted
+kubectl label namespace prod pod-security.kubernetes.io/warn=restricted
+```
+
+### Post-Synth Security Checks
+
+chant catches security issues at build time:
+
+| Check | What it detects |
+|-------|----------------|
+| WK8005 | Secrets exposed in environment variables |
+| WK8006 | `latest` image tags (non-deterministic) |
+| WK8041 | API keys or tokens in plain text |
+| WK8042 | Hardcoded passwords in container env |
+| WK8201 | Missing resource limits (CPU/memory) |
+| WK8202 | Privileged containers |
+| WK8203 | Host namespace sharing (hostPID/hostNetwork) |
+| WK8204 | Writable root filesystem |
+| WK8205 | Containers running as root |
+
+## Image Security
+
+### Pin Image Digests
+
+Use image digests instead of tags for immutability:
+
+```typescript
+const { deployment } = WebApp({
+  name: "api",
+  image: "api@sha256:abc123def456...",
+  port: 8080,
+});
+```
+
+### Private Registry with imagePullSecrets
+
+```typescript
+import { Deployment, Secret } from "@intentius/chant-lexicon-k8s";
+
+export const registryCreds = new Secret({
+  metadata: { name: "registry-creds" },
+  type: "kubernetes.io/dockerconfigjson",
+  data: { ".dockerconfigjson": "${DOCKER_CONFIG_JSON}" },
+});
+
+export const deployment = new Deployment({
+  spec: {
+    template: {
+      spec: {
+        imagePullSecrets: [{ name: "registry-creds" }],
+        containers: [{ name: "app", image: "private.registry.io/app:1.0" }],
+      },
+    },
+  },
+});
+```
+
+### Image Policy
+
+Block unsigned or unscanned images with admission controllers:
+- **Kyverno**: policy-based, Kubernetes-native
+- **OPA/Gatekeeper**: Rego-based policies
+- **Sigstore/Cosign**: image signature verification
+
+## Network Policies
+
+### Default Deny All
+
+Start with deny-all and add explicit allows:
+
+```typescript
+import { NamespaceEnv } from "@intentius/chant-lexicon-k8s";
+
+const ns = NamespaceEnv({
+  name: "prod",
+  defaultDenyIngress: true,
+  defaultDenyEgress: true,
+});
+```
+
+### Allow Specific Traffic
+
+```typescript
+import { NetworkIsolatedApp } from "@intentius/chant-lexicon-k8s";
+
+const app = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  namespace: "prod",
+  allowIngressFrom: [
+    { podSelector: { "app.kubernetes.io/name": "gateway" } },
+    { namespaceSelector: { "kubernetes.io/metadata.name": "monitoring" } },
+  ],
+  allowEgressTo: [
+    { podSelector: { "app.kubernetes.io/name": "postgres" }, ports: [{ port: 5432 }] },
+    { ipBlock: { cidr: "10.0.0.0/8" }, ports: [{ port: 443 }] },
+  ],
+});
+```
+
+### Allow DNS Egress
+
+Most pods need DNS. Always allow egress to kube-dns:
+
+```yaml
+egress:
+  - to:
+      - namespaceSelector:
+          matchLabels:
+            kubernetes.io/metadata.name: kube-system
+    ports:
+      - port: 53
+        protocol: UDP
+      - port: 53
+        protocol: TCP
+```
+
+## Secrets Management
+
+### External Secrets Operator
+
+Sync secrets from external providers (AWS Secrets Manager, Vault, etc.):
+
+```yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: app-secrets
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: aws-secrets
+    kind: ClusterSecretStore
+  target:
+    name: app-secrets
+  data:
+    - secretKey: db-password
+      remoteRef:
+        key: prod/db-password
+```
+
+### Sealed Secrets
+
+Encrypt secrets for safe storage in Git:
+
+```bash
+kubeseal --format yaml < secret.yaml > sealed-secret.yaml
+```
+
+### Secret Rotation
+
+Use the External Secrets Operator `refreshInterval` or Reloader to restart pods on secret changes:
+
+```bash
+kubectl annotate deployment api reloader.stakater.com/auto="true"
+```
+
+## RBAC Hardening
+
+### Audit RBAC Permissions
+
+```bash
+# Check what a ServiceAccount can do
+kubectl auth can-i --list --as=system:serviceaccount:prod:api-sa
+
+# Check specific permission
+kubectl auth can-i create pods --as=system:serviceaccount:prod:api-sa
+```
+
+### Avoid Cluster-Admin
+
+Never bind `cluster-admin` to application ServiceAccounts. Use namespace-scoped Roles with minimal verbs:
+
+```typescript
+import { WorkerPool } from "@intentius/chant-lexicon-k8s";
+
+const worker = WorkerPool({
+  name: "processor",
+  image: "processor:1.0",
+  rbacRules: [
+    { apiGroups: [""], resources: ["configmaps"], verbs: ["get"] },
+  ],
+});
+```
+
+### Service Account Token Projection
+
+Disable auto-mounting of SA tokens when not needed:
+
+```yaml
+automountServiceAccountToken: false
+```

package/src/skills/chant-k8s.md

@@ -0,0 +1,305 @@
+---
+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 compiler** — it compiles TypeScript source files into Kubernetes YAML manifests. `chant build` does not call the Kubernetes API; synthesis is pure and deterministic. The optional `chant state snapshot` command queries the Kubernetes API to capture deployment metadata (pod names, status, UIDs) for observability. Your job as an agent is to bridge synthesis and deployment:
+
+- 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 |
+
+## 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
+```
+
+### 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.
+
+## 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 — Core Composites
+
+| 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 |
+| HPA metrics provider | **MetricsServer** | Deployment + Service + RBAC + APIService |
+| CockroachDB cluster | **CockroachDbCluster** | StatefulSet + Services + PVCs + RBAC + optional CertificateRequests |
+
+### Decision Tree — AWS (EKS) Composites
+
+| Need | Composite | Resources |
+|------|-----------|-----------|
+| 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 |
+
+### Decision Tree — GCP (GKE) Composites
+
+| Need | Composite | Resources |
+|------|-----------|-----------|
+| GKE Gateway API Ingress | **GkeGateway** | Gateway + HTTPRoute + optional HealthCheckPolicy |
+| GKE Ingress (classic) | **GceIngress** | Ingress with GCE annotations + optional BackendConfig |
+| GKE Workload Identity SA | **WorkloadIdentityServiceAccount** | ServiceAccount + optional RBAC (GCP IAM binding annotation) |
+| GCE Persistent Disk StorageClass | **GcePdStorageClass** | StorageClass (pd.csi.storage.gke.io) |
+| Filestore StorageClass | **FilestoreStorageClass** | StorageClass (filestore.csi.storage.gke.io) |
+| GKE Fluent Bit agent | **GkeFluentBitAgent** | DaemonSet + RBAC + ConfigMap (Cloud Logging) |
+| GKE ExternalDNS agent | **GkeExternalDnsAgent** | Deployment + WI SA + ClusterRole (Cloud DNS) |
+| GKE OpenTelemetry Collector | **GkeOtelCollector** | DaemonSet + RBAC + ConfigMap (Cloud Trace/Monitoring) |
+| Config Connector context | **ConfigConnectorContext** | ConfigConnectorContext + Namespace + RBAC |
+
+### Decision Tree — Azure (AKS) Composites
+
+| Need | Composite | Resources |
+|------|-----------|-----------|
+| AKS AGIC Ingress | **AgicIngress** | Ingress with AGIC annotations + optional BackendConfig |
+| Azure Disk StorageClass | **AzureDiskStorageClass** | StorageClass (disk.csi.azure.com) |
+| Azure File StorageClass | **AzureFileStorageClass** | StorageClass (file.csi.azure.com) |
+| AKS ExternalDNS agent | **AksExternalDnsAgent** | Deployment + WI SA + ClusterRole (Azure DNS) |
+| Azure Monitor Collector | **AzureMonitorCollector** | DaemonSet + RBAC + ConfigMap (Azure Monitor) |
+
+### 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
+
+- 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
+
+## 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 Pending | Too many pods on node | Check `kubectl describe node` for Allocatable vs Allocated |
+| Pod stuck in ContainerCreating | ConfigMap/Secret not found | Ensure referenced ConfigMaps/Secrets exist |
+| Pod stuck in ContainerCreating | Volume mount timeout | Check CSI driver logs, storage provider status |
+| Service returns 503 | No ready endpoints | Check pod readiness probes, selector match |
+| Service returns 503 | Endpoints exist but pod failing probes | Increase `initialDelaySeconds`, check probe path |
+| Ingress returns 404 | Backend service not found | Check Ingress rules, service name/port |
+| Ingress returns 502 | Backend pods not ready | Check pod readiness, container port matches Service targetPort |
+| HPA not scaling | Metrics server not installed | Install metrics-server or MetricsServer composite |
+| HPA not scaling | Resource requests not set | Add CPU/memory requests to containers |
+| HPA stuck at max | Target utilization too low | Raise `targetCPUUtilizationPercentage`, add nodes |
+| CronJob not running | Invalid cron expression | Validate cron syntax (5-field format) |
+| CronJob not running | `concurrencyPolicy: Forbid` with long jobs | Increase job deadline or switch to `Replace` |
+| NetworkPolicy blocking | Default deny applied | Add explicit allow rules for required traffic |
+| RBAC permission denied | Missing Role/RoleBinding | Check ServiceAccount bindings and verb permissions |
+| RBAC permission denied | ClusterRole vs namespaced Role | Use ClusterRoleBinding for cluster-scoped resources |
+| PDB preventing eviction | minAvailable too high | Lower minAvailable or increase replicas |
+| StatefulSet stuck on update | Pod ordinal blocked | Check PVC status for ordinal, delete stuck pod |
+
+## Troubleshooting decision tree
+
+```
+Pod not running?
+├─ Pending
+│  ├─ "Insufficient cpu/memory" → scale cluster or lower requests
+│  ├─ "no nodes match" → fix nodeSelector / tolerations
+│  └─ "unbound PVC" → check StorageClass, provision PV
+├─ ContainerCreating
+│  ├─ "secret not found" → create missing Secret
+│  └─ "timeout waiting for volume" → check CSI driver
+├─ CrashLoopBackOff
+│  ├─ OOMKilled → increase memory limit
+│  ├─ exit code 1 → check app logs (`kubectl logs --previous`)
+│  └─ exit code 137 → SIGKILL — liveness probe too aggressive
+├─ ImagePullBackOff
+│  ├─ 401 Unauthorized → check imagePullSecrets
+│  └─ manifest unknown → verify image:tag exists in registry
+└─ Running but not Ready
+   ├─ readinessProbe failing → check probe path/port
+   └─ startup probe failing → increase `failureThreshold * periodSeconds`
+```
+
+## 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
+```