@intentius/chant-lexicon-k8s 0.95.0 → 0.96.0

package/src/composites/otel-collector-shape.ts

@@ -0,0 +1,141 @@
+/**
+ * What `OtelCollector` and `OtelCollectorGateway` share beyond the container:
+ * reading ports and probes back from a declared config, and the annotations
+ * that record, in the built manifests, how each collector config is deployed.
+ *
+ * A post-synth check sees only the rendered YAML. The collector config is a
+ * string inside a ConfigMap, and whether it runs once per node or as N
+ * replicas behind a Service lives on another document. The annotations below
+ * join the two, so a check can take a ConfigMap, find its workload, and know
+ * the collector's role, its replica count, and (for an agent) which gateway
+ * it exports to and whether through `loadbalancing`.
+ */
+
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  buildCollectorConfig,
+  collectorEndpoints,
+  collectorYaml,
+  COLLECTOR_CONFIG_PATH,
+  type BuiltCollector,
+} from "@intentius/chant-lexicon-otel";
+
+/**
+ * Annotation keys the collector composites write on their ConfigMap and
+ * workload. `GkeOtelCollector` writes none of them; its output is fixed.
+ *
+ * | Key | On | Value |
+ * |---|---|---|
+ * | `role` | ConfigMap, workload | `agent` (a DaemonSet, one collector per node) or `gateway` (a Deployment) |
+ * | `workload` | ConfigMap | the workload that mounts it, `DaemonSet/<name>` or `Deployment/<name>`, in the ConfigMap's namespace |
+ * | `config` | workload | the name of the ConfigMap holding its `config.yaml` |
+ * | `gateways` | agent ConfigMap and DaemonSet | comma-separated `<namespace>/<gateway name>=<routing>`, where routing is `loadbalancing` or `service` |
+ *
+ * The replica count is the workload's own `spec.replicas`.
+ */
+export const OTEL_COLLECTOR_ANNOTATIONS = {
+  role: "otel.chant.dev/role",
+  workload: "otel.chant.dev/workload",
+  config: "otel.chant.dev/config",
+  gateways: "otel.chant.dev/gateways",
+} as const;
+
+export type CollectorRole = "agent" | "gateway";
+
+/** How an agent reaches a gateway: its ClusterIP Service, or each replica through `loadbalancing`. */
+export type GatewayRouting = "service" | "loadbalancing";
+
+/** The gateway an exporter built by `gatewayExporter()` points at. */
+export interface GatewayTarget {
+  name: string;
+  namespace: string;
+  routing: GatewayRouting;
+}
+
+const gatewayTargets = new WeakMap<object, GatewayTarget>();
+
+/** Record which gateway an exporter entity was built for. */
+export function markGatewayExporter(exporter: object, target: GatewayTarget): void {
+  gatewayTargets.set(exporter, target);
+}
+
+/** The gateways a built config's exporters were built for, in declaration order. */
+export function gatewayTargetsOf(built: BuiltCollector): GatewayTarget[] {
+  const out: GatewayTarget[] = [];
+  for (const c of built.components) {
+    const t = gatewayTargets.get(c);
+    if (t && !out.some((o) => o.name === t.name && o.namespace === t.namespace && o.routing === t.routing)) out.push(t);
+  }
+  return out;
+}
+
+/** The `gateways` annotation value for a list of targets. */
+export function gatewaysAnnotation(targets: GatewayTarget[]): string {
+  return targets.map((t) => `${t.namespace}/${t.name}=${t.routing}`).join(",");
+}
+
+/** A declared collector config, rendered, with the container and Service ports and probes read back from it. */
+export interface CollectorRuntime {
+  built: BuiltCollector;
+  configYaml: string;
+  configDir: string;
+  containerPorts: Array<{ containerPort: number; name: string }>;
+  /** The receiver ports, which the Services expose. The health port is left out. */
+  servicePorts: Array<{ name: string; port: number }>;
+  /** Security context and, when the config enables `health_check`, the probes. */
+  containerExtra: Record<string, unknown>;
+}
+
+export function collectorRuntime(entities: Declarable[]): CollectorRuntime {
+  const built = buildCollectorConfig(entities);
+  const { ports, healthCheck } = collectorEndpoints(built.config);
+  const configDir = COLLECTOR_CONFIG_PATH.slice(0, COLLECTOR_CONFIG_PATH.lastIndexOf("/"));
+
+  // The probe names the port. A health_check on a receiver's port reuses that
+  // port's name, since a container port is declared once.
+  const healthPortName = healthCheck ? (ports.find((p) => p.port === healthCheck.port)?.name ?? "health") : undefined;
+  const probe = healthCheck ? { httpGet: { path: healthCheck.path, port: healthPortName } } : undefined;
+  const containerPorts = [
+    ...ports.map((p) => ({ containerPort: p.port, name: p.name })),
+    ...(healthCheck && !ports.some((p) => p.port === healthCheck.port)
+      ? [{ containerPort: healthCheck.port, name: "health" }]
+      : []),
+  ];
+
+  return {
+    built,
+    configYaml: collectorYaml(entities),
+    configDir,
+    containerPorts,
+    servicePorts: ports.map((p) => ({ name: p.name, port: p.port })),
+    containerExtra: {
+      imagePullPolicy: "IfNotPresent",
+      securityContext: {
+        runAsNonRoot: true,
+        runAsUser: 10001,
+        readOnlyRootFilesystem: true,
+        allowPrivilegeEscalation: false,
+        capabilities: { drop: ["ALL"] },
+      },
+      ...(probe ? { livenessProbe: probe, readinessProbe: probe } : {}),
+    },
+  };
+}
+
+/**
+ * The namespaces whose Endpoints a config's `loadbalancing` exporters watch
+ * through the `k8s` resolver. A service given as `name` resolves in the
+ * collector's own namespace, `name.namespace` in that one.
+ */
+export function k8sResolverNamespaces(built: BuiltCollector, ownNamespace: string): string[] {
+  const out: string[] = [];
+  for (const [id, cfg] of Object.entries(built.config.exporters ?? {})) {
+    if (id !== "loadbalancing" && !id.startsWith("loadbalancing/")) continue;
+    const service = (cfg as { resolver?: { k8s?: { service?: string } } })?.resolver?.k8s?.service;
+    if (!service) continue;
+    const dot = service.indexOf(".");
+    const ns = dot === -1 ? ownNamespace : service.slice(dot + 1);
+    if (!out.includes(ns)) out.push(ns);
+  }
+  return out;
+}

package/src/composites/otel-collector.ts

@@ -10,22 +10,27 @@
  * read back from that config, so they follow whatever config is passed in.
  *
  * `GkeOtelCollector` builds the same DaemonSet, RBAC and ConfigMap for GKE.
+ * `OtelCollectorGateway` is the central tier agents export to; give this
+ * composite an exporter from `gatewayExporter()` to point it there.
  */
 
 import { Composite, mergeDefaults } from "@intentius/chant";
 import type { Declarable } from "@intentius/chant/declarable";
 import {
-  buildCollectorConfig,
-  collectorEndpoints,
-  collectorYaml,
   otlpCollector,
-  COLLECTOR_CONFIG_PATH,
   COLLECTOR_IMAGE,
   type OTelComponent,
   type Signal,
 } from "@intentius/chant-lexicon-otel";
-import { Service } from "../generated";
+import { Service, Role, RoleBinding } from "../generated";
 import { collectorAgentResources, type CollectorAgentResources } from "./otel-collector-agent";
+import {
+  collectorRuntime,
+  gatewaysAnnotation,
+  gatewayTargetsOf,
+  k8sResolverNamespaces,
+  OTEL_COLLECTOR_ANNOTATIONS,
+} from "./otel-collector-shape";
 
 export interface OtelCollectorProps {
   /** Agent name (default: "otel-collector"). */
@@ -62,11 +67,16 @@ export interface OtelCollectorProps {
     clusterRole?: Partial<Record<string, unknown>>;
     clusterRoleBinding?: Partial<Record<string, unknown>>;
     configMap?: Partial<Record<string, unknown>>;
+    endpointsRole?: Partial<Record<string, unknown>>;
+    endpointsRoleBinding?: Partial<Record<string, unknown>>;
   };
 }
 
 export type OtelCollectorResult = CollectorAgentResources & {
   service: InstanceType<typeof Service>;
+  /** Read access to Endpoints for a `loadbalancing` exporter's `k8s` resolver, in the resolved Service's namespace. */
+  endpointsRole?: InstanceType<typeof Role>;
+  endpointsRoleBinding?: InstanceType<typeof RoleBinding>;
 };
 
 /**
@@ -103,19 +113,14 @@ export const OtelCollector = Composite((props: OtelCollectorProps) => {
   };
 
   const entities = props.config ? [...props.config] : otlpCollector({ exporters: props.exporters, signals: props.signals });
-  const { ports, healthCheck } = collectorEndpoints(buildCollectorConfig(entities).config);
-  const configDir = COLLECTOR_CONFIG_PATH.slice(0, COLLECTOR_CONFIG_PATH.lastIndexOf("/"));
+  const runtime = collectorRuntime(entities);
+  const configMapName = `${name}-config`;
 
-  // The probe names the port. A health_check on a receiver's port reuses that
-  // port's name, since a container port is declared once.
-  const healthPortName = healthCheck ? (ports.find((p) => p.port === healthCheck.port)?.name ?? "health") : undefined;
-  const probe = healthCheck ? { httpGet: { path: healthCheck.path, port: healthPortName } } : undefined;
-  const containerPorts = [
-    ...ports.map((p) => ({ containerPort: p.port, name: p.name })),
-    ...(healthCheck && !ports.some((p) => p.port === healthCheck.port)
-      ? [{ containerPort: healthCheck.port, name: "health" }]
-      : []),
-  ];
+  // How this agent is deployed, and which gateways it sends to, recorded on
+  // the ConfigMap and the DaemonSet for post-synth checks (see
+  // OTEL_COLLECTOR_ANNOTATIONS).
+  const gateways = gatewayTargetsOf(runtime.built);
+  const shape: Record<string, string> = gateways.length ? { [OTEL_COLLECTOR_ANNOTATIONS.gateways]: gatewaysAnnotation(gateways) } : {};
 
   const resources = collectorAgentResources({
     name,
@@ -123,22 +128,23 @@ export const OtelCollector = Composite((props: OtelCollectorProps) => {
     image,
     commonLabels,
     extraLabels,
-    configYaml: collectorYaml(entities),
-    configDir,
-    ports: containerPorts,
+    configYaml: runtime.configYaml,
+    configDir: runtime.configDir,
+    ports: runtime.containerPorts,
     cpuRequest,
     memoryRequest,
     cpuLimit,
     memoryLimit,
-    containerExtra: {
-      securityContext: {
-        runAsNonRoot: true,
-        runAsUser: 10001,
-        readOnlyRootFilesystem: true,
-        allowPrivilegeEscalation: false,
-        capabilities: { drop: ["ALL"] },
-      },
-      ...(probe ? { livenessProbe: probe, readinessProbe: probe } : {}),
+    containerExtra: runtime.containerExtra,
+    workloadAnnotations: {
+      [OTEL_COLLECTOR_ANNOTATIONS.role]: "agent",
+      [OTEL_COLLECTOR_ANNOTATIONS.config]: configMapName,
+      ...shape,
+    },
+    configMapAnnotations: {
+      [OTEL_COLLECTOR_ANNOTATIONS.role]: "agent",
+      [OTEL_COLLECTOR_ANNOTATIONS.workload]: `DaemonSet/${name}`,
+      ...shape,
     },
     defaults: defs,
   });
@@ -152,9 +158,46 @@ export const OtelCollector = Composite((props: OtelCollectorProps) => {
     spec: {
       selector: { "app.kubernetes.io/name": name },
       internalTrafficPolicy: "Local",
-      ports: ports.map((p) => ({ name: p.name, port: p.port, targetPort: p.name, protocol: "TCP" })),
+      ports: runtime.servicePorts.map((p) => ({ name: p.name, port: p.port, targetPort: p.name, protocol: "TCP" })),
     },
   }, defs?.service));
 
-  return { ...resources, service };
+  // The loadbalancing exporter's k8s resolver runs in this agent and watches
+  // the gateway's headless Service, so the agent's ServiceAccount gets read
+  // access to Endpoints (what the resolver watches at the pinned collector
+  // version) and EndpointSlices (what later versions watch) in that namespace.
+  const resolverNamespaces = k8sResolverNamespaces(runtime.built, namespace);
+  if (resolverNamespaces.length > 1) {
+    throw new Error(
+      `OtelCollector ${name}: loadbalancing exporters resolve Services in ${resolverNamespaces.join(" and ")}; ` +
+        `one agent can watch Endpoints in one namespace. Use one gateway namespace, or grant the rest through defaults.clusterRole`,
+    );
+  }
+  const saName = (resources.serviceAccount as unknown as { props: { metadata: { name: string } } }).props.metadata.name;
+  const endpointsRbac = resolverNamespaces.length
+    ? {
+        endpointsRole: new Role(mergeDefaults({
+          metadata: {
+            name: `${name}-endpoints`,
+            namespace: resolverNamespaces[0],
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+          },
+          rules: [
+            { apiGroups: [""], resources: ["endpoints"], verbs: ["get", "list", "watch"] },
+            { apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: ["get", "list", "watch"] },
+          ],
+        }, defs?.endpointsRole)),
+        endpointsRoleBinding: new RoleBinding(mergeDefaults({
+          metadata: {
+            name: `${name}-endpoints`,
+            namespace: resolverNamespaces[0],
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+          },
+          roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: `${name}-endpoints` },
+          subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+        }, defs?.endpointsRoleBinding)),
+      }
+    : {};
+
+  return { ...resources, service, ...endpointsRbac };
 }, "OtelCollector");

package/src/index.ts

@@ -70,6 +70,7 @@ export {
   WebApp, StatefulApp, CronWorkload, AutoscaledService, WorkerPool, NamespaceEnv, NodeAgent,
   BatchJob, SecureIngress, ConfiguredApp, SidecarApp, MonitoredService, NetworkIsolatedApp,
   IrsaServiceAccount, AlbIngress, EbsStorageClass, EfsStorageClass, FluentBitAgent, ExternalDnsAgent, AdotCollector, OtelCollector,
+  OtelCollectorGateway, gatewayExporter, OTEL_COLLECTOR_ANNOTATIONS,
   MetricsServer, WorkloadIdentityServiceAccount, GcePdStorageClass, FilestoreStorageClass, GkeGateway, ConfigConnectorContext,
   GceIngress, CockroachDbCluster, CockroachDbRegionStack,
   RayCluster, RayJob, RayService,
@@ -93,6 +94,8 @@ export type {
   FluentBitAgentProps, FluentBitAgentResult, ExternalDnsAgentProps, ExternalDnsAgentResult,
   AdotCollectorProps, AdotCollectorResult,
   OtelCollectorProps, OtelCollectorResult,
+  OtelCollectorGatewayProps, OtelCollectorGatewayResult, GatewayExporterOptions, CollectorPolicyRule,
+  CollectorRole, GatewayRouting,
   MetricsServerProps, MetricsServerResult,
   WorkloadIdentityServiceAccountProps, WorkloadIdentityServiceAccountResult,
   GcePdStorageClassProps, GcePdStorageClassResult,

package/src/lint/audit-catalog.ts

@@ -46,6 +46,9 @@ export const k8sAuditCatalog: Record<string, RuleMeta> = {
   WK8503: auditRule("WK8503", "merge-worthy", "guidance", "Workload consumes a Secret nothing in the output produces", "Produce the Secret in the same build (Secret, ExternalSecret, InfisicalSecret, cert-manager Certificate), or declare its provenance with declareSecret() if it exists out of band.", { category: "correctness" }),
   WK8504: auditRule("WK8504", "merge-worthy", "guidance", "committed-encrypted secret declaration does not resolve", "Point `file` at the committed ciphertext, make its metadata.name match the declaration, and re-run `sops -e -i` so every data/stringData value is ENC[...].", { authority: [K8S_SECRETS] }),
   WK8505: auditRule("WK8505", "report-only", "guidance", "committed-encrypted secret with no Flux decryption wiring", "Add decryption: \"sops\" to the FluxAppFor reconciling the path that carries the ciphertext sidecar, or ignore if that Kustomization is declared in a different build. This check sees one build root at a time, so it goes silent once the secret and the Kustomization live in different build roots (chant #1939).", { category: "correctness" }),
+  WK8601: auditRule("WK8601", "merge-worthy", "guidance", "OpenTelemetry Collector runs tail_sampling on every node", "Move tail_sampling from the DaemonSet agent to a gateway Deployment, and send traces to it through a loadbalancing exporter routed by traceID.", { category: "correctness" }),
+  WK8602: auditRule("WK8602", "merge-worthy", "guidance", "Multi-replica tail sampling gateway reached without trace-aware load balancing", "Send traces to the gateway through a loadbalancing exporter with routing_key traceID (k8s resolver, or dns on a headless Service), or run the gateway with one replica. It goes silent when the senders are in another build root (chant #1939).", { category: "correctness" }),
+  WK8603: auditRule("WK8603", "merge-worthy", "guidance", "k8s_cluster receiver runs in every collector copy", "Run the k8s_cluster receiver in a single-replica Deployment, or set its k8s_leader_elector to a k8s_leader_elector extension enabled in service.extensions.", { category: "correctness" }),
 };
 
 // Prior art credits live beside the rules in ./audit-lineage.ts (see core audit/prior-art.ts).

package/src/lint/post-synth/index.ts

@@ -40,6 +40,9 @@ import { wk8502 } from "./wk8502";
 import { wk8503 } from "./wk8503";
 import { wk8504 } from "./wk8504";
 import { wk8505 } from "./wk8505";
+import { wk8601 } from "./wk8601";
+import { wk8602 } from "./wk8602";
+import { wk8603 } from "./wk8603";
 
 export const postSynthChecks: PostSynthCheck[] = [
   argo002,
@@ -82,4 +85,7 @@ export const postSynthChecks: PostSynthCheck[] = [
   wk8503,
   wk8504,
   wk8505,
+  wk8601,
+  wk8602,
+  wk8603,
 ];

package/src/lint/post-synth/otel-placement-helpers.ts

@@ -0,0 +1,277 @@
+/**
+ * Where each OpenTelemetry Collector config in a k8s build runs: the join
+ * WK8601, WK8602 and WK8603 read (chant #2899).
+ *
+ * The collector config is a YAML string inside a ConfigMap, and whether it
+ * runs once per node or as N replicas lives on another document, the workload
+ * that mounts it. A config is joined to its workload in this order:
+ *
+ * 1. The workload's `otel.chant.dev/config` annotation, written by
+ *    `OtelCollector` and `OtelCollectorGateway`, naming the ConfigMap whose
+ *    `config.yaml` it runs.
+ * 2. Otherwise the ConfigMaps the pod spec mounts as volumes (how
+ *    `GkeOtelCollector` and hand-written manifests link them), keeping only
+ *    data keys that parse as a collector config (a `service.pipelines` map).
+ *    When a container passes `--config=<path>`, only keys named by those
+ *    paths count.
+ *
+ * Anything this can't resolve (a ConfigMap or workload outside the build, a
+ * replica count that isn't a number) is left out, so the checks stay silent
+ * rather than guess. Like every bundle-join check they see one build root at
+ * a time (chant #1939).
+ *
+ * The annotation keys are repeated here rather than imported from the
+ * composites, whose module pulls in the otel lexicon; a test pins them to
+ * `OTEL_COLLECTOR_ANNOTATIONS`.
+ */
+
+import { load } from "js-yaml";
+import { extractContainers, extractPodSpec, type K8sManifest } from "./k8s-helpers";
+
+export const PLACEMENT_ANNOTATIONS = {
+  role: "otel.chant.dev/role",
+  workload: "otel.chant.dev/workload",
+  config: "otel.chant.dev/config",
+  gateways: "otel.chant.dev/gateways",
+} as const;
+
+/** The part of a collector config the placement checks read. */
+export interface CollectorConfigShape {
+  receivers?: Record<string, unknown>;
+  processors?: Record<string, unknown>;
+  exporters?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+  service: {
+    extensions?: unknown;
+    pipelines: Record<string, { receivers?: unknown; processors?: unknown; exporters?: unknown }>;
+  };
+}
+
+/** One collector config and the workload that runs it. */
+export interface CollectorPlacement {
+  workload: K8sManifest;
+  kind: "DaemonSet" | "Deployment" | "StatefulSet";
+  name: string;
+  namespace: string;
+  /**
+   * How many copies run at most: `spec.replicas` (1 when unset), raised to a
+   * HorizontalPodAutoscaler's `maxReplicas` when one targets the workload.
+   * Undefined for a DaemonSet, or when the count isn't a number.
+   */
+  replicas: number | undefined;
+  configMap: string;
+  key: string;
+  config: CollectorConfigShape;
+}
+
+const PLACED_KINDS = new Set(["DaemonSet", "Deployment", "StatefulSet"]);
+
+function ns(m: K8sManifest): string {
+  const n = m.metadata?.namespace;
+  return typeof n === "string" && n.length > 0 ? n : "default";
+}
+
+function annotations(m: K8sManifest): Record<string, unknown> {
+  const a = (m.metadata as { annotations?: unknown } | undefined)?.annotations;
+  return a && typeof a === "object" ? (a as Record<string, unknown>) : {};
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Parse a ConfigMap value as a collector config, or undefined when it isn't one. */
+export function parseCollectorConfig(text: unknown): CollectorConfigShape | undefined {
+  if (typeof text !== "string") return undefined;
+  let value: unknown;
+  try {
+    value = load(text);
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(value) || !isRecord(value.service) || !isRecord(value.service.pipelines)) return undefined;
+  return value as unknown as CollectorConfigShape;
+}
+
+/** The `type` of a component id: `tail_sampling/errors` is `tail_sampling`. */
+export function componentType(id: string): string {
+  const slash = id.indexOf("/");
+  return slash === -1 ? id : id.slice(0, slash);
+}
+
+function stringList(v: unknown): string[] {
+  return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+}
+
+/** The pipelines of one signal (`traces`, `traces/sampled`, ...) as [id, pipeline] pairs. */
+export function pipelinesOf(config: CollectorConfigShape, signal: string): Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> {
+  const out: Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> = [];
+  for (const [id, p] of Object.entries(config.service.pipelines)) {
+    if (componentType(id) !== signal || !isRecord(p)) continue;
+    out.push([id, { receivers: stringList(p.receivers), processors: stringList(p.processors), exporters: stringList(p.exporters) }]);
+  }
+  return out;
+}
+
+/** Every pipeline, whatever its signal. */
+export function allPipelines(config: CollectorConfigShape): Array<[string, { receivers: string[]; processors: string[]; exporters: string[] }]> {
+  return ["traces", "metrics", "logs"].flatMap((s) => pipelinesOf(config, s));
+}
+
+/** Processor ids of `type` that a traces pipeline runs. */
+export function tracePipelineProcessors(config: CollectorConfigShape, type: string): string[] {
+  const out = new Set<string>();
+  for (const [, p] of pipelinesOf(config, "traces")) {
+    for (const id of p.processors) if (componentType(id) === type) out.add(id);
+  }
+  return [...out];
+}
+
+/** The ConfigMap file names a workload's containers pass with `--config`. */
+function configArgNames(workload: K8sManifest): string[] {
+  const names: string[] = [];
+  for (const c of extractContainers(workload)) {
+    const argv = [...stringList(c.command), ...stringList(c.args)];
+    for (let i = 0; i < argv.length; i++) {
+      let path: string | undefined;
+      if (argv[i].startsWith("--config=")) path = argv[i].slice("--config=".length);
+      else if (argv[i] === "--config") path = argv[i + 1];
+      if (!path) continue;
+      // `--config=env:...`, `--config=yaml:...` and URLs are not files.
+      if (/^[a-z]+:/.test(path)) continue;
+      names.push(path.slice(path.lastIndexOf("/") + 1));
+    }
+  }
+  return names;
+}
+
+/** ConfigMap names mounted by a workload's pod spec, directly or through a projected volume. */
+function mountedConfigMaps(workload: K8sManifest): string[] {
+  const pod = extractPodSpec(workload);
+  const out: string[] = [];
+  for (const v of Array.isArray(pod?.volumes) ? pod.volumes : []) {
+    if (!isRecord(v)) continue;
+    const cm = isRecord(v.configMap) ? v.configMap.name : undefined;
+    if (typeof cm === "string") out.push(cm);
+    const sources = isRecord(v.projected) && Array.isArray(v.projected.sources) ? v.projected.sources : [];
+    for (const s of sources) {
+      const name = isRecord(s) && isRecord(s.configMap) ? s.configMap.name : undefined;
+      if (typeof name === "string") out.push(name);
+    }
+  }
+  return out;
+}
+
+/** The max replica count an HPA allows for kind/name in a namespace, if one targets it. */
+function hpaMax(manifests: K8sManifest[], kind: string, name: string, namespace: string): number | undefined {
+  let max: number | undefined;
+  for (const m of manifests) {
+    if (m.kind !== "HorizontalPodAutoscaler" || ns(m) !== namespace) continue;
+    const target = isRecord(m.spec?.scaleTargetRef) ? m.spec.scaleTargetRef : undefined;
+    if (!target || target.kind !== kind || target.name !== name) continue;
+    const n = m.spec?.maxReplicas;
+    if (typeof n === "number") max = Math.max(max ?? 0, n);
+  }
+  return max;
+}
+
+/** Join every collector config in the build to the workload that runs it. */
+export function collectorPlacements(manifests: K8sManifest[]): CollectorPlacement[] {
+  const configMaps = new Map<string, K8sManifest>();
+  for (const m of manifests) {
+    if (m.kind === "ConfigMap" && typeof m.metadata?.name === "string") configMaps.set(`${ns(m)}/${m.metadata.name}`, m);
+  }
+
+  const out: CollectorPlacement[] = [];
+  for (const workload of manifests) {
+    if (!workload.kind || !PLACED_KINDS.has(workload.kind)) continue;
+    const name = workload.metadata?.name;
+    if (typeof name !== "string") continue;
+    const namespace = ns(workload);
+    const kind = workload.kind as CollectorPlacement["kind"];
+
+    let replicas: number | undefined;
+    if (kind !== "DaemonSet") {
+      const r = workload.spec?.replicas;
+      const base = r === undefined || r === null ? 1 : typeof r === "number" ? r : undefined;
+      const hpa = hpaMax(manifests, kind, name, namespace);
+      replicas = base === undefined ? undefined : Math.max(base, hpa ?? 0);
+    }
+
+    const annotated = annotations(workload)[PLACEMENT_ANNOTATIONS.config];
+    const candidates: Array<{ configMap: string; keys?: string[] }> =
+      typeof annotated === "string"
+        ? [{ configMap: annotated, keys: ["config.yaml"] }]
+        : mountedConfigMaps(workload).map((configMap) => ({ configMap }));
+    const argNames = configArgNames(workload);
+
+    for (const { configMap, keys } of candidates) {
+      const cm = configMaps.get(`${namespace}/${configMap}`);
+      if (!cm || !isRecord(cm.data)) continue;
+      const parsed: Array<[string, CollectorConfigShape]> = [];
+      for (const [key, text] of Object.entries(cm.data)) {
+        if (keys && !keys.includes(key)) continue;
+        const config = parseCollectorConfig(text);
+        if (config) parsed.push([key, config]);
+      }
+      const named = parsed.filter(([key]) => argNames.includes(key));
+      for (const [key, config] of named.length > 0 ? named : parsed) {
+        out.push({ workload, kind, name, namespace, replicas, configMap, key, config });
+      }
+    }
+  }
+  return out;
+}
+
+/** How a placement is described in a message: `DaemonSet observability/otel-agent`. */
+export function describePlacement(p: CollectorPlacement): string {
+  return `${p.kind} ${p.namespace}/${p.name}`;
+}
+
+// ── Services and exporters (WK8602) ─────────────────────────────────
+
+/** A Service that selects a workload's pods. */
+export interface SelectingService {
+  name: string;
+  namespace: string;
+  headless: boolean;
+}
+
+/** The Services in a workload's namespace whose selector matches its pod template labels. */
+export function servicesSelecting(manifests: K8sManifest[], workload: K8sManifest): SelectingService[] {
+  const template = isRecord(workload.spec?.template) ? workload.spec.template : undefined;
+  const labels = isRecord(template?.metadata) && isRecord(template.metadata.labels) ? template.metadata.labels : {};
+  const out: SelectingService[] = [];
+  for (const m of manifests) {
+    if (m.kind !== "Service" || ns(m) !== ns(workload) || typeof m.metadata?.name !== "string") continue;
+    const selector = isRecord(m.spec?.selector) ? m.spec.selector : undefined;
+    if (!selector || Object.keys(selector).length === 0) continue;
+    if (!Object.entries(selector).every(([k, v]) => labels[k] === v)) continue;
+    out.push({ name: m.metadata.name, namespace: ns(m), headless: m.spec?.clusterIP === "None" });
+  }
+  return out;
+}
+
+/**
+ * The Service a hostname names, as `name.namespace`, when it has the shape of
+ * cluster DNS: `name`, `name.ns`, `name.ns.svc` or `name.ns.svc.<domain>`.
+ * A bare `name` resolves in the caller's namespace.
+ */
+export function serviceOfHost(host: string, callerNamespace: string): string | undefined {
+  const parts = host.split(".");
+  if (parts.some((p) => p.length === 0)) return undefined;
+  if (parts.length === 1) return `${parts[0]}.${callerNamespace}`;
+  if (parts.length === 2) return `${parts[0]}.${parts[1]}`;
+  if (parts[2] === "svc") return `${parts[0]}.${parts[1]}`;
+  return undefined;
+}
+
+/** The host of an exporter endpoint: `host:port`, `scheme://host:port/path` or `dns:///host:port`. */
+export function hostOfEndpoint(endpoint: unknown): string | undefined {
+  if (typeof endpoint !== "string" || endpoint.length === 0) return undefined;
+  let rest = endpoint.replace(/^[a-z][a-z0-9+.-]*:\/\/\/?/i, "");
+  rest = rest.split("/")[0];
+  if (rest.startsWith("[")) return undefined;
+  const colon = rest.lastIndexOf(":");
+  return colon === -1 ? rest : rest.slice(0, colon);
+}