@intentius/chant-lexicon-k8s 0.0.22 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/dist/integrity.json +9 -4
  2. package/dist/manifest.json +1 -1
  3. package/dist/skills/chant-k8s-aks.md +146 -0
  4. package/{src/skills/kubernetes-patterns.md → dist/skills/chant-k8s-deployment-strategies.md} +1 -1
  5. package/dist/skills/chant-k8s-eks.md +156 -0
  6. package/dist/skills/chant-k8s-gke.md +246 -0
  7. package/{src/skills/kubernetes-security.md → dist/skills/chant-k8s-security.md} +1 -1
  8. package/dist/skills/chant-k8s.md +65 -2
  9. package/package.json +5 -4
  10. package/src/composites/adot-collector.ts +34 -22
  11. package/src/composites/agic-ingress.ts +14 -6
  12. package/src/composites/aks-external-dns-agent.ts +29 -18
  13. package/src/composites/alb-ingress.ts +14 -6
  14. package/src/composites/autoscaled-service.ts +25 -20
  15. package/src/composites/azure-disk-storage-class.ts +14 -6
  16. package/src/composites/azure-file-storage-class.ts +14 -6
  17. package/src/composites/azure-monitor-collector.ts +34 -22
  18. package/src/composites/batch-job.ts +25 -17
  19. package/src/composites/cockroachdb-cluster.ts +164 -58
  20. package/src/composites/composites.test.ts +371 -365
  21. package/src/composites/config-connector-context.ts +18 -11
  22. package/src/composites/configured-app.ts +21 -15
  23. package/src/composites/cron-workload.ts +25 -20
  24. package/src/composites/ebs-storage-class.ts +14 -6
  25. package/src/composites/efs-storage-class.ts +14 -6
  26. package/src/composites/external-dns-agent.ts +26 -20
  27. package/src/composites/filestore-storage-class.ts +14 -6
  28. package/src/composites/fluent-bit-agent.ts +30 -24
  29. package/src/composites/gce-ingress.ts +14 -6
  30. package/src/composites/gce-pd-storage-class.ts +14 -6
  31. package/src/composites/gke-external-dns-agent.ts +34 -21
  32. package/src/composites/gke-fluent-bit-agent.ts +34 -22
  33. package/src/composites/gke-gateway.ts +19 -12
  34. package/src/composites/gke-otel-collector.ts +34 -22
  35. package/src/composites/irsa-service-account.ts +22 -14
  36. package/src/composites/metrics-server.ts +41 -26
  37. package/src/composites/monitored-service.ts +26 -19
  38. package/src/composites/namespace-env.ts +26 -17
  39. package/src/composites/network-isolated-app.ts +21 -16
  40. package/src/composites/node-agent.ts +33 -22
  41. package/src/composites/secure-ingress.ts +19 -11
  42. package/src/composites/sidecar-app.ts +17 -12
  43. package/src/composites/stateful-app.ts +21 -12
  44. package/src/composites/web-app.ts +25 -21
  45. package/src/composites/worker-pool.ts +40 -26
  46. package/src/composites/workload-identity-sa.ts +22 -14
  47. package/src/composites/workload-identity-service-account.ts +22 -16
  48. package/src/plugin.ts +40 -614
  49. package/src/serializer.ts +7 -0
  50. package/src/skills/chant-k8s-deployment-strategies.md +183 -0
  51. package/src/skills/chant-k8s-gke.md +56 -1
  52. package/src/skills/chant-k8s-patterns.md +245 -0
  53. package/src/skills/chant-k8s-security.md +237 -0
  54. package/src/skills/chant-k8s.md +305 -0
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "algorithm": "xxhash64",
3
3
  "artifacts": {
4
- "manifest.json": "b91b5f6c197826b1",
4
+ "manifest.json": "aff81f16893ceb64",
5
5
  "meta.json": "1ce194f36f9b5f90",
6
6
  "types/index.d.ts": "beec4cc869064186",
7
7
  "rules/missing-resource-limits.ts": "a6f776d2ff477948",
@@ -31,8 +31,13 @@
31
31
  "rules/wk8105.ts": "8dbcfe399f23656a",
32
32
  "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
33
33
  "rules/wk8207.ts": "6f2bc621d530afa2",
34
- "skills/chant-k8s.md": "177efa9794242096",
35
- "skills/chant-k8s-patterns.md": "c5151ed799145c4b"
34
+ "skills/chant-k8s.md": "bf3ac0c5bddd5d2a",
35
+ "skills/chant-k8s-patterns.md": "c5151ed799145c4b",
36
+ "skills/chant-k8s-deployment-strategies.md": "74f179e7cdb15ed5",
37
+ "skills/chant-k8s-security.md": "f377edc5fe0a3587",
38
+ "skills/chant-k8s-eks.md": "f79f31f058c7f2ed",
39
+ "skills/chant-k8s-gke.md": "2f65ca45aef40c22",
40
+ "skills/chant-k8s-aks.md": "764fa4b1408b618d"
36
41
  },
37
- "composite": "c7b4bc8445140fdf"
42
+ "composite": "583e41307c91a103"
38
43
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "k8s",
3
- "version": "0.0.22",
3
+ "version": "0.1.0",
4
4
  "chantVersion": ">=0.1.0",
5
5
  "namespace": "K8s",
6
6
  "intrinsics": [],
@@ -0,0 +1,146 @@
1
+ ---
2
+ skill: chant-k8s-aks
3
+ description: AKS-specific Kubernetes patterns and composites
4
+ user-invocable: true
5
+ ---
6
+
7
+ # AKS Kubernetes Patterns
8
+
9
+ ## AKS Composites Overview
10
+
11
+ These composites produce K8s YAML with AKS-specific annotations and configurations.
12
+
13
+ ### AksWorkloadIdentityServiceAccount — ServiceAccount with Azure client ID annotation
14
+
15
+ ```typescript
16
+ import { AksWorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
17
+
18
+ const { serviceAccount, role, roleBinding } = AksWorkloadIdentityServiceAccount({
19
+ name: "app-sa",
20
+ clientId: "12345678-abcd-1234-abcd-123456789012",
21
+ rbacRules: [
22
+ { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
23
+ ],
24
+ namespace: "prod",
25
+ });
26
+ ```
27
+
28
+ Annotates the ServiceAccount with `azure.workload.identity/client-id` for AKS Workload Identity.
29
+
30
+ ### AgicIngress — Ingress with Application Gateway annotations
31
+
32
+ ```typescript
33
+ import { AgicIngress } from "@intentius/chant-lexicon-k8s";
34
+
35
+ const { ingress } = AgicIngress({
36
+ name: "api-ingress",
37
+ hosts: [
38
+ {
39
+ hostname: "api.example.com",
40
+ paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
41
+ },
42
+ ],
43
+ certificateArn: "keyvault-cert-name",
44
+ healthCheckPath: "/healthz",
45
+ wafPolicyId: "/subscriptions/.../applicationGatewayWebApplicationFirewallPolicies/my-waf",
46
+ cookieAffinity: false,
47
+ });
48
+ ```
49
+
50
+ Features:
51
+ - Auto-sets `appgw.ingress.kubernetes.io/*` annotations
52
+ - SSL redirect enabled by default when `certificateArn` set
53
+ - `wafPolicyId` for WAFv2 integration
54
+ - `healthCheckPath` for backend health probes
55
+ - `cookieAffinity` for session persistence
56
+
57
+ ### AzureDiskStorageClass — StorageClass for Azure Disk CSI
58
+
59
+ ```typescript
60
+ import { AzureDiskStorageClass } from "@intentius/chant-lexicon-k8s";
61
+
62
+ const { storageClass } = AzureDiskStorageClass({
63
+ name: "premium-lrs",
64
+ skuName: "Premium_LRS",
65
+ cachingMode: "ReadOnly",
66
+ allowVolumeExpansion: true,
67
+ });
68
+ ```
69
+
70
+ SKU options: `Premium_LRS`, `StandardSSD_LRS`, `Standard_LRS`, `UltraSSD_LRS`.
71
+
72
+ ### AzureFileStorageClass — StorageClass for Azure Files CSI (ReadWriteMany)
73
+
74
+ ```typescript
75
+ import { AzureFileStorageClass } from "@intentius/chant-lexicon-k8s";
76
+
77
+ const { storageClass } = AzureFileStorageClass({
78
+ name: "azure-files-premium",
79
+ skuName: "Premium_LRS",
80
+ protocol: "smb",
81
+ });
82
+ ```
83
+
84
+ Protocol options: `smb` (default), `nfs`. Use Azure Files when you need ReadWriteMany (shared across pods/nodes). Use Azure Disk for ReadWriteOnce (single pod).
85
+
86
+ ### AksExternalDnsAgent — ExternalDNS for Azure DNS
87
+
88
+ ```typescript
89
+ import { AksExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
90
+
91
+ const result = AksExternalDnsAgent({
92
+ clientId: "12345678-abcd-1234-abcd-123456789012",
93
+ resourceGroup: "my-rg",
94
+ subscriptionId: "sub-id",
95
+ tenantId: "tenant-id",
96
+ domainFilters: ["example.com"],
97
+ txtOwnerId: "my-cluster",
98
+ });
99
+ ```
100
+
101
+ ### AzureMonitorCollector — Azure Monitor + OTel for Log Analytics
102
+
103
+ ```typescript
104
+ import { AzureMonitorCollector } from "@intentius/chant-lexicon-k8s";
105
+
106
+ const result = AzureMonitorCollector({
107
+ workspaceId: "/subscriptions/.../workspaces/my-workspace",
108
+ clusterName: "my-cluster",
109
+ clientId: "12345678-abcd-1234-abcd-123456789012",
110
+ });
111
+ ```
112
+
113
+ ## AKS Workload Identity vs Pod-Managed Identity
114
+
115
+ | Feature | Workload Identity | Pod-Managed Identity (deprecated) |
116
+ |---------|------------------|----------------------------------|
117
+ | K8s annotation needed | Yes (`azure.workload.identity/client-id`) | Yes (`aadpodidbinding` label) |
118
+ | Composite available | **AksWorkloadIdentityServiceAccount** | None (deprecated) |
119
+ | Setup | OIDC issuer + federated credential | AzureIdentity + AzureIdentityBinding CRDs |
120
+ | Security | OIDC token exchange, no NMI pod | NMI DaemonSet intercepts IMDS calls |
121
+ | When to use | Always (recommended) | Legacy only, migrate to Workload Identity |
122
+
123
+ Pod-managed identity (AAD Pod Identity v1) is deprecated. Always use AKS Workload Identity for new workloads.
124
+
125
+ ## AGIC Considerations
126
+
127
+ Application Gateway Ingress Controller (AGIC) manages an Azure Application Gateway:
128
+ - **Application Gateway provisioned in ARM** — the gateway itself is an Azure resource created by the ARM template
129
+ - **AGIC addon** — runs as a pod in the cluster, watches Ingress resources and configures the gateway
130
+ - **Backend pools** — AGIC automatically adds pod IPs to the Application Gateway backend pool
131
+ - **Health probes** — set `healthCheckPath` for proper backend health checking
132
+ - **WAF integration** — attach a WAF policy via `wafPolicyId` for L7 protection
133
+ - **TLS termination** — reference Key Vault certificates via `certificateArn` (the certificate URI or secret name)
134
+
135
+ ## AKS Add-ons
136
+
137
+ Common add-ons managed via AKS (not K8s manifests):
138
+ - **AGIC** — Application Gateway Ingress Controller (required for AgicIngress)
139
+ - **Azure Monitor (Container Insights)** — alternative to AzureMonitorCollector for managed monitoring
140
+ - **AKS Workload Identity** — OIDC-based identity federation (required for AksWorkloadIdentityServiceAccount)
141
+ - **Azure Disk CSI driver** — enabled by default, required for AzureDiskStorageClass
142
+ - **Azure Files CSI driver** — enabled by default, required for AzureFileStorageClass
143
+ - **Azure Key Vault Secrets Provider** — sync Key Vault secrets to K8s Secrets
144
+ - **Azure Policy** — enforce governance policies on cluster resources
145
+
146
+ Configure add-ons via the Azure lexicon (`@intentius/chant-lexicon-azure`) ARM resources.
@@ -1,5 +1,5 @@
1
1
  ---
2
- skill: kubernetes-patterns
2
+ skill: chant-k8s-deployment-strategies
3
3
  description: Kubernetes deployment strategies, stateful workloads, RBAC, and networking patterns
4
4
  user-invocable: true
5
5
  ---
@@ -0,0 +1,156 @@
1
+ ---
2
+ skill: chant-k8s-eks
3
+ description: EKS-specific Kubernetes patterns and composites
4
+ user-invocable: true
5
+ ---
6
+
7
+ # EKS Kubernetes Patterns
8
+
9
+ ## EKS Composites Overview
10
+
11
+ These composites produce K8s YAML with EKS-specific annotations and configurations.
12
+
13
+ ### IrsaServiceAccount — ServiceAccount with IAM Role annotation
14
+
15
+ ```typescript
16
+ import { IrsaServiceAccount } from "@intentius/chant-lexicon-k8s";
17
+
18
+ const { serviceAccount, role, roleBinding } = IrsaServiceAccount({
19
+ name: "app-sa",
20
+ iamRoleArn: "arn:aws:iam::123456789012:role/my-app-role",
21
+ rbacRules: [
22
+ { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
23
+ ],
24
+ namespace: "prod",
25
+ });
26
+ ```
27
+
28
+ ### AlbIngress — Ingress with AWS ALB Controller annotations
29
+
30
+ ```typescript
31
+ import { AlbIngress } from "@intentius/chant-lexicon-k8s";
32
+
33
+ const { ingress } = AlbIngress({
34
+ name: "api-ingress",
35
+ hosts: [
36
+ {
37
+ hostname: "api.example.com",
38
+ paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
39
+ },
40
+ ],
41
+ scheme: "internet-facing",
42
+ certificateArn: "arn:aws:acm:us-east-1:123456789012:certificate/abc-123",
43
+ groupName: "shared-alb",
44
+ healthCheckPath: "/healthz",
45
+ });
46
+ ```
47
+
48
+ Features:
49
+ - Auto-sets `alb.ingress.kubernetes.io/*` annotations
50
+ - SSL redirect enabled by default when `certificateArn` set
51
+ - `groupName` for shared ALB across multiple Ingresses
52
+ - `wafAclArn` for WAFv2 integration
53
+
54
+ ### EbsStorageClass — StorageClass for EBS CSI
55
+
56
+ ```typescript
57
+ import { EbsStorageClass } from "@intentius/chant-lexicon-k8s";
58
+
59
+ const { storageClass } = EbsStorageClass({
60
+ name: "gp3-encrypted",
61
+ type: "gp3",
62
+ encrypted: true,
63
+ iops: "3000",
64
+ throughput: "125",
65
+ });
66
+ ```
67
+
68
+ ### EfsStorageClass — StorageClass for EFS CSI (ReadWriteMany)
69
+
70
+ ```typescript
71
+ import { EfsStorageClass } from "@intentius/chant-lexicon-k8s";
72
+
73
+ const { storageClass } = EfsStorageClass({
74
+ name: "efs-shared",
75
+ fileSystemId: "fs-12345678",
76
+ });
77
+ ```
78
+
79
+ Use EFS when you need ReadWriteMany (shared across pods/nodes). Use EBS for ReadWriteOnce (single pod).
80
+
81
+ ### FluentBitAgent — DaemonSet for CloudWatch logging
82
+
83
+ ```typescript
84
+ import { FluentBitAgent } from "@intentius/chant-lexicon-k8s";
85
+
86
+ const result = FluentBitAgent({
87
+ logGroup: "/aws/eks/my-cluster/containers",
88
+ region: "us-east-1",
89
+ clusterName: "my-cluster",
90
+ });
91
+ ```
92
+
93
+ ### ExternalDnsAgent — ExternalDNS for Route53
94
+
95
+ ```typescript
96
+ import { ExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
97
+
98
+ const result = ExternalDnsAgent({
99
+ iamRoleArn: "arn:aws:iam::123456789012:role/external-dns-role",
100
+ domainFilters: ["example.com"],
101
+ txtOwnerId: "my-cluster",
102
+ });
103
+ ```
104
+
105
+ ### AdotCollector — ADOT for CloudWatch/X-Ray
106
+
107
+ ```typescript
108
+ import { AdotCollector } from "@intentius/chant-lexicon-k8s";
109
+
110
+ const result = AdotCollector({
111
+ region: "us-east-1",
112
+ clusterName: "my-cluster",
113
+ exporters: ["cloudwatch", "xray"],
114
+ });
115
+ ```
116
+
117
+ ## Pod Identity vs IRSA
118
+
119
+ | Feature | IRSA | Pod Identity |
120
+ |---------|------|-------------|
121
+ | K8s annotation needed | Yes (`eks.amazonaws.com/role-arn`) | No |
122
+ | Composite available | **IrsaServiceAccount** | None needed |
123
+ | Setup | OIDC provider + IAM role trust policy | EKS Pod Identity Agent add-on + association |
124
+ | When to use | Existing clusters, broad compatibility | New clusters (EKS 1.28+), simpler management |
125
+
126
+ For Pod Identity, no K8s-side composite is needed — configure the association via AWS API/CloudFormation and use a plain ServiceAccount.
127
+
128
+ ## Karpenter
129
+
130
+ Karpenter replaces Cluster Autoscaler for node provisioning. Karpenter NodePool and EC2NodeClass are simple CRDs — use CRD import rather than composites:
131
+
132
+ ```bash
133
+ # Import Karpenter CRDs into your chant project
134
+ chant import --url https://raw.githubusercontent.com/aws/karpenter/main/pkg/apis/crds/karpenter.sh_nodepools.yaml
135
+ ```
136
+
137
+ ## Fargate Considerations
138
+
139
+ When running on EKS Fargate:
140
+ - **No DaemonSets** — FluentBitAgent and AdotCollector cannot run on Fargate nodes
141
+ - **No hostPath volumes** — use EFS for shared storage
142
+ - **No privileged containers** — security context restrictions apply
143
+ - For Fargate logging, use the built-in Fluent Bit log router (Fargate logging configuration)
144
+
145
+ ## EKS Add-ons
146
+
147
+ Common add-ons managed via AWS (not K8s manifests):
148
+ - **vpc-cni** — Amazon VPC CNI plugin
149
+ - **coredns** — Cluster DNS
150
+ - **kube-proxy** — Network proxy
151
+ - **aws-ebs-csi-driver** — EBS CSI driver (required for EbsStorageClass)
152
+ - **aws-efs-csi-driver** — EFS CSI driver (required for EfsStorageClass)
153
+ - **adot** — AWS Distro for OpenTelemetry (alternative to AdotCollector composite)
154
+ - **aws-guardduty-agent** — Runtime threat detection
155
+
156
+ Configure add-ons via the AWS lexicon (`@intentius/chant-lexicon-aws`) CloudFormation resources.
@@ -0,0 +1,246 @@
1
+ ---
2
+ skill: chant-k8s-gke
3
+ description: GKE-specific Kubernetes patterns and composites
4
+ user-invocable: true
5
+ ---
6
+
7
+ # GKE Kubernetes Patterns
8
+
9
+ ## GKE Composites Overview
10
+
11
+ These composites produce K8s YAML with GKE-specific annotations and configurations.
12
+
13
+ ### WorkloadIdentityServiceAccount — ServiceAccount with GCP SA annotation
14
+
15
+ ```typescript
16
+ import { WorkloadIdentityServiceAccount } from "@intentius/chant-lexicon-k8s";
17
+
18
+ const { serviceAccount, role, roleBinding } = WorkloadIdentityServiceAccount({
19
+ name: "app-sa",
20
+ gcpServiceAccountEmail: "app@my-project.iam.gserviceaccount.com",
21
+ rbacRules: [
22
+ { apiGroups: [""], resources: ["secrets"], verbs: ["get"] },
23
+ ],
24
+ namespace: "prod",
25
+ });
26
+ ```
27
+
28
+ Annotates the ServiceAccount with `iam.gke.io/gcp-service-account` for GKE Workload Identity.
29
+
30
+ ### GceIngress — Ingress with GCE ingress class annotations
31
+
32
+ ```typescript
33
+ import { GceIngress } from "@intentius/chant-lexicon-k8s";
34
+
35
+ const { ingress } = GceIngress({
36
+ name: "api-ingress",
37
+ hosts: [
38
+ {
39
+ hostname: "api.example.com",
40
+ paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
41
+ },
42
+ ],
43
+ staticIpName: "api-ip",
44
+ managedCertificate: "api-cert",
45
+ namespace: "prod",
46
+ });
47
+ ```
48
+
49
+ Features:
50
+ - Sets `kubernetes.io/ingress.class: "gce"` annotation
51
+ - `staticIpName` binds a reserved global static IP via `kubernetes.io/ingress.global-static-ip-name`
52
+ - `managedCertificate` attaches a GKE-managed SSL certificate via `networking.gke.io/managed-certificates`
53
+ - Auto-generates FrontendConfig for SSL redirect when `managedCertificate` is set (override with `sslRedirect: false`)
54
+ - Pairs naturally with Config Connector `ComputeAddress` resources for static IPs
55
+
56
+ ### GkeGateway — Gateway API with GKE gateway classes
57
+
58
+ ```typescript
59
+ import { GkeGateway } from "@intentius/chant-lexicon-k8s";
60
+
61
+ const { gateway, httpRoute } = GkeGateway({
62
+ name: "api-gateway",
63
+ gatewayClassName: "gke-l7-global-external-managed",
64
+ hosts: [
65
+ {
66
+ hostname: "api.example.com",
67
+ paths: [{ path: "/", serviceName: "api", servicePort: 80 }],
68
+ },
69
+ ],
70
+ certificateName: "api-cert",
71
+ namespace: "prod",
72
+ });
73
+ ```
74
+
75
+ Gateway class options:
76
+ - `gke-l7-global-external-managed` — Global external (default)
77
+ - `gke-l7-regional-external-managed` — Regional external
78
+ - `gke-l7-rilb` — Regional internal
79
+
80
+ ### GcePdStorageClass — StorageClass for GCE Persistent Disk CSI
81
+
82
+ ```typescript
83
+ import { GcePdStorageClass } from "@intentius/chant-lexicon-k8s";
84
+
85
+ const { storageClass } = GcePdStorageClass({
86
+ name: "pd-balanced",
87
+ type: "pd-balanced",
88
+ replicationType: "none",
89
+ allowVolumeExpansion: true,
90
+ });
91
+ ```
92
+
93
+ Disk types: `pd-standard`, `pd-ssd`, `pd-balanced` (default), `pd-extreme`.
94
+
95
+ ### FilestoreStorageClass — StorageClass for Filestore CSI (ReadWriteMany)
96
+
97
+ ```typescript
98
+ import { FilestoreStorageClass } from "@intentius/chant-lexicon-k8s";
99
+
100
+ const { storageClass } = FilestoreStorageClass({
101
+ name: "filestore-shared",
102
+ tier: "standard",
103
+ network: "my-vpc",
104
+ });
105
+ ```
106
+
107
+ Use Filestore when you need ReadWriteMany (shared across pods/nodes). Use GCE PD for ReadWriteOnce (single pod).
108
+
109
+ ### GkeExternalDnsAgent — ExternalDNS for Cloud DNS
110
+
111
+ ```typescript
112
+ import { GkeExternalDnsAgent } from "@intentius/chant-lexicon-k8s";
113
+
114
+ const result = GkeExternalDnsAgent({
115
+ gcpServiceAccountEmail: "dns@my-project.iam.gserviceaccount.com",
116
+ gcpProjectId: "my-project",
117
+ domainFilters: ["example.com"],
118
+ txtOwnerId: "my-cluster",
119
+ });
120
+ ```
121
+
122
+ **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?`
123
+
124
+ **Returns:** `{ deployment, serviceAccount, clusterRole, clusterRoleBinding }`
125
+
126
+ To watch both Services and Ingresses, pass `source: ["service", "ingress"]`.
127
+
128
+ ### GkeFluentBitAgent — DaemonSet for Cloud Logging
129
+
130
+ ```typescript
131
+ import { GkeFluentBitAgent } from "@intentius/chant-lexicon-k8s";
132
+
133
+ const result = GkeFluentBitAgent({
134
+ clusterName: "my-cluster",
135
+ projectId: "my-project",
136
+ gcpServiceAccountEmail: "logging@my-project.iam.gserviceaccount.com",
137
+ });
138
+ ```
139
+
140
+ ### GkeOtelCollector — OTel for Cloud Trace + Cloud Monitoring
141
+
142
+ ```typescript
143
+ import { GkeOtelCollector } from "@intentius/chant-lexicon-k8s";
144
+
145
+ const result = GkeOtelCollector({
146
+ clusterName: "my-cluster",
147
+ projectId: "my-project",
148
+ gcpServiceAccountEmail: "monitoring@my-project.iam.gserviceaccount.com",
149
+ });
150
+ ```
151
+
152
+ ### CockroachDbCluster — multi-node CockroachDB StatefulSet
153
+
154
+ ```typescript
155
+ import { CockroachDbCluster } from "@intentius/chant-lexicon-k8s";
156
+
157
+ const crdb = CockroachDbCluster({
158
+ name: "cockroachdb",
159
+ namespace: "crdb-east",
160
+ replicas: 3,
161
+ image: "cockroachdb/cockroach:v24.3.4",
162
+ storageSize: "100Gi",
163
+ storageClassName: "pd-ssd",
164
+ cpuLimit: "2",
165
+ memoryLimit: "8Gi",
166
+ locality: "region=us-east1,zone=us-east1-b",
167
+ joinAddresses: ["cockroachdb-0.east.crdb.example.com", "cockroachdb-0.west.crdb.example.com"],
168
+ secure: true,
169
+ skipInit: false, // true on non-bootstrapping regions
170
+ skipCertGen: true, // true when certs are provisioned externally
171
+ advertiseHostDomain: "east.crdb.example.com",
172
+ extraCertNodeAddresses: [
173
+ "cockroachdb-0.east.crdb.example.com",
174
+ "cockroachdb-1.east.crdb.example.com",
175
+ "cockroachdb-2.east.crdb.example.com",
176
+ ],
177
+ });
178
+
179
+ export const {
180
+ serviceAccount, role, roleBinding, clusterRole, clusterRoleBinding,
181
+ publicService, headlessService, pdb, statefulSet,
182
+ initJob, // only when skipInit: false
183
+ certGenJob, // only when skipCertGen: false
184
+ } = crdb;
185
+ ```
186
+
187
+ **Key props:**
188
+ - `secure` — enables TLS node-to-node and client comms (default: `false`)
189
+ - `skipInit` — skip `cockroach init`; set `true` on all regions except the one that bootstraps the cluster
190
+ - `skipCertGen` — skip cert generation Job; use when certs are managed externally (e.g. `generate-certs.sh`)
191
+ - `advertiseHostDomain` — hostname suffix CockroachDB advertises to peers; must resolve via ExternalDNS or similar
192
+ - `extraCertNodeAddresses` — SANs added to node certs for cross-region RPC; list all pod FQDNs that peers will dial
193
+ - `locality` — CockroachDB locality string (`region=...,zone=...`); used for data placement and rebalancing
194
+ - `joinAddresses` — seed peer addresses used at startup; include one node from each region
195
+
196
+ **`defaults`** allow deep-merging arbitrary fields onto any generated resource:
197
+ - `defaults.serviceAccount` — e.g. add `iam.gke.io/gcp-service-account` annotation for Workload Identity
198
+ - `defaults.publicService` — e.g. add `cloud.google.com/backend-config` + `cloud.google.com/app-protocols` annotations for GCE Ingress
199
+ - `defaults.headlessService` — e.g. add `external-dns.alpha.kubernetes.io/hostname` for ExternalDNS registration
200
+
201
+ ### ConfigConnectorContext — Config Connector namespace bootstrap
202
+
203
+ ```typescript
204
+ import { ConfigConnectorContext } from "@intentius/chant-lexicon-k8s";
205
+
206
+ const { context } = ConfigConnectorContext({
207
+ googleServiceAccountEmail: "cc-sa@my-project.iam.gserviceaccount.com",
208
+ namespace: "config-connector",
209
+ stateIntoSpec: "Absent",
210
+ });
211
+ ```
212
+
213
+ Required when using Config Connector to manage GCP resources from within the cluster.
214
+
215
+ ## Workload Identity vs Key-Based Auth
216
+
217
+ | Feature | Workload Identity | Key-based (JSON key file) |
218
+ |---------|------------------|--------------------------|
219
+ | K8s annotation needed | Yes (`iam.gke.io/gcp-service-account`) | No |
220
+ | Composite available | **WorkloadIdentityServiceAccount** | None needed (mount key as Secret) |
221
+ | Setup | GKE cluster WI enabled + IAM binding | Create key → K8s Secret → volume mount |
222
+ | Security | No long-lived credentials, auto-rotated | Static key, must rotate manually |
223
+ | When to use | Always (recommended) | Legacy workloads, non-GKE clusters |
224
+
225
+ 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.
226
+
227
+ ## Config Connector Considerations
228
+
229
+ Config Connector (CC) runs as a GKE add-on and manages GCP resources declaratively via K8s CRDs:
230
+ - **Bootstrap cluster required** — CC needs an existing GKE cluster to run in; use `npm run bootstrap` to create one
231
+ - **CC service account** — a GCP SA with editor/IAM roles, bound to the CC controller pod via Workload Identity
232
+ - **Reconciliation** — CC continuously reconciles; deleting a CC resource deletes the underlying GCP resource
233
+ - **ConfigConnectorContext** — use the composite to configure CC per-namespace (SA email, stateIntoSpec policy)
234
+
235
+ ## GKE Add-ons
236
+
237
+ Common add-ons managed via GKE (not K8s manifests):
238
+ - **Config Connector** — manage GCP resources as K8s CRDs
239
+ - **Workload Identity** — pod-to-GCP-SA identity federation (required for WorkloadIdentityServiceAccount)
240
+ - **GKE Gateway Controller** — Gateway API implementation (required for GkeGateway)
241
+ - **GKE managed Prometheus** — alternative to GkeOtelCollector for metrics
242
+ - **GKE Dataplane V2** — eBPF-based networking with built-in NetworkPolicy enforcement
243
+ - **Filestore CSI driver** — required for FilestoreStorageClass
244
+ - **Compute Engine persistent disk CSI driver** — enabled by default, required for GcePdStorageClass
245
+
246
+ Configure add-ons via the GCP lexicon (`@intentius/chant-lexicon-gcp`) Config Connector resources.
@@ -1,5 +1,5 @@
1
1
  ---
2
- skill: kubernetes-security
2
+ skill: chant-k8s-security
3
3
  description: Kubernetes pod security, image scanning, network policies, and secrets management
4
4
  user-invocable: true
5
5
  ---