@intentius/chant-lexicon-k8s 0.95.0 → 0.96.0

package/dist/rules/wk8602.ts

@@ -0,0 +1,133 @@
+/**
+ * WK8602: `tail_sampling` on a multi-replica gateway that collectors reach
+ * without trace-aware load balancing
+ *
+ * Tail sampling needs every span of a trace in the same process. Behind a
+ * ClusterIP Service, connections are spread across the gateway replicas with
+ * no regard for trace ids, so the spans of one trace land on different
+ * replicas and each samples a fragment. The fix is a `loadbalancing`
+ * exporter in front, routing by `traceID` to the replicas themselves (the
+ * `k8s` resolver on any Service that selects them, or the `dns` resolver on
+ * a headless one). A single-replica gateway passes.
+ *
+ * The check fires on evidence, not on absence: another collector in the
+ * build whose traces pipeline exports to one of the gateway's Services
+ * through `otlp`/`otlphttp`, through a `loadbalancing` exporter routed by
+ * something other than `traceID`, or through the `dns` resolver on a
+ * ClusterIP Service (one virtual IP, so one backend per connection). When
+ * the senders live in another build root, or are applications talking to
+ * the gateway directly, it stays silent (chant #1939).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { docsToManifests } from "./k8s-helpers";
+import {
+  collectorPlacements,
+  componentType,
+  describePlacement,
+  hostOfEndpoint,
+  pipelinesOf,
+  serviceOfHost,
+  servicesSelecting,
+  tracePipelineProcessors,
+  type CollectorPlacement,
+} from "./otel-placement-helpers";
+
+const TRACE_ID_KEYS = new Set([undefined, null, "", "traceID"]);
+
+function record(v: unknown): Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v) ? (v as Record<string, unknown>) : {};
+}
+
+/** Why each traces exporter of `sender` that reaches `services` does so without trace-aware routing. */
+function unroutedExporters(sender: CollectorPlacement, services: Map<string, boolean>): string[] {
+  const reasons: string[] = [];
+  const seen = new Set<string>();
+  for (const [, pipeline] of pipelinesOf(sender.config, "traces")) {
+    for (const id of pipeline.exporters) {
+      if (seen.has(id)) continue;
+      seen.add(id);
+      const type = componentType(id);
+      const cfg = record(sender.config.exporters?.[id]);
+
+      if (type === "loadbalancing") {
+        const resolver = record(cfg.resolver);
+        const k8sService = record(resolver.k8s).service;
+        const dnsHost = record(resolver.dns).hostname;
+        let target: string | undefined;
+        if (typeof k8sService === "string") {
+          const svc = serviceOfHost(k8sService, sender.namespace);
+          if (svc && services.has(svc)) target = svc;
+        } else if (typeof dnsHost === "string") {
+          const svc = serviceOfHost(dnsHost, sender.namespace);
+          if (svc && services.has(svc)) {
+            target = svc;
+            if (!services.get(svc)) {
+              reasons.push(`${id} resolves ClusterIP Service ${svc} through dns, which returns one virtual IP rather than the replicas`);
+              continue;
+            }
+          }
+        }
+        if (target && !TRACE_ID_KEYS.has(cfg.routing_key as string | undefined)) {
+          reasons.push(`${id} routes by ${String(cfg.routing_key)}, not traceID`);
+        }
+        continue;
+      }
+
+      if (type === "otlp" || type === "otlphttp") {
+        for (const field of ["endpoint", "traces_endpoint"]) {
+          const host = hostOfEndpoint(cfg[field]);
+          const svc = host ? serviceOfHost(host, sender.namespace) : undefined;
+          if (svc && services.has(svc)) {
+            reasons.push(`${id} sends to Service ${svc} directly`);
+            break;
+          }
+        }
+      }
+    }
+  }
+  return reasons;
+}
+
+export const wk8602: PostSynthCheck = {
+  id: "WK8602",
+  description:
+    "OpenTelemetry Collector gateway runs tail_sampling on more than one replica, but collectors send it traces without a loadbalancing exporter routed by traceID. Sees one build root at a time (chant #1939).",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const manifests = docsToManifests(ctx);
+    const placements = collectorPlacements(manifests);
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const gateway of placements) {
+      if (gateway.kind === "DaemonSet" || gateway.replicas === undefined || gateway.replicas <= 1) continue;
+      const tail = tracePipelineProcessors(gateway.config, "tail_sampling");
+      if (tail.length === 0) continue;
+
+      const services = new Map<string, boolean>();
+      for (const s of servicesSelecting(manifests, gateway.workload)) services.set(`${s.name}.${s.namespace}`, s.headless);
+      if (services.size === 0) continue;
+
+      const senders = new Set<string>();
+      for (const sender of placements) {
+        if (sender.workload === gateway.workload) continue;
+        const key = `${sender.kind}/${sender.namespace}/${sender.name}/${sender.configMap}/${sender.key}`;
+        if (senders.has(key)) continue;
+        senders.add(key);
+        const reasons = unroutedExporters(sender, services);
+        if (reasons.length === 0) continue;
+        diagnostics.push({
+          checkId: "WK8602",
+          severity: "warning",
+          message:
+            `${describePlacement(gateway)} runs ${tail.join(", ")} on up to ${gateway.replicas} replicas, and ${describePlacement(sender)} sends it traces without trace-aware routing: ${reasons.join("; ")}. ` +
+            `Spans of one trace land on different replicas and each samples a fragment. ` +
+            `Export traces through a loadbalancing exporter with routing_key traceID (gatewayExporter(gateway, { loadBalance: true })), or run one replica.`,
+          entity: gateway.name,
+          lexicon: "k8s",
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/dist/rules/wk8603.ts

@@ -0,0 +1,66 @@
+/**
+ * WK8603: `k8s_cluster` receiver in a collector that runs more than one copy
+ * without a leader elector
+ *
+ * The `k8s_cluster` receiver reports cluster-level metrics and entity events
+ * (nodes, deployments, pods, resource quotas) by watching the API server.
+ * Every copy of the collector reports every object, so in a DaemonSet the
+ * cluster is reported once per node, and in a Deployment once per replica:
+ * duplicated series and N watches against the API server. Run it in a
+ * single-replica Deployment, or set the receiver's `k8s_leader_elector` to a
+ * `k8s_leader_elector` extension enabled in `service.extensions` (both ship in
+ * otelcol-contrib and otelcol-k8s at the pinned v0.130.0), so only the
+ * leader collects.
+ *
+ * One build root at a time (chant #1939).
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { docsToManifests } from "./k8s-helpers";
+import { allPipelines, collectorPlacements, componentType, describePlacement, type CollectorConfigShape } from "./otel-placement-helpers";
+
+/** Why a `k8s_cluster` receiver is not behind a working leader elector, or undefined when it is. */
+function missingLeader(config: CollectorConfigShape, id: string): string | undefined {
+  const cfg = config.receivers?.[id];
+  const ref = typeof cfg === "object" && cfg !== null ? (cfg as Record<string, unknown>).k8s_leader_elector : undefined;
+  if (typeof ref !== "string" || ref.length === 0) return `${id} has no k8s_leader_elector`;
+  if (componentType(ref) !== "k8s_leader_elector" || !(config.extensions && ref in config.extensions)) {
+    return `${id} names k8s_leader_elector "${ref}", which is not a declared k8s_leader_elector extension`;
+  }
+  const enabled = Array.isArray(config.service.extensions) && config.service.extensions.includes(ref);
+  if (!enabled) return `${id} names k8s_leader_elector "${ref}", which is not enabled in service.extensions`;
+  return undefined;
+}
+
+export const wk8603: PostSynthCheck = {
+  id: "WK8603",
+  description:
+    "OpenTelemetry Collector runs the k8s_cluster receiver in a DaemonSet or multi-replica workload without a k8s_leader_elector; every copy reports every cluster object. Sees one build root at a time (chant #1939).",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    for (const p of collectorPlacements(docsToManifests(ctx))) {
+      const copies = p.kind === "DaemonSet" ? "every node" : p.replicas !== undefined && p.replicas > 1 ? `each of up to ${p.replicas} replicas` : undefined;
+      if (!copies) continue;
+
+      const used = new Set<string>();
+      for (const [, pipeline] of allPipelines(p.config)) {
+        for (const id of pipeline.receivers) if (componentType(id) === "k8s_cluster") used.add(id);
+      }
+      const reasons = [...used].map((id) => missingLeader(p.config, id)).filter((r): r is string => r !== undefined);
+      if (reasons.length === 0) continue;
+
+      diagnostics.push({
+        checkId: "WK8603",
+        severity: "warning",
+        message:
+          `${describePlacement(p)} runs the k8s_cluster receiver on ${copies} (ConfigMap ${p.configMap}, ${p.key}): ${reasons.join("; ")}. ` +
+          `Each copy reports every cluster object, duplicating series and API server watches. ` +
+          `Run it in a single-replica Deployment, or reference a k8s_leader_elector extension from the receiver and enable it in service.extensions.`,
+        entity: p.name,
+        lexicon: "k8s",
+      });
+    }
+    return diagnostics;
+  },
+};

package/dist/serializer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAyRlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAkO3B,CAAC"}
+{"version":3,"file":"serializer.d.ts","sourceRoot":"","sources":["../src/serializer.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,6BAA6B,CAAC;AAiSlG;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,UAkO3B,CAAC"}

package/dist/skills/chant-k8s.md

@@ -171,6 +171,8 @@ Composites are higher-level functions that produce multiple coordinated K8s reso
 | Multi-host TLS Ingress (cert-manager) | **SecureIngress** | Ingress + optional Certificate |
 | HPA metrics provider | **MetricsServer** | Deployment + Service + RBAC + APIService |
 | CockroachDB cluster | **CockroachDbCluster** | StatefulSet + Services + PVCs + RBAC + optional CertificateRequests |
+| OpenTelemetry agent on every node | **OtelCollector** | DaemonSet + node-local Service + RBAC + ConfigMap |
+| OpenTelemetry gateway tier | **OtelCollectorGateway** | Deployment + ClusterIP and headless Services + PDB + ConfigMap; point agents at it with `gatewayExporter(gateway, { loadBalance: true })` |
 
 ### Decision Tree — AWS (EKS) Composites
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k8s",
-  "version": "0.95.0",
+  "version": "0.96.0",
   "description": "Kubernetes lexicon for chant — declarative IaC in TypeScript",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -73,11 +73,12 @@
   },
   "dependencies": {
     "@intentius/chant-lexicon-otel": "*",
+    "@intentius/chant-lexicon-prometheus": "*",
     "js-yaml": "^4.3.1",
     "@types/js-yaml": "^4.0.9"
   },
   "optionalDependencies": {
-    "@intentius/chant-k8s-client": "^0.95.0"
+    "@intentius/chant-k8s-client": "^0.96.0"
   },
   "devDependencies": {
     "@intentius/chant": "*",
@@ -85,7 +86,7 @@
   },
   "peerDependencies": {
     "zod": "^4.3.6",
-    "@intentius/chant": "^0.95.0",
+    "@intentius/chant": "^0.96.0",
     "typescript": "^5.9.3"
   }
 }

package/src/composites/__snapshots__/gke-otel-collector.snapshot.test.ts.snap

@@ -0,0 +1,401 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`GkeOtelCollector output > with Workload Identity 1`] = `
+"apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: gke-otel-collector
+  namespace: gke-monitoring
+  labels:
+    app.kubernetes.io/name: gke-otel-collector
+    app.kubernetes.io/managed-by: chant
+    app.kubernetes.io/component: agent
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: gke-otel-collector
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: gke-otel-collector
+    spec:
+      serviceAccountName: gke-otel-collector-sa
+      containers:
+        - name: gke-otel-collector
+          image: otel/opentelemetry-collector-contrib:latest
+          args:
+            - --config=/etc/otel/config.yaml
+          ports:
+            - containerPort: 4317
+              name: otlp-grpc
+            - containerPort: 4318
+              name: otlp-http
+          resources:
+            requests:
+              cpu: '100m'
+              memory: '256Mi'
+            limits:
+              cpu: '500m'
+              memory: '512Mi'
+          volumeMounts:
+            - name: config
+              mountPath: /etc/otel
+              readOnly: true
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 10001
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+      volumes:
+        - name: config
+          configMap:
+            name: gke-otel-collector-config
+      tolerations:
+        - operator: Exists
+
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: gke-otel-collector-sa
+  namespace: gke-monitoring
+  labels:
+    app.kubernetes.io/name: gke-otel-collector
+    app.kubernetes.io/managed-by: chant
+    app.kubernetes.io/component: agent
+  annotations:
+    iam.gke.io/gcp-service-account: otel@test-project.iam.gserviceaccount.com
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: gke-otel-collector-role
+  labels:
+    app.kubernetes.io/name: gke-otel-collector
+    app.kubernetes.io/managed-by: chant
+    app.kubernetes.io/component: rbac
+rules:
+  - apiGroups:
+      - ''
+    resources:
+      - pods
+      - nodes
+      - endpoints
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - apps
+    resources:
+      - replicasets
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - batch
+    resources:
+      - jobs
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - ''
+    resources:
+      - nodes/proxy
+    verbs:
+      - get
+  - apiGroups:
+      - ''
+    resources:
+      - nodes/stats
+      - configmaps
+      - events
+    verbs:
+      - create
+      - get
+  - apiGroups:
+      - ''
+    resources:
+      - configmaps
+    verbs:
+      - get
+      - update
+      - create
+    resourceNames:
+      - otel-container-insight-clusterleader
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: gke-otel-collector-binding
+  labels:
+    app.kubernetes.io/name: gke-otel-collector
+    app.kubernetes.io/managed-by: chant
+    app.kubernetes.io/component: rbac
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: gke-otel-collector-role
+subjects:
+  - kind: ServiceAccount
+    name: gke-otel-collector-sa
+    namespace: gke-monitoring
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: gke-otel-collector-config
+  namespace: gke-monitoring
+  labels:
+    app.kubernetes.io/name: gke-otel-collector
+    app.kubernetes.io/managed-by: chant
+    app.kubernetes.io/component: config
+data:
+  config.yaml: |
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+            endpoint: 0.0.0.0:4317
+          http:
+            endpoint: 0.0.0.0:4318
+    
+    processors:
+      batch:
+        timeout: 30s
+        send_batch_size: 8192
+      resourcedetection:
+        detectors: [gcp]
+        timeout: 10s
+    
+    exporters:
+      googlecloud:
+        project: test-project
+        metric:
+          prefix: custom.googleapis.com/test-cluster
+        trace:
+          attribute_mappings:
+            - key: service.name
+              replacement: g.co/r/service/name
+    
+    service:
+      pipelines:
+        metrics:
+          receivers: [otlp]
+          processors: [batch, resourcedetection]
+          exporters: [googlecloud]
+        traces:
+          receivers: [otlp]
+          processors: [batch, resourcedetection]
+          exporters: [googlecloud]
+"
+`;
+
+exports[`GkeOtelCollector output > with every prop set 1`] = `
+"apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: otel
+  namespace: telemetry
+  labels:
+    app.kubernetes.io/name: otel
+    app.kubernetes.io/managed-by: chant
+    team: obs
+    app.kubernetes.io/component: agent
+spec:
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: otel
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: otel
+        team: obs
+    spec:
+      serviceAccountName: otel-sa
+      containers:
+        - name: otel
+          image: otel/opentelemetry-collector-contrib:0.100.0
+          args:
+            - --config=/etc/otel/config.yaml
+          ports:
+            - containerPort: 4317
+              name: otlp-grpc
+            - containerPort: 4318
+              name: otlp-http
+          resources:
+            requests:
+              cpu: '50m'
+              memory: '128Mi'
+            limits:
+              cpu: '1'
+              memory: '1Gi'
+          volumeMounts:
+            - name: config
+              mountPath: /etc/otel
+              readOnly: true
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 10001
+            readOnlyRootFilesystem: true
+            allowPrivilegeEscalation: false
+      volumes:
+        - name: config
+          configMap:
+            name: otel-config
+      tolerations:
+        - operator: Exists
+  updateStrategy:
+    type: OnDelete
+
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: otel-sa
+  namespace: telemetry
+  labels:
+    app.kubernetes.io/name: otel
+    app.kubernetes.io/managed-by: chant
+    team: obs
+    app.kubernetes.io/component: agent
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRole
+metadata:
+  name: otel-role
+  labels:
+    app.kubernetes.io/name: otel
+    app.kubernetes.io/managed-by: chant
+    team: obs
+    app.kubernetes.io/component: rbac
+rules:
+  - apiGroups:
+      - ''
+    resources:
+      - pods
+      - nodes
+      - endpoints
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - apps
+    resources:
+      - replicasets
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - batch
+    resources:
+      - jobs
+    verbs:
+      - get
+      - list
+      - watch
+  - apiGroups:
+      - ''
+    resources:
+      - nodes/proxy
+    verbs:
+      - get
+  - apiGroups:
+      - ''
+    resources:
+      - nodes/stats
+      - configmaps
+      - events
+    verbs:
+      - create
+      - get
+  - apiGroups:
+      - ''
+    resources:
+      - configmaps
+    verbs:
+      - get
+      - update
+      - create
+    resourceNames:
+      - otel-container-insight-clusterleader
+
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: otel-binding
+  labels:
+    app.kubernetes.io/name: otel
+    app.kubernetes.io/managed-by: chant
+    team: obs
+    app.kubernetes.io/component: rbac
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: ClusterRole
+  name: otel-role
+subjects:
+  - kind: ServiceAccount
+    name: otel-sa
+    namespace: telemetry
+
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: otel-config
+  namespace: telemetry
+  labels:
+    app.kubernetes.io/name: otel
+    app.kubernetes.io/managed-by: chant
+    team: obs
+    app.kubernetes.io/component: config
+data:
+  config.yaml: |
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+            endpoint: 0.0.0.0:4317
+          http:
+            endpoint: 0.0.0.0:4318
+    
+    processors:
+      batch:
+        timeout: 30s
+        send_batch_size: 8192
+      resourcedetection:
+        detectors: [gcp]
+        timeout: 10s
+    
+    exporters:
+      googlecloud:
+        project: p-123456
+        metric:
+          prefix: custom.googleapis.com/c1
+        trace:
+          attribute_mappings:
+            - key: service.name
+              replacement: g.co/r/service/name
+    
+    service:
+      pipelines:
+        metrics:
+          receivers: [otlp]
+          processors: [batch, resourcedetection]
+          exporters: [googlecloud]
+        traces:
+          receivers: [otlp]
+          processors: [batch, resourcedetection]
+          exporters: [googlecloud]
+"
+`;