@intentius/chant-lexicon-k8s 0.0.14 → 0.0.16

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[] {
@@ -42,11 +44,14 @@ export const k8sPlugin: LexiconPlugin = {
     const { wk8301 } = require("./lint/post-synth/wk8301");
     const { wk8302 } = require("./lint/post-synth/wk8302");
     const { wk8303 } = require("./lint/post-synth/wk8303");
+    const { wk8304 } = require("./lint/post-synth/wk8304");
+    const { wk8305 } = require("./lint/post-synth/wk8305");
+    const { wk8306 } = require("./lint/post-synth/wk8306");
     return [
       wk8005, wk8006, wk8041, wk8042,
       wk8101, wk8102, wk8103, wk8104, wk8105,
       wk8201, wk8202, wk8203, wk8204, wk8205, wk8207, wk8208, wk8209,
-      wk8301, wk8302, wk8303,
+      wk8301, wk8302, wk8303, wk8304, wk8305, wk8306,
     ];
   },
 
@@ -712,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",
 });`,
           },
         ],
@@ -1222,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/serializer.test.ts

@@ -143,6 +143,76 @@ describe("k8sSerializer", () => {
     expect(result).not.toContain("spec:");
   });
 
+  test("ClusterRole is specless type", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "viewRole",
+      mockResource("K8s::Rbac::ClusterRole", {
+        metadata: { name: "view-role" },
+        rules: [{ apiGroups: [""], resources: ["pods"], verbs: ["get", "list"] }],
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: ClusterRole");
+    expect(result).toContain("name: view-role");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("ClusterRoleBinding is specless type", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "viewBinding",
+      mockResource("K8s::Rbac::ClusterRoleBinding", {
+        metadata: { name: "view-binding" },
+        roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "ClusterRole", name: "view-role" },
+        subjects: [{ kind: "ServiceAccount", name: "default", namespace: "default" }],
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: ClusterRoleBinding");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("StorageClass is specless type", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "gp3",
+      mockResource("K8s::Storage::StorageClass", {
+        metadata: { name: "gp3-encrypted" },
+        provisioner: "ebs.csi.aws.com",
+        parameters: { type: "gp3", encrypted: "true" },
+        reclaimPolicy: "Delete",
+        volumeBindingMode: "WaitForFirstConsumer",
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: StorageClass");
+    expect(result).toContain("provisioner: ebs.csi.aws.com");
+    expect(result).not.toContain("spec:");
+  });
+
+  test("APIService is specless type", () => {
+    const entities = new Map<string, any>();
+    entities.set(
+      "metricsApi",
+      mockResource("K8s::Admissionregistration::APIService", {
+        metadata: { name: "v1beta1.metrics.k8s.io" },
+        group: "metrics.k8s.io",
+        version: "v1beta1",
+        service: { name: "metrics-server", namespace: "kube-system" },
+        groupPriorityMinimum: 100,
+        versionPriority: 100,
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: APIService");
+    expect(result).not.toContain("spec:");
+  });
+
   test("multi-resource entities joined by ---", () => {
     const entities = new Map<string, any>();
     entities.set(
@@ -248,6 +318,56 @@ describe("k8sSerializer", () => {
     expect(result).toBe("");
   });
 
+  test("Namespaces appear before other resources regardless of insertion order", () => {
+    const entities = new Map<string, any>();
+    // Insert Deployment first, then Namespace — Namespace should still come first in output
+    entities.set(
+      "deploy",
+      mockResource("K8s::Apps::Deployment", {
+        metadata: { name: "app", namespace: "my-ns" },
+        spec: { replicas: 1 },
+      }),
+    );
+    entities.set(
+      "ns",
+      mockResource("K8s::Core::Namespace", {
+        metadata: { name: "my-ns" },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    const docs = result.split("---");
+    // First document should be the Namespace
+    expect(docs[0]).toContain("kind: Namespace");
+    expect(docs[0]).toContain("name: my-ns");
+    // Second document should be the Deployment
+    expect(docs[1]).toContain("kind: Deployment");
+  });
+
+  test("ConfigMap multiline data emits as | block scalar", () => {
+    const entities = new Map<string, any>();
+    const multilineConfig = "[SERVICE]\n    Flush 5\n    Log_Level info\n\n[INPUT]\n    Name tail\n";
+    entities.set(
+      "config",
+      mockResource("K8s::Core::ConfigMap", {
+        metadata: { name: "app-config" },
+        data: { "fluent-bit.conf": multilineConfig },
+      }),
+    );
+
+    const result = k8sSerializer.serialize(entities);
+    expect(result).toContain("kind: ConfigMap");
+    // Must use | block scalar, not flatten to single line
+    expect(result).toContain("fluent-bit.conf: |");
+    // Content lines should be preserved (indented under the key)
+    expect(result).toContain("[SERVICE]");
+    expect(result).toContain("Flush 5");
+    expect(result).toContain("[INPUT]");
+    expect(result).toContain("Name tail");
+    // Should NOT contain literal \n in the output
+    expect(result).not.toContain("\\n");
+  });
+
   test("key ordering: apiVersion, kind, metadata, spec, then rest", () => {
     const entities = new Map<string, any>();
     entities.set(

package/src/serializer.ts

@@ -26,6 +26,13 @@ const SPECLESS_TYPES = new Set([
   "Secret",
   "Namespace",
   "ServiceAccount",
+  "ClusterRole",
+  "ClusterRoleBinding",
+  "Role",
+  "RoleBinding",
+  "StorageClass",
+  "PersistentVolume",
+  "APIService",
 ]);
 
 /**
@@ -157,7 +164,8 @@ export const k8sSerializer: Serializer = {
       }
     }
 
-    const documents: string[] = [];
+    const namespaceDocs: string[] = [];
+    const otherDocs: string[] = [];
 
     for (const [name, entity] of entities) {
       if (isPropertyDeclarable(entity)) continue;
@@ -230,12 +238,16 @@ export const k8sSerializer: Serializer = {
         }
       }
 
-      // Emit as YAML
+      // Emit as YAML — sort Namespaces first so kubectl apply succeeds
       const yamlDoc = emitK8sManifest(manifest);
-      documents.push(yamlDoc);
+      if (gvk.kind === "Namespace") {
+        namespaceDocs.push(yamlDoc);
+      } else {
+        otherDocs.push(yamlDoc);
+      }
     }
 
-    return documents.join("\n---\n");
+    return [...namespaceDocs, ...otherDocs].join("\n---\n");
   },
 };
 

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.