@intentius/chant-lexicon-k8s 0.0.14 → 0.0.16

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

@@ -0,0 +1,191 @@
+---
+skill: chant-k8s-gke
+description: GKE-specific Kubernetes patterns and composites
+user-invocable: true
+---
+
+# GKE Kubernetes Patterns
+
+## GKE Composites Overview
+
+These composites produce K8s YAML with GKE-specific annotations and configurations.
+
+### WorkloadIdentityServiceAccount — ServiceAccount with GCP SA annotation
+
+```typescript
+import { WorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
+
+const { serviceAccount, role, roleBinding } = WorkloadIdentityServiceAccount({
+  name: "app-sa",
+  gcpServiceAccountEmail: "app@my-project.iam.gserviceaccount.com",
+  rbacRules: [
+    { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+  ],
+  namespace: "prod",
+});
+```
+
+Annotates the ServiceAccount with `iam.gke.io/gcp-service-account` for GKE Workload Identity.
+
+### GceIngress — Ingress with GCE ingress class annotations
+
+```typescript
+import { GceIngress } from "@intentius/chant-lexicon-k8s";
+
+const { ingress } = GceIngress({
+  name: "api-ingress",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+    },
+  ],
+  staticIpName: "api-ip",
+  managedCertificate: "api-cert",
+  namespace: "prod",
+});
+```
+
+Features:
+- Sets `kubernetes.io/ingress.class: "gce"` annotation
+- `staticIpName` binds a reserved global static IP via `kubernetes.io/ingress.global-static-ip-name`
+- `managedCertificate` attaches a GKE-managed SSL certificate via `networking.gke.io/managed-certificates`
+- Auto-generates FrontendConfig for SSL redirect when `managedCertificate` is set (override with `sslRedirect: false`)
+- Pairs naturally with Config Connector `ComputeAddress` resources for static IPs
+
+### GkeGateway — Gateway API with GKE gateway classes
+
+```typescript
+import { GkeGateway } from "@intentius/chant-lexicon-k8s";
+
+const { gateway, httpRoute } = GkeGateway({
+  name: "api-gateway",
+  gatewayClassName: "gke-l7-global-external-managed",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+    },
+  ],
+  certificateName: "api-cert",
+  namespace: "prod",
+});
+```
+
+Gateway class options:
+- `gke-l7-global-external-managed` — Global external (default)
+- `gke-l7-regional-external-managed` — Regional external
+- `gke-l7-rilb` — Regional internal
+
+### GcePdStorageClass — StorageClass for GCE Persistent Disk CSI
+
+```typescript
+import { GcePdStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = GcePdStorageClass({
+  name: "pd-balanced",
+  type: "pd-balanced",
+  replicationType: "none",
+  allowVolumeExpansion: true,
+});
+```
+
+Disk types: `pd-standard`, `pd-ssd`, `pd-balanced` (default), `pd-extreme`.
+
+### FilestoreStorageClass — StorageClass for Filestore CSI (ReadWriteMany)
+
+```typescript
+import { FilestoreStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = FilestoreStorageClass({
+  name: "filestore-shared",
+  tier: "standard",
+  network: "my-vpc",
+});
+```
+
+Use Filestore when you need ReadWriteMany (shared across pods/nodes). Use GCE PD for ReadWriteOnce (single pod).
+
+### GkeExternalDnsAgent — ExternalDNS for Cloud DNS
+
+```typescript
+import { GkeExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
+
+const result = GkeExternalDnsAgent({
+  gcpServiceAccountEmail: "dns@my-project.iam.gserviceaccount.com",
+  gcpProjectId: "my-project",
+  domainFilters: ["example.com"],
+  txtOwnerId: "my-cluster",
+});
+```
+
+### GkeFluentBitAgent — DaemonSet for Cloud Logging
+
+```typescript
+import { GkeFluentBitAgent } from "@intentius/chant-lexicon-k8s";
+
+const result = GkeFluentBitAgent({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+  gcpServiceAccountEmail: "logging@my-project.iam.gserviceaccount.com",
+});
+```
+
+### GkeOtelCollector — OTel for Cloud Trace + Cloud Monitoring
+
+```typescript
+import { GkeOtelCollector } from "@intentius/chant-lexicon-k8s";
+
+const result = GkeOtelCollector({
+  clusterName: "my-cluster",
+  projectId: "my-project",
+  gcpServiceAccountEmail: "monitoring@my-project.iam.gserviceaccount.com",
+});
+```
+
+### ConfigConnectorContext — Config Connector namespace bootstrap
+
+```typescript
+import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";
+
+const { context } = ConfigConnectorContext({
+  googleServiceAccountEmail: "cc-sa@my-project.iam.gserviceaccount.com",
+  namespace: "config-connector",
+  stateIntoSpec: "absent",
+});
+```
+
+Required when using Config Connector to manage GCP resources from within the cluster.
+
+## Workload Identity vs Key-Based Auth
+
+| Feature | Workload Identity | Key-based (JSON key file) |
+|---------|------------------|--------------------------|
+| K8s annotation needed | Yes (`iam.gke.io/gcp-service-account`) | No |
+| Composite available | **WorkloadIdentityServiceAccount** | None needed (mount key as Secret) |
+| Setup | GKE cluster WI enabled + IAM binding | Create key → K8s Secret → volume mount |
+| Security | No long-lived credentials, auto-rotated | Static key, must rotate manually |
+| When to use | Always (recommended) | Legacy workloads, non-GKE clusters |
+
+Workload Identity is the recommended approach for all GKE workloads. Key-based auth requires no K8s-side composite — create a Secret from the JSON key and mount it.
+
+## Config Connector Considerations
+
+Config Connector (CC) runs as a GKE add-on and manages GCP resources declaratively via K8s CRDs:
+- **Bootstrap cluster required** — CC needs an existing GKE cluster to run in; use `npm run bootstrap` to create one
+- **CC service account** — a GCP SA with editor/IAM roles, bound to the CC controller pod via Workload Identity
+- **Reconciliation** — CC continuously reconciles; deleting a CC resource deletes the underlying GCP resource
+- **ConfigConnectorContext** — use the composite to configure CC per-namespace (SA email, stateIntoSpec policy)
+
+## GKE Add-ons
+
+Common add-ons managed via GKE (not K8s manifests):
+- **Config Connector** — manage GCP resources as K8s CRDs
+- **Workload Identity** — pod-to-GCP-SA identity federation (required for WorkloadIdentityServiceAccount)
+- **GKE Gateway Controller** — Gateway API implementation (required for GkeGateway)
+- **GKE managed Prometheus** — alternative to GkeOtelCollector for metrics
+- **GKE Dataplane V2** — eBPF-based networking with built-in NetworkPolicy enforcement
+- **Filestore CSI driver** — required for FilestoreStorageClass
+- **Compute Engine persistent disk CSI driver** — enabled by default, required for GcePdStorageClass
+
+Configure add-ons via the GCP lexicon (`@intentius/chant-lexicon-gcp`) Config Connector resources.

package/src/skills/kubernetes-patterns.md

@@ -0,0 +1,183 @@
+---
+skill: kubernetes-patterns
+description: Kubernetes deployment strategies, stateful workloads, RBAC, and networking patterns
+user-invocable: true
+---
+
+# Kubernetes Infrastructure Patterns
+
+## Deployment Strategies
+
+### Rolling Update (default)
+
+Gradually replaces pods with zero downtime. Configure surge and unavailability:
+
+```typescript
+import { WebApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service } = WebApp({
+  name: "api",
+  image: "api:2.0",
+  replicas: 4,
+  strategy: {
+    type: "RollingUpdate",
+    rollingUpdate: { maxSurge: "25%", maxUnavailable: "25%" },
+  },
+});
+```
+
+### Blue/Green Deployment
+
+Run two full deployments and switch traffic by updating the Service selector:
+
+```typescript
+import { WebApp } from "@intentius/chant-lexicon-k8s";
+
+const blue = WebApp({ name: "app-blue", image: "app:1.0", replicas: 3 });
+const green = WebApp({ name: "app-green", image: "app:2.0", replicas: 3 });
+
+// Switch traffic: update the Service selector to point at green
+// kubectl patch svc app -p '{"spec":{"selector":{"version":"green"}}}'
+```
+
+### Canary Deployment
+
+Deploy a small replica set alongside the main deployment to test new versions:
+
+```typescript
+import { AutoscaledService, WebApp } from "@intentius/chant-lexicon-k8s";
+
+const main = AutoscaledService({
+  name: "app",
+  image: "app:1.0",
+  port: 8080,
+  minReplicas: 9,
+  maxReplicas: 20,
+});
+
+const canary = WebApp({
+  name: "app-canary",
+  image: "app:2.0",
+  replicas: 1,
+  labels: { track: "canary" },
+});
+```
+
+Both share the same `app.kubernetes.io/name` label so the Service routes traffic to both.
+
+## Stateful Workloads
+
+### StatefulSet with Persistent Storage
+
+Use `StatefulApp` for databases, caches, and other stateful services:
+
+```typescript
+import { StatefulApp } from "@intentius/chant-lexicon-k8s";
+
+const { statefulSet, service } = StatefulApp({
+  name: "postgres",
+  image: "postgres:16",
+  port: 5432,
+  replicas: 3,
+  storageSize: "50Gi",
+  storageClass: "gp3-encrypted",
+  env: [
+    { name: "POSTGRES_DB", value: "app" },
+    { name: "POSTGRES_PASSWORD", valueFrom: { secretKeyRef: { name: "pg-creds", key: "password" } } },
+  ],
+});
+```
+
+### Headless Service for StatefulSet Discovery
+
+`StatefulApp` creates a headless Service (`clusterIP: None`) automatically. Pods are addressable as `postgres-0.postgres.namespace.svc.cluster.local`.
+
+### PersistentVolumeClaim Retention
+
+StatefulSet PVCs persist after pod deletion by default. To clean up:
+
+```bash
+kubectl delete pvc -l app.kubernetes.io/name=postgres
+```
+
+## RBAC Patterns
+
+### Least-Privilege ServiceAccount
+
+Use `WorkerPool` or `BatchJob` composites which create scoped RBAC automatically:
+
+```typescript
+import { WorkerPool } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, serviceAccount, role, roleBinding } = WorkerPool({
+  name: "queue-worker",
+  image: "worker:1.0",
+  replicas: 3,
+  rbacRules: [
+    { apiGroups: [""], resources: ["configmaps"], verbs: ["get", "list"] },
+    { apiGroups: ["batch"], resources: ["jobs"], verbs: ["create"] },
+  ],
+});
+```
+
+### Namespace-Scoped vs Cluster-Scoped
+
+- Use `Role` + `RoleBinding` for namespace-scoped permissions (default in composites)
+- Use `ClusterRole` + `ClusterRoleBinding` for cross-namespace access (node agents, monitoring)
+
+```typescript
+import { NodeAgent } from "@intentius/chant-lexicon-k8s";
+
+const { daemonSet, serviceAccount, clusterRole, clusterRoleBinding } = NodeAgent({
+  name: "log-agent",
+  image: "fluent-bit:2.2",
+  rbacRules: [
+    { apiGroups: [""], resources: ["pods", "namespaces"], verbs: ["get", "list", "watch"] },
+  ],
+});
+```
+
+## Networking Patterns
+
+### Default-Deny with Selective Allow
+
+Use `NamespaceEnv` for namespace-level isolation, then `NetworkIsolatedApp` for per-app rules:
+
+```typescript
+import { NamespaceEnv, NetworkIsolatedApp } from "@intentius/chant-lexicon-k8s";
+
+const ns = NamespaceEnv({
+  name: "prod",
+  defaultDenyIngress: true,
+  defaultDenyEgress: true,
+  cpuLimit: "8",
+  memoryLimit: "16Gi",
+});
+
+const app = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  namespace: "prod",
+  allowIngressFrom: [
+    { podSelector: { "app.kubernetes.io/name": "gateway" } },
+  ],
+  allowEgressTo: [
+    { podSelector: { "app.kubernetes.io/name": "postgres" }, ports: [{ port: 5432 }] },
+  ],
+});
+```
+
+### Service Mesh (Istio/Linkerd)
+
+For mTLS between services, use a sidecar-injected namespace:
+
+```bash
+kubectl label namespace prod istio-injection=enabled
+```
+
+Then deploy with standard composites. The mesh proxy is injected automatically.
+
+### DNS-Based Service Discovery
+
+Services are discoverable at `<service>.<namespace>.svc.cluster.local`. For headless services (StatefulSets), individual pods are at `<pod>.<service>.<namespace>.svc.cluster.local`.

package/src/skills/kubernetes-security.md

@@ -0,0 +1,237 @@
+---
+skill: kubernetes-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
+```