@intentius/chant-lexicon-k8s 0.0.22 → 0.1.0

package/src/serializer.ts

@@ -88,6 +88,13 @@ const API_GROUP_VERSIONS: Record<string, string> = {
   Storage: "storage.k8s.io/v1",
   Autoscaling: "autoscaling/v2",
   Admissionregistration: "admissionregistration.k8s.io/v1",
+  GKE: "cloud.google.com/v1",
+  NetworkingGKE: "networking.gke.io/v1",
+  NetworkingGKEBeta: "networking.gke.io/v1beta1",
+  // Common Kubernetes operator CRDs
+  CertManager: "cert-manager.io/v1",
+  ExternalSecrets: "external-secrets.io/v1",
+  Monitoring: "monitoring.coreos.com/v1",
 };
 
 function deriveGVKFromType(entityType: string): { apiVersion: string; kind: string } | null {

package/src/skills/chant-k8s-deployment-strategies.md

@@ -0,0 +1,183 @@
+---
+skill: chant-k8s-deployment-strategies
+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/chant-k8s-gke.md

@@ -119,6 +119,12 @@ const result = GkeExternalDnsAgent({
 });
 ```
 
+**Props:** `gcpServiceAccountEmail` (required), `gcpProjectId` (required), `domainFilters` (required), `txtOwnerId?`, `source?` (string or string[], default: `"service"`), `name?` (default: `"external-dns"`), `namespace?` (default: `"kube-system"`), `image?` (default: `"registry.k8s.io/external-dns/external-dns:v0.14.2"`), `labels?`, `defaults?`
+
+**Returns:** `{ deployment, serviceAccount, clusterRole, clusterRoleBinding }`
+
+To watch both Services and Ingresses, pass `source: ["service", "ingress"]`.
+
 ### GkeFluentBitAgent — DaemonSet for Cloud Logging
 
 ```typescript
@@ -143,6 +149,55 @@ const result = GkeOtelCollector({
 });
 ```
 
+### CockroachDbCluster — multi-node CockroachDB StatefulSet
+
+```typescript
+import { CockroachDbCluster } from "@intentius/chant-lexicon-k8s";
+
+const crdb = CockroachDbCluster({
+  name: "cockroachdb",
+  namespace: "crdb-east",
+  replicas: 3,
+  image: "cockroachdb/cockroach:v24.3.4",
+  storageSize: "100Gi",
+  storageClassName: "pd-ssd",
+  cpuLimit: "2",
+  memoryLimit: "8Gi",
+  locality: "region=us-east1,zone=us-east1-b",
+  joinAddresses: ["cockroachdb-0.east.crdb.example.com", "cockroachdb-0.west.crdb.example.com"],
+  secure: true,
+  skipInit: false,       // true on non-bootstrapping regions
+  skipCertGen: true,     // true when certs are provisioned externally
+  advertiseHostDomain: "east.crdb.example.com",
+  extraCertNodeAddresses: [
+    "cockroachdb-0.east.crdb.example.com",
+    "cockroachdb-1.east.crdb.example.com",
+    "cockroachdb-2.east.crdb.example.com",
+  ],
+});
+
+export const {
+  serviceAccount, role, roleBinding, clusterRole, clusterRoleBinding,
+  publicService, headlessService, pdb, statefulSet,
+  initJob,     // only when skipInit: false
+  certGenJob,  // only when skipCertGen: false
+} = crdb;
+```
+
+**Key props:**
+- `secure` — enables TLS node-to-node and client comms (default: `false`)
+- `skipInit` — skip `cockroach init`; set `true` on all regions except the one that bootstraps the cluster
+- `skipCertGen` — skip cert generation Job; use when certs are managed externally (e.g. `generate-certs.sh`)
+- `advertiseHostDomain` — hostname suffix CockroachDB advertises to peers; must resolve via ExternalDNS or similar
+- `extraCertNodeAddresses` — SANs added to node certs for cross-region RPC; list all pod FQDNs that peers will dial
+- `locality` — CockroachDB locality string (`region=...,zone=...`); used for data placement and rebalancing
+- `joinAddresses` — seed peer addresses used at startup; include one node from each region
+
+**`defaults`** allow deep-merging arbitrary fields onto any generated resource:
+- `defaults.serviceAccount` — e.g. add `iam.gke.io/gcp-service-account` annotation for Workload Identity
+- `defaults.publicService` — e.g. add `cloud.google.com/backend-config` + `cloud.google.com/app-protocols` annotations for GCE Ingress
+- `defaults.headlessService` — e.g. add `external-dns.alpha.kubernetes.io/hostname` for ExternalDNS registration
+
 ### ConfigConnectorContext — Config Connector namespace bootstrap
 
 ```typescript
@@ -151,7 +206,7 @@ import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";
 const { context } = ConfigConnectorContext({
   googleServiceAccountEmail: "cc-sa@my-project.iam.gserviceaccount.com",
   namespace: "config-connector",
-  stateIntoSpec: "absent",
+  stateIntoSpec: "Absent",
 });
 ```
 

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

@@ -0,0 +1,245 @@
+---
+skill: chant-k8s-patterns
+description: Advanced Kubernetes deployment patterns and composites
+user-invocable: true
+---
+
+# Advanced Kubernetes Patterns
+
+## Sidecar Patterns
+
+### SidecarApp — multi-container Deployment
+
+```typescript
+import { SidecarApp } from "@intentius/chant-lexicon-k8s";
+
+// Envoy sidecar proxy
+const { deployment, service } = SidecarApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  sidecars: [
+    {
+      name: "envoy",
+      image: "envoyproxy/envoy:v1.28",
+      ports: [{ containerPort: 9901, name: "admin" }],
+      resources: { requests: { cpu: "100m", memory: "128Mi" }, limits: { cpu: "200m", memory: "256Mi" } },
+    },
+  ],
+  initContainers: [
+    { name: "migrate", image: "api:1.0", command: ["python", "manage.py", "migrate"] },
+  ],
+  sharedVolumes: [{ name: "tmp", emptyDir: {} }],
+});
+```
+
+Common sidecar use cases:
+- **Envoy proxy** — service mesh, mTLS, traffic management
+- **Log forwarder** — Fluent Bit sidecar for app-specific log routing
+- **Auth proxy** — OAuth2 Proxy for authentication
+- **Config watcher** — reload config on ConfigMap changes
+
+## Config and Secret Mounting
+
+### ConfiguredApp — automatic volume wiring
+
+```typescript
+import { ConfiguredApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, configMap } = ConfiguredApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  // Mount ConfigMap as volume
+  configData: { "app.conf": "key=value\nother=setting" },
+  configMountPath: "/etc/api",
+  // Mount existing Secret as volume
+  secretName: "api-creds",
+  secretMountPath: "/secrets",
+  // Inject as environment variables
+  envFrom: { secretRef: "api-env-secret", configMapRef: "api-env-config" },
+  // Run migrations before the app starts
+  initContainers: [
+    { name: "migrate", image: "api:1.0", command: ["./migrate.sh"] },
+  ],
+});
+```
+
+### Volume patterns
+
+| Pattern | Use Case | ConfiguredApp Props |
+|---------|----------|---------------------|
+| ConfigMap as file | Config files, templates | `configData` + `configMountPath` |
+| Secret as file | TLS certs, credentials | `secretName` + `secretMountPath` |
+| ConfigMap as env | Simple key-value config | `envFrom.configMapRef` |
+| Secret as env | Database URLs, API keys | `envFrom.secretRef` |
+
+## TLS / cert-manager
+
+### SecureIngress — multi-host TLS with cert-manager
+
+```typescript
+import { SecureIngress } from "@intentius/chant-lexicon-k8s";
+
+const { ingress, certificate } = SecureIngress({
+  name: "app-ingress",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [
+        { path: "/v1", serviceName: "api-v1", servicePort: 80 },
+        { path: "/v2", serviceName: "api-v2", servicePort: 80 },
+      ],
+    },
+    {
+      hostname: "admin.example.com",
+      paths: [{ path: "/", serviceName: "admin", servicePort: 80 }],
+    },
+  ],
+  clusterIssuer: "letsencrypt-prod",
+  ingressClassName: "nginx",
+});
+```
+
+Features:
+- Multiple hosts and paths per Ingress
+- Automatic cert-manager Certificate when `clusterIssuer` set
+- TLS secret auto-provisioned by cert-manager
+
+### cert-manager setup (prerequisite)
+
+```bash
+# Install cert-manager
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
+
+# Create ClusterIssuer for Let's Encrypt
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@example.com
+    privateKeySecretRef:
+      name: letsencrypt-prod-key
+    solvers:
+    - http01:
+        ingress:
+          class: nginx
+EOF
+```
+
+## Observability
+
+### MonitoredService — Prometheus monitoring
+
+```typescript
+import { MonitoredService } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  metricsPort: 9090,
+  metricsPath: "/metrics",
+  scrapeInterval: "15s",
+  alertRules: [
+    {
+      name: "HighErrorRate",
+      expr: 'rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05',
+      for: "5m",
+      severity: "critical",
+      annotations: { summary: "High error rate on {{ $labels.instance }}" },
+    },
+    {
+      name: "HighLatency",
+      expr: 'histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 1',
+      for: "10m",
+      severity: "warning",
+    },
+  ],
+});
+```
+
+### Prerequisites
+
+- Prometheus Operator installed (for ServiceMonitor/PrometheusRule CRDs)
+- Prometheus configured to discover ServiceMonitors
+
+## Network Isolation
+
+### NetworkIsolatedApp — per-app firewall rules
+
+```typescript
+import { NetworkIsolatedApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, networkPolicy } = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  allowIngressFrom: [
+    { podSelector: { "app.kubernetes.io/name": "frontend" } },
+    { namespaceSelector: { "kubernetes.io/metadata.name": "monitoring" } },
+  ],
+  allowEgressTo: [
+    { podSelector: { "app.kubernetes.io/name": "postgres" }, ports: [{ port: 5432 }] },
+    { podSelector: { "app.kubernetes.io/name": "redis" }, ports: [{ port: 6379 }] },
+  ],
+});
+```
+
+### Combining with NamespaceEnv
+
+Use NamespaceEnv for namespace-level default-deny, then NetworkIsolatedApp for per-app allow rules:
+
+```typescript
+// Namespace: deny all by default
+const ns = NamespaceEnv({ name: "prod", defaultDenyIngress: true, defaultDenyEgress: true });
+
+// App: allow specific traffic
+const app = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  namespace: "prod",
+  allowIngressFrom: [{ podSelector: { "app.kubernetes.io/name": "gateway" } }],
+  allowEgressTo: [{ podSelector: { "app.kubernetes.io/name": "db" }, ports: [{ port: 5432 }] }],
+});
+```
+
+## Blue/Green and Canary
+
+These patterns use standard K8s resources — no special composite needed.
+
+### Blue/Green
+
+```typescript
+// Two Deployments with different versions
+const blue = WebApp({ name: "app-blue", image: "app:1.0", labels: { version: "blue" } });
+const green = WebApp({ name: "app-green", image: "app:2.0", labels: { version: "green" } });
+
+// Service points to active version — switch by changing selector
+// Active: blue → green (update the Service selector)
+```
+
+### Canary
+
+```typescript
+// Main deployment (90% traffic)
+const main = AutoscaledService({ name: "app", image: "app:1.0", minReplicas: 9, maxReplicas: 20, ... });
+
+// Canary deployment (10% traffic) — same app label, fewer replicas
+const canary = WebApp({ name: "app-canary", image: "app:2.0", replicas: 1, labels: { track: "canary" } });
+// Both share the same Service selector ("app.kubernetes.io/name": "app") for traffic splitting
+```
+
+## Gateway API (future direction)
+
+Gateway API is the successor to Ingress. Key differences:
+- **HTTPRoute** replaces Ingress rules
+- **Gateway** replaces IngressClass
+- Built-in traffic splitting, header matching, URL rewriting
+- Currently in beta — use Ingress/SecureIngress/AlbIngress for production today
+
+When Gateway API reaches GA, new composites will be added. For now, use CRD import if you need Gateway API resources.