@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.
- package/dist/integrity.json +9 -4
- package/dist/manifest.json +1 -1
- package/dist/skills/chant-k8s-aks.md +146 -0
- package/{src/skills/kubernetes-patterns.md → dist/skills/chant-k8s-deployment-strategies.md} +1 -1
- package/dist/skills/chant-k8s-eks.md +156 -0
- package/dist/skills/chant-k8s-gke.md +246 -0
- package/{src/skills/kubernetes-security.md → dist/skills/chant-k8s-security.md} +1 -1
- package/dist/skills/chant-k8s.md +65 -2
- package/package.json +5 -4
- package/src/composites/adot-collector.ts +34 -22
- package/src/composites/agic-ingress.ts +14 -6
- package/src/composites/aks-external-dns-agent.ts +29 -18
- package/src/composites/alb-ingress.ts +14 -6
- package/src/composites/autoscaled-service.ts +25 -20
- package/src/composites/azure-disk-storage-class.ts +14 -6
- package/src/composites/azure-file-storage-class.ts +14 -6
- package/src/composites/azure-monitor-collector.ts +34 -22
- package/src/composites/batch-job.ts +25 -17
- package/src/composites/cockroachdb-cluster.ts +164 -58
- package/src/composites/composites.test.ts +371 -365
- package/src/composites/config-connector-context.ts +18 -11
- package/src/composites/configured-app.ts +21 -15
- package/src/composites/cron-workload.ts +25 -20
- package/src/composites/ebs-storage-class.ts +14 -6
- package/src/composites/efs-storage-class.ts +14 -6
- package/src/composites/external-dns-agent.ts +26 -20
- package/src/composites/filestore-storage-class.ts +14 -6
- package/src/composites/fluent-bit-agent.ts +30 -24
- package/src/composites/gce-ingress.ts +14 -6
- package/src/composites/gce-pd-storage-class.ts +14 -6
- package/src/composites/gke-external-dns-agent.ts +34 -21
- package/src/composites/gke-fluent-bit-agent.ts +34 -22
- package/src/composites/gke-gateway.ts +19 -12
- package/src/composites/gke-otel-collector.ts +34 -22
- package/src/composites/irsa-service-account.ts +22 -14
- package/src/composites/metrics-server.ts +41 -26
- package/src/composites/monitored-service.ts +26 -19
- package/src/composites/namespace-env.ts +26 -17
- package/src/composites/network-isolated-app.ts +21 -16
- package/src/composites/node-agent.ts +33 -22
- package/src/composites/secure-ingress.ts +19 -11
- package/src/composites/sidecar-app.ts +17 -12
- package/src/composites/stateful-app.ts +21 -12
- package/src/composites/web-app.ts +25 -21
- package/src/composites/worker-pool.ts +40 -26
- package/src/composites/workload-identity-sa.ts +22 -14
- package/src/composites/workload-identity-service-account.ts +22 -16
- package/src/plugin.ts +40 -614
- package/src/serializer.ts +7 -0
- package/src/skills/chant-k8s-deployment-strategies.md +183 -0
- package/src/skills/chant-k8s-gke.md +56 -1
- package/src/skills/chant-k8s-patterns.md +245 -0
- package/src/skills/chant-k8s-security.md +237 -0
- package/src/skills/chant-k8s.md +305 -0
package/dist/integrity.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"algorithm": "xxhash64",
|
|
3
3
|
"artifacts": {
|
|
4
|
-
"manifest.json": "
|
|
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": "
|
|
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": "
|
|
42
|
+
"composite": "583e41307c91a103"
|
|
38
43
|
}
|
package/dist/manifest.json
CHANGED
|
@@ -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.
|
|
@@ -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.
|