@intentius/chant-lexicon-k8s 0.0.12 → 0.0.14

package/README.md

@@ -0,0 +1,24 @@
+# @intentius/chant-lexicon-k8s
+
+Kubernetes lexicon for [chant](https://intentius.io/chant/) — declare infrastructure as typed TypeScript that serializes to Kubernetes YAML manifests.
+
+This package provides typed constructors for all core Kubernetes resource types (Deployments, Services, ConfigMaps, Secrets, StatefulSets, and more), property types (Containers, Volumes, Probes, etc.), composites for common patterns, and K8s-specific lint rules. It also includes LSP and MCP server support for editor completions and hover.
+
+```bash
+npm install --save-dev @intentius/chant @intentius/chant-lexicon-k8s
+```
+
+**[Documentation →](https://intentius.io/chant/lexicons/k8s/)**
+
+## Related Packages
+
+| Package | Role |
+|---------|------|
+| [@intentius/chant](https://www.npmjs.com/package/@intentius/chant) | Core type system, CLI, build pipeline |
+| [@intentius/chant-lexicon-aws](https://www.npmjs.com/package/@intentius/chant-lexicon-aws) | AWS CloudFormation lexicon |
+| [@intentius/chant-lexicon-gitlab](https://www.npmjs.com/package/@intentius/chant-lexicon-gitlab) | GitLab CI lexicon |
+| [@intentius/chant-lexicon-flyway](https://www.npmjs.com/package/@intentius/chant-lexicon-flyway) | Flyway migration lexicon |
+
+## License
+
+See the main project LICENSE file.

package/dist/integrity.json

@@ -1,32 +1,34 @@
 {
   "algorithm": "xxhash64",
   "artifacts": {
-    "manifest.json": "a9f93ff8c0a8f750",
+    "manifest.json": "59b066d7c2f8d709",
     "meta.json": "1ce194f36f9b5f90",
     "types/index.d.ts": "beec4cc869064186",
     "rules/hardcoded-namespace.ts": "54b216c71018e101",
-    "rules/wk8006.ts": "6e04f754f79f076e",
     "rules/wk8201.ts": "4dbbd20e21b5fa04",
-    "rules/wk8103.ts": "e5d6a506d966e312",
-    "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
+    "rules/wk8204.ts": "31c3f8eac8455795",
     "rules/wk8301.ts": "283265ab0c5b8511",
-    "rules/wk8105.ts": "8dbcfe399f23656a",
+    "rules/wk8102.ts": "78d4aac387107b56",
     "rules/wk8101.ts": "f8ffcf6e5c89076b",
     "rules/wk8302.ts": "a80d1eab37c0dbe4",
+    "rules/wk8005.ts": "a9a1b93b80f3aa51",
+    "rules/wk8209.ts": "820df53f304e0a59",
     "rules/wk8203.ts": "f5bf17539c0428c5",
-    "rules/wk8042.ts": "6064c84481ae8551",
-    "rules/wk8202.ts": "6bd950ae2128256c",
-    "rules/wk8207.ts": "6f2bc621d530afa2",
     "rules/wk8104.ts": "94bd75c16b8d50b7",
+    "rules/wk8303.ts": "c545464e2af8fbb9",
+    "rules/wk8103.ts": "e5d6a506d966e312",
     "rules/wk8205.ts": "d000527c6371a05",
+    "rules/wk8042.ts": "6064c84481ae8551",
+    "rules/wk8006.ts": "6e04f754f79f076e",
     "rules/wk8041.ts": "4df512c93caaef50",
-    "rules/wk8102.ts": "78d4aac387107b56",
-    "rules/wk8005.ts": "a9a1b93b80f3aa51",
-    "rules/wk8303.ts": "c545464e2af8fbb9",
-    "rules/wk8204.ts": "31c3f8eac8455795",
+    "rules/wk8202.ts": "6bd950ae2128256c",
     "rules/wk8208.ts": "1133f9e53c174ae9",
-    "rules/wk8209.ts": "820df53f304e0a59",
-    "skills/chant-k8s.md": "f1c4ed163f8fa84c"
+    "rules/wk8105.ts": "8dbcfe399f23656a",
+    "rules/k8s-helpers.ts": "53a6d3bfbedb2852",
+    "rules/wk8207.ts": "6f2bc621d530afa2",
+    "skills/chant-k8s.md": "c7db82c3ba37c78",
+    "skills/chant-k8s-eks.md": "f79f31f058c7f2ed",
+    "skills/chant-k8s-patterns.md": "c5151ed799145c4b"
   },
-  "composite": "cfc40ee5b5214cda"
+  "composite": "586aea18d5400dd8"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "k8s",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "chantVersion": ">=0.1.0",
   "namespace": "K8s",
   "intrinsics": [],

package/dist/skills/chant-k8s-eks.md

@@ -0,0 +1,156 @@
+---
+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.

package/dist/skills/chant-k8s-patterns.md

@@ -0,0 +1,245 @@
+---
+skill: chant-k8s-patterns
+description: Advanced Kubernetes deployment patterns and composites
+user-invocable: true
+---
+
+# Advanced Kubernetes Patterns
+
+## Sidecar Patterns
+
+### SidecarApp — multi-container Deployment
+
+```typescript
+import { SidecarApp } from "@intentius/chant-lexicon-k8s";
+
+// Envoy sidecar proxy
+const { deployment, service } = SidecarApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  sidecars: [
+    {
+      name: "envoy",
+      image: "envoyproxy/envoy:v1.28",
+      ports: [{ containerPort: 9901, name: "admin" }],
+      resources: { requests: { cpu: "100m", memory: "128Mi" }, limits: { cpu: "200m", memory: "256Mi" } },
+    },
+  ],
+  initContainers: [
+    { name: "migrate", image: "api:1.0", command: ["python", "manage.py", "migrate"] },
+  ],
+  sharedVolumes: [{ name: "tmp", emptyDir: {} }],
+});
+```
+
+Common sidecar use cases:
+- **Envoy proxy** — service mesh, mTLS, traffic management
+- **Log forwarder** — Fluent Bit sidecar for app-specific log routing
+- **Auth proxy** — OAuth2 Proxy for authentication
+- **Config watcher** — reload config on ConfigMap changes
+
+## Config and Secret Mounting
+
+### ConfiguredApp — automatic volume wiring
+
+```typescript
+import { ConfiguredApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, configMap } = ConfiguredApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  // Mount ConfigMap as volume
+  configData: { "app.conf": "key=value\nother=setting" },
+  configMountPath: "/etc/api",
+  // Mount existing Secret as volume
+  secretName: "api-creds",
+  secretMountPath: "/secrets",
+  // Inject as environment variables
+  envFrom: { secretRef: "api-env-secret", configMapRef: "api-env-config" },
+  // Run migrations before the app starts
+  initContainers: [
+    { name: "migrate", image: "api:1.0", command: ["./migrate.sh"] },
+  ],
+});
+```
+
+### Volume patterns
+
+| Pattern | Use Case | ConfiguredApp Props |
+|---------|----------|---------------------|
+| ConfigMap as file | Config files, templates | `configData` + `configMountPath` |
+| Secret as file | TLS certs, credentials | `secretName` + `secretMountPath` |
+| ConfigMap as env | Simple key-value config | `envFrom.configMapRef` |
+| Secret as env | Database URLs, API keys | `envFrom.secretRef` |
+
+## TLS / cert-manager
+
+### SecureIngress — multi-host TLS with cert-manager
+
+```typescript
+import { SecureIngress } from "@intentius/chant-lexicon-k8s";
+
+const { ingress, certificate } = SecureIngress({
+  name: "app-ingress",
+  hosts: [
+    {
+      hostname: "api.example.com",
+      paths: [
+        { path: "/v1", serviceName: "api-v1", servicePort: 80 },
+        { path: "/v2", serviceName: "api-v2", servicePort: 80 },
+      ],
+    },
+    {
+      hostname: "admin.example.com",
+      paths: [{ path: "/", serviceName: "admin", servicePort: 80 }],
+    },
+  ],
+  clusterIssuer: "letsencrypt-prod",
+  ingressClassName: "nginx",
+});
+```
+
+Features:
+- Multiple hosts and paths per Ingress
+- Automatic cert-manager Certificate when `clusterIssuer` set
+- TLS secret auto-provisioned by cert-manager
+
+### cert-manager setup (prerequisite)
+
+```bash
+# Install cert-manager
+kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml
+
+# Create ClusterIssuer for Let's Encrypt
+kubectl apply -f - <<EOF
+apiVersion: cert-manager.io/v1
+kind: ClusterIssuer
+metadata:
+  name: letsencrypt-prod
+spec:
+  acme:
+    server: https://acme-v02.api.letsencrypt.org/directory
+    email: admin@example.com
+    privateKeySecretRef:
+      name: letsencrypt-prod-key
+    solvers:
+    - http01:
+        ingress:
+          class: nginx
+EOF
+```
+
+## Observability
+
+### MonitoredService — Prometheus monitoring
+
+```typescript
+import { MonitoredService } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, serviceMonitor, prometheusRule } = MonitoredService({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  metricsPort: 9090,
+  metricsPath: "/metrics",
+  scrapeInterval: "15s",
+  alertRules: [
+    {
+      name: "HighErrorRate",
+      expr: 'rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m]) > 0.05',
+      for: "5m",
+      severity: "critical",
+      annotations: { summary: "High error rate on {{ $labels.instance }}" },
+    },
+    {
+      name: "HighLatency",
+      expr: 'histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) > 1',
+      for: "10m",
+      severity: "warning",
+    },
+  ],
+});
+```
+
+### Prerequisites
+
+- Prometheus Operator installed (for ServiceMonitor/PrometheusRule CRDs)
+- Prometheus configured to discover ServiceMonitors
+
+## Network Isolation
+
+### NetworkIsolatedApp — per-app firewall rules
+
+```typescript
+import { NetworkIsolatedApp } from "@intentius/chant-lexicon-k8s";
+
+const { deployment, service, networkPolicy } = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  port: 8080,
+  allowIngressFrom: [
+    { podSelector: { "app.kubernetes.io/name": "frontend" } },
+    { namespaceSelector: { "kubernetes.io/metadata.name": "monitoring" } },
+  ],
+  allowEgressTo: [
+    { podSelector: { "app.kubernetes.io/name": "postgres" }, ports: [{ port: 5432 }] },
+    { podSelector: { "app.kubernetes.io/name": "redis" }, ports: [{ port: 6379 }] },
+  ],
+});
+```
+
+### Combining with NamespaceEnv
+
+Use NamespaceEnv for namespace-level default-deny, then NetworkIsolatedApp for per-app allow rules:
+
+```typescript
+// Namespace: deny all by default
+const ns = NamespaceEnv({ name: "prod", defaultDenyIngress: true, defaultDenyEgress: true });
+
+// App: allow specific traffic
+const app = NetworkIsolatedApp({
+  name: "api",
+  image: "api:1.0",
+  namespace: "prod",
+  allowIngressFrom: [{ podSelector: { "app.kubernetes.io/name": "gateway" } }],
+  allowEgressTo: [{ podSelector: { "app.kubernetes.io/name": "db" }, ports: [{ port: 5432 }] }],
+});
+```
+
+## Blue/Green and Canary
+
+These patterns use standard K8s resources — no special composite needed.
+
+### Blue/Green
+
+```typescript
+// Two Deployments with different versions
+const blue = WebApp({ name: "app-blue", image: "app:1.0", labels: { version: "blue" } });
+const green = WebApp({ name: "app-green", image: "app:2.0", labels: { version: "green" } });
+
+// Service points to active version — switch by changing selector
+// Active: blue → green (update the Service selector)
+```
+
+### Canary
+
+```typescript
+// Main deployment (90% traffic)
+const main = AutoscaledService({ name: "app", image: "app:1.0", minReplicas: 9, maxReplicas: 20, ... });
+
+// Canary deployment (10% traffic) — same app label, fewer replicas
+const canary = WebApp({ name: "app-canary", image: "app:2.0", replicas: 1, labels: { track: "canary" } });
+// Both share the same Service selector ("app.kubernetes.io/name": "app") for traffic splitting
+```
+
+## Gateway API (future direction)
+
+Gateway API is the successor to Ingress. Key differences:
+- **HTTPRoute** replaces Ingress rules
+- **Gateway** replaces IngressClass
+- Built-in traffic splitting, header matching, URL rewriting
+- Currently in beta — use Ingress/SecureIngress/AlbIngress for production today
+
+When Gateway API reaches GA, new composites will be added. For now, use CRD import if you need Gateway API resources.