@intentius/chant-lexicon-k8s 0.0.15 → 0.0.16

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

@@ -0,0 +1,146 @@
+---
+skill: chant-k8s-aks
+description: AKS-specific Kubernetes patterns and composites
+user-invocable: true
+---
+
+# AKS Kubernetes Patterns
+
+## AKS Composites Overview
+
+These composites produce K8s YAML with AKS-specific annotations and configurations.
+
+### AksWorkloadIdentityServiceAccount — ServiceAccount with Azure client ID annotation
+
+```typescript
+import { AksWorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
+
+const { serviceAccount, role, roleBinding } = AksWorkloadIdentityServiceAccount({
+  name: "app-sa",
+  clientId: "12345678-abcd-1234-abcd-123456789012",
+  rbacRules: [
+    { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
+  ],
+  namespace: "prod",
+});
+```
+
+Annotates the ServiceAccount with `azure.workload.identity/client-id` for AKS Workload Identity.
+
+### AgicIngress — Ingress with Application Gateway annotations
+
+```typescript
+import { AgicIngress } from "@intentius/chant-lexicon-k8s";
+
+const { ingress } = AgicIngress({
+  name: "api-ingress",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
+    },
+  ],
+  certificateArn: "keyvault-cert-name",
+  healthCheckPath: "/healthz",
+  wafPolicyId: "/subscriptions/.../applicationGatewayWebApplicationFirewallPolicies/my-waf",
+  cookieAffinity: false,
+});
+```
+
+Features:
+- Auto-sets `appgw.ingress.kubernetes.io/*` annotations
+- SSL redirect enabled by default when `certificateArn` set
+- `wafPolicyId` for WAFv2 integration
+- `healthCheckPath` for backend health probes
+- `cookieAffinity` for session persistence
+
+### AzureDiskStorageClass — StorageClass for Azure Disk CSI
+
+```typescript
+import { AzureDiskStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = AzureDiskStorageClass({
+  name: "premium-lrs",
+  skuName: "Premium_LRS",
+  cachingMode: "ReadOnly",
+  allowVolumeExpansion: true,
+});
+```
+
+SKU options: `Premium_LRS`, `StandardSSD_LRS`, `Standard_LRS`, `UltraSSD_LRS`.
+
+### AzureFileStorageClass — StorageClass for Azure Files CSI (ReadWriteMany)
+
+```typescript
+import { AzureFileStorageClass } from "@intentius/chant-lexicon-k8s";
+
+const { storageClass } = AzureFileStorageClass({
+  name: "azure-files-premium",
+  skuName: "Premium_LRS",
+  protocol: "smb",
+});
+```
+
+Protocol options: `smb` (default), `nfs`. Use Azure Files when you need ReadWriteMany (shared across pods/nodes). Use Azure Disk for ReadWriteOnce (single pod).
+
+### AksExternalDnsAgent — ExternalDNS for Azure DNS
+
+```typescript
+import { AksExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
+
+const result = AksExternalDnsAgent({
+  clientId: "12345678-abcd-1234-abcd-123456789012",
+  resourceGroup: "my-rg",
+  subscriptionId: "sub-id",
+  tenantId: "tenant-id",
+  domainFilters: ["example.com"],
+  txtOwnerId: "my-cluster",
+});
+```
+
+### AzureMonitorCollector — Azure Monitor + OTel for Log Analytics
+
+```typescript
+import { AzureMonitorCollector } from "@intentius/chant-lexicon-k8s";
+
+const result = AzureMonitorCollector({
+  workspaceId: "/subscriptions/.../workspaces/my-workspace",
+  clusterName: "my-cluster",
+  clientId: "12345678-abcd-1234-abcd-123456789012",
+});
+```
+
+## AKS Workload Identity vs Pod-Managed Identity
+
+| Feature | Workload Identity | Pod-Managed Identity (deprecated) |
+|---------|------------------|----------------------------------|
+| K8s annotation needed | Yes (`azure.workload.identity/client-id`) | Yes (`aadpodidbinding` label) |
+| Composite available | **AksWorkloadIdentityServiceAccount** | None (deprecated) |
+| Setup | OIDC issuer + federated credential | AzureIdentity + AzureIdentityBinding CRDs |
+| Security | OIDC token exchange, no NMI pod | NMI DaemonSet intercepts IMDS calls |
+| When to use | Always (recommended) | Legacy only, migrate to Workload Identity |
+
+Pod-managed identity (AAD Pod Identity v1) is deprecated. Always use AKS Workload Identity for new workloads.
+
+## AGIC Considerations
+
+Application Gateway Ingress Controller (AGIC) manages an Azure Application Gateway:
+- **Application Gateway provisioned in ARM** — the gateway itself is an Azure resource created by the ARM template
+- **AGIC addon** — runs as a pod in the cluster, watches Ingress resources and configures the gateway
+- **Backend pools** — AGIC automatically adds pod IPs to the Application Gateway backend pool
+- **Health probes** — set `healthCheckPath` for proper backend health checking
+- **WAF integration** — attach a WAF policy via `wafPolicyId` for L7 protection
+- **TLS termination** — reference Key Vault certificates via `certificateArn` (the certificate URI or secret name)
+
+## AKS Add-ons
+
+Common add-ons managed via AKS (not K8s manifests):
+- **AGIC** — Application Gateway Ingress Controller (required for AgicIngress)
+- **Azure Monitor (Container Insights)** — alternative to AzureMonitorCollector for managed monitoring
+- **AKS Workload Identity** — OIDC-based identity federation (required for AksWorkloadIdentityServiceAccount)
+- **Azure Disk CSI driver** — enabled by default, required for AzureDiskStorageClass
+- **Azure Files CSI driver** — enabled by default, required for AzureFileStorageClass
+- **Azure Key Vault Secrets Provider** — sync Key Vault secrets to K8s Secrets
+- **Azure Policy** — enforce governance policies on cluster resources
+
+Configure add-ons via the Azure lexicon (`@intentius/chant-lexicon-azure`) ARM resources.

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`.