@intentius/chant-lexicon-k8s 0.0.15 → 0.0.18

package/src/plugin.ts

@@ -18,7 +18,9 @@ export const k8sPlugin: LexiconPlugin = {
 
   lintRules(): LintRule[] {
     const { hardcodedNamespaceRule } = require("./lint/rules/hardcoded-namespace");
-    return [hardcodedNamespaceRule];
+    const { latestImageTagRule } = require("./lint/rules/latest-image-tag");
+    const { missingResourceLimitsRule } = require("./lint/rules/missing-resource-limits");
+    return [hardcodedNamespaceRule, latestImageTagRule, missingResourceLimitsRule];
   },
 
   postSynthChecks(): PostSynthCheck[] {
@@ -715,213 +717,6 @@ const { job, serviceAccount, role, roleBinding } = BatchJob({
   command: ["python", "manage.py", "migrate"],
   backoffLimit: 3,
   ttlSecondsAfterFinished: 3600,
-});`,
-          },
-        ],
-      },
-      {
-        name: "chant-k8s-eks",
-        description: "EKS-specific Kubernetes composites — IRSA, ALB, EBS/EFS, Fluent Bit, ExternalDNS, ADOT",
-        content: `---
-skill: chant-k8s-eks
-description: EKS-specific Kubernetes patterns and composites
-user-invocable: true
----
-
-# EKS Kubernetes Patterns
-
-## EKS Composites Overview
-
-These composites produce K8s YAML with EKS-specific annotations and configurations.
-
-### IrsaServiceAccount — ServiceAccount with IAM Role annotation
-
-\`\`\`typescript
-import { IrsaServiceAccount } from "@intentius/chant-lexicon-k8s";
-
-const { serviceAccount, role, roleBinding } = IrsaServiceAccount({
-  name: "app-sa",
-  iamRoleArn: "arn:aws:iam::123456789012:role/my-app-role",
-  rbacRules: [
-    { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
-  ],
-  namespace: "prod",
-});
-\`\`\`
-
-### AlbIngress — Ingress with AWS ALB Controller annotations
-
-\`\`\`typescript
-import { AlbIngress } from "@intentius/chant-lexicon-k8s";
-
-const { ingress } = AlbIngress({
-  name: "api-ingress",
-  hosts: [
-    {
-      hostname: "api.example.com",
-      paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
-    },
-  ],
-  scheme: "internet-facing",
-  certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
-  groupName: "shared-alb",
-  healthCheckPath: "/healthz",
-});
-\`\`\`
-
-Features:
-- Auto-sets \`alb.ingress.kubernetes.io/*\` annotations
-- SSL redirect enabled by default when \`certificateArn\` set
-- \`groupName\` for shared ALB across multiple Ingresses
-- \`wafAclArn\` for WAFv2 integration
-
-### EbsStorageClass — StorageClass for EBS CSI
-
-\`\`\`typescript
-import { EbsStorageClass } from "@intentius/chant-lexicon-k8s";
-
-const { storageClass } = EbsStorageClass({
-  name: "gp3-encrypted",
-  type: "gp3",
-  encrypted: true,
-  iops: "3000",
-  throughput: "125",
-});
-\`\`\`
-
-### EfsStorageClass — StorageClass for EFS CSI (ReadWriteMany)
-
-\`\`\`typescript
-import { EfsStorageClass } from "@intentius/chant-lexicon-k8s";
-
-const { storageClass } = EfsStorageClass({
-  name: "efs-shared",
-  fileSystemId: "fs-12345678",
-});
-\`\`\`
-
-Use EFS when you need ReadWriteMany (shared across pods/nodes). Use EBS for ReadWriteOnce (single pod).
-
-### FluentBitAgent — DaemonSet for CloudWatch logging
-
-\`\`\`typescript
-import { FluentBitAgent } from "@intentius/chant-lexicon-k8s";
-
-const result = FluentBitAgent({
-  logGroup: "/aws/eks/my-cluster/containers",
-  region: "us-east-1",
-  clusterName: "my-cluster",
-});
-\`\`\`
-
-### ExternalDnsAgent — ExternalDNS for Route53
-
-\`\`\`typescript
-import { ExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
-
-const result = ExternalDnsAgent({
-  iamRoleArn: "arn:aws:iam::123456789012:role/external-dns-role",
-  domainFilters: ["example.com"],
-  txtOwnerId: "my-cluster",
-});
-\`\`\`
-
-### AdotCollector — ADOT for CloudWatch/X-Ray
-
-\`\`\`typescript
-import { AdotCollector } from "@intentius/chant-lexicon-k8s";
-
-const result = AdotCollector({
-  region: "us-east-1",
-  clusterName: "my-cluster",
-  exporters: ["cloudwatch", "xray"],
-});
-\`\`\`
-
-## Pod Identity vs IRSA
-
-| Feature | IRSA | Pod Identity |
-|---------|------|-------------|
-| K8s annotation needed | Yes (\`eks.amazonaws.com/role-arn\`) | No |
-| Composite available | **IrsaServiceAccount** | None needed |
-| Setup | OIDC provider + IAM role trust policy | EKS Pod Identity Agent add-on + association |
-| When to use | Existing clusters, broad compatibility | New clusters (EKS 1.28+), simpler management |
-
-For Pod Identity, no K8s-side composite is needed — configure the association via AWS API/CloudFormation and use a plain ServiceAccount.
-
-## Karpenter
-
-Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter NodePool and EC2NodeClass are simple CRDs — use CRD import rather than composites:
-
-\`\`\`bash
-# Import Karpenter CRDs into your chant project
-chant import --url https://raw.githubusercontent.com/aws/karpenter/main/pkg/apis/crds/karpenter.sh_nodepools.yaml
-\`\`\`
-
-## Fargate Considerations
-
-When running on EKS Fargate:
-- **No DaemonSets** — FluentBitAgent and AdotCollector cannot run on Fargate nodes
-- **No hostPath volumes** — use EFS for shared storage
-- **No privileged containers** — security context restrictions apply
-- For Fargate logging, use the built-in Fluent Bit log router (Fargate logging configuration)
-
-## EKS Add-ons
-
-Common add-ons managed via AWS (not K8s manifests):
-- **vpc-cni** — Amazon VPC CNI plugin
-- **coredns** — Cluster DNS
-- **kube-proxy** — Network proxy
-- **aws-ebs-csi-driver** — EBS CSI driver (required for EbsStorageClass)
-- **aws-efs-csi-driver** — EFS CSI driver (required for EfsStorageClass)
-- **adot** — AWS Distro for OpenTelemetry (alternative to AdotCollector composite)
-- **aws-guardduty-agent** — Runtime threat detection
-
-Configure add-ons via the AWS lexicon (\`@intentius/chant-lexicon-aws\`) CloudFormation resources.
-`,
-        triggers: [
-          { type: "context", value: "eks" },
-          { type: "context", value: "irsa" },
-          { type: "context", value: "alb" },
-          { type: "context", value: "ebs" },
-          { type: "context", value: "efs" },
-          { type: "context", value: "fluent-bit" },
-          { type: "context", value: "cloudwatch" },
-          { type: "context", value: "karpenter" },
-          { type: "context", value: "fargate" },
-        ],
-        preConditions: [
-          "chant CLI is installed (chant --version succeeds)",
-          "EKS cluster is provisioned",
-          "kubectl is configured for the EKS cluster",
-        ],
-        postConditions: [
-          "EKS-specific resources are deployed and functional",
-        ],
-        parameters: [],
-        examples: [
-          {
-            title: "IRSA ServiceAccount",
-            description: "Create a ServiceAccount with IAM role for S3 access",
-            input: "Create an IRSA ServiceAccount for my app that needs S3 access",
-            output: `import { IrsaServiceAccount } from "@intentius/chant-lexicon-k8s";
-
-const { serviceAccount } = IrsaServiceAccount({
-  name: "app-sa",
-  iamRoleArn: "arn:aws:iam::123456789012:role/app-s3-role",
-  namespace: "prod",
-});`,
-          },
-          {
-            title: "ALB Ingress with TLS",
-            description: "Create an ALB Ingress with ACM certificate",
-            input: "Set up an internet-facing ALB with TLS for my API",
-            output: `import { AlbIngress } from "@intentius/chant-lexicon-k8s";
-
-const { ingress } = AlbIngress({
-  name: "api-ingress",
-  hosts: [{ hostname: "api.example.com", paths: [{ path: "/", serviceName: "api", servicePort: 80 }] }],
-  certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
 });`,
           },
         ],
@@ -1225,5 +1020,127 @@ const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService
         ],
       },
     ];
+
+    // Load file-based skills from src/skills/
+    const { readFileSync } = require("fs");
+    const { join, dirname } = require("path");
+    const { fileURLToPath } = require("url");
+    const dir = dirname(fileURLToPath(import.meta.url));
+
+    const skillFiles = [
+      {
+        file: "kubernetes-patterns.md",
+        name: "kubernetes-patterns",
+        description: "Kubernetes deployment strategies, stateful workloads, RBAC, and networking patterns",
+        triggers: [
+          { type: "context" as const, value: "deployment strategy" },
+          { type: "context" as const, value: "statefulset" },
+          { type: "context" as const, value: "rbac" },
+          { type: "context" as const, value: "network policy" },
+          { type: "context" as const, value: "rolling update" },
+          { type: "context" as const, value: "blue green" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Blue/Green Deployment",
+            input: "Set up a blue/green deployment for my app",
+            output: "import { WebApp } from \"@intentius/chant-lexicon-k8s\";\n\nconst blue = WebApp({ name: \"app-blue\", image: \"app:1.0\" });\nconst green = WebApp({ name: \"app-green\", image: \"app:2.0\" });",
+          },
+        ],
+      },
+      {
+        file: "kubernetes-security.md",
+        name: "kubernetes-security",
+        description: "Kubernetes pod security, image scanning, network policies, and secrets management",
+        triggers: [
+          { type: "context" as const, value: "k8s security" },
+          { type: "context" as const, value: "pod security" },
+          { type: "context" as const, value: "image security" },
+          { type: "context" as const, value: "k8s secrets" },
+          { type: "context" as const, value: "security context" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "Hardened Container",
+            input: "Create a hardened container with security context",
+            output: "WebApp({ name: \"api\", image: \"api:1.0\", securityContext: { runAsNonRoot: true, readOnlyRootFilesystem: true, capabilities: { drop: [\"ALL\"] } } })",
+          },
+        ],
+      },
+      {
+        file: "chant-k8s-eks.md",
+        name: "chant-k8s-eks",
+        description: "EKS-specific Kubernetes composites — IRSA, ALB, EBS/EFS, Fluent Bit, ExternalDNS, ADOT",
+        triggers: [
+          { type: "context" as const, value: "eks composites" },
+          { type: "context" as const, value: "irsa" },
+          { type: "context" as const, value: "alb ingress" },
+          { type: "context" as const, value: "ebs storage" },
+          { type: "context" as const, value: "karpenter" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "IRSA ServiceAccount",
+            input: "Create an IRSA ServiceAccount for my app",
+            output: "import { IrsaServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = IrsaServiceAccount({ name: \"app-sa\", iamRoleArn: \"arn:aws:iam::123456789012:role/app-role\" });",
+          },
+        ],
+      },
+      {
+        file: "chant-k8s-gke.md",
+        name: "chant-k8s-gke",
+        description: "GKE-specific Kubernetes composites — Workload Identity, GCE PD, Filestore, FluentBit, OTel, ExternalDNS, Gateway",
+        triggers: [
+          { type: "context" as const, value: "gke composites" },
+          { type: "context" as const, value: "workload identity gke" },
+          { type: "context" as const, value: "config connector k8s" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "GKE Workload Identity",
+            input: "Create a ServiceAccount with GKE Workload Identity",
+            output: "import { WorkloadIdentityServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = WorkloadIdentityServiceAccount({ name: \"app-sa\", gcpServiceAccountEmail: \"app@project.iam.gserviceaccount.com\" });",
+          },
+        ],
+      },
+      {
+        file: "chant-k8s-aks.md",
+        name: "chant-k8s-aks",
+        description: "AKS-specific Kubernetes composites — Workload Identity, AGIC, Azure Disk/File, ExternalDNS, Azure Monitor",
+        triggers: [
+          { type: "context" as const, value: "aks composites" },
+          { type: "context" as const, value: "workload identity aks" },
+          { type: "context" as const, value: "agic ingress" },
+        ],
+        parameters: [],
+        examples: [
+          {
+            title: "AKS Workload Identity",
+            input: "Create a ServiceAccount with AKS Workload Identity",
+            output: "import { AksWorkloadIdentityServiceAccount } from \"@intentius/chant-lexicon-k8s\";\n\nconst { serviceAccount } = AksWorkloadIdentityServiceAccount({ name: \"app-sa\", clientId: \"12345678-abcd-1234-abcd-123456789012\" });",
+          },
+        ],
+      },
+    ];
+
+    for (const skill of skillFiles) {
+      try {
+        const content = readFileSync(join(dir, "skills", skill.file), "utf-8");
+        skills.push({
+          name: skill.name,
+          description: skill.description,
+          content,
+          triggers: skill.triggers,
+          parameters: skill.parameters,
+          examples: skill.examples,
+        });
+      } catch { /* skip missing skills */ }
+    }
+
+    return skills;
   },
 };

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.