@intentius/chant-lexicon-k8s 0.95.1 → 0.97.0

package/src/composites/otel-collector-gateway.test.ts

@@ -0,0 +1,260 @@
+import { describe, expect, test } from "vitest";
+import { load, loadAll } from "js-yaml";
+import { expandComposite } from "@intentius/chant";
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  DebugExporter,
+  LoadBalancingExporter,
+  OtlpReceiver,
+  Pipeline,
+  TailSamplingProcessor,
+  collectorTopology,
+  validateCollectorConfig,
+  type CollectorConfig,
+} from "@intentius/chant-lexicon-otel";
+import { k8sSerializer } from "../serializer";
+import { OtelCollector } from "./otel-collector";
+import { OtelCollectorGateway, gatewayExporter } from "./otel-collector-gateway";
+import { OTEL_COLLECTOR_ANNOTATIONS as A } from "./otel-collector-shape";
+
+function p(member: unknown): any {
+  return (member as { props: unknown }).props;
+}
+
+function config(result: { configMap: unknown }): CollectorConfig {
+  return load(p(result.configMap).data["config.yaml"]) as CollectorConfig;
+}
+
+function agentOf(exporter: ReturnType<typeof gatewayExporter>, props: Record<string, unknown> = {}) {
+  const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+  return OtelCollector({
+    ...props,
+    config: [new Pipeline({ signal: "traces", receivers: [otlp], exporters: [exporter] })],
+  });
+}
+
+function manifests(instances: Record<string, any>): Array<Record<string, any>> {
+  const entities = new Map<string, Declarable>();
+  for (const [name, instance] of Object.entries(instances)) {
+    for (const [k, v] of expandComposite(name, instance)) entities.set(k, v);
+  }
+  const out = k8sSerializer.serialize(entities);
+  return loadAll(typeof out === "string" ? out : out.primary) as Array<Record<string, any>>;
+}
+
+describe("OtelCollectorGateway", () => {
+  test("returns a Deployment, two Services, a ServiceAccount and a ConfigMap, and no RBAC by default", () => {
+    const gw = OtelCollectorGateway({});
+    for (const key of ["deployment", "service", "headlessService", "serviceAccount", "configMap"]) {
+      expect((gw as any)[key], key).toBeDefined();
+    }
+    expect(gw.clusterRole).toBeUndefined();
+    expect(gw.clusterRoleBinding).toBeUndefined();
+  });
+
+  test("defaults to two replicas of otel-gateway in observability, running the default config", () => {
+    const gw = OtelCollectorGateway({});
+    const d = p(gw.deployment);
+    expect(d.metadata).toMatchObject({ name: "otel-gateway", namespace: "observability" });
+    expect(d.spec.replicas).toBe(2);
+    expect(d.spec.template.spec.tolerations).toBeUndefined();
+    expect(d.spec.template.spec.serviceAccountName).toBe("otel-gateway-sa");
+    expect(validateCollectorConfig(config(gw))).toEqual([]);
+  });
+
+  test("the ClusterIP Service and the headless Service expose the config's receiver ports", () => {
+    const gw = OtelCollectorGateway({});
+    const ports = [
+      { name: "otlp-grpc", port: 4317, targetPort: "otlp-grpc", protocol: "TCP" },
+      { name: "otlp-http", port: 4318, targetPort: "otlp-http", protocol: "TCP" },
+    ];
+    expect(p(gw.service).spec).toEqual({ type: "ClusterIP", selector: { "app.kubernetes.io/name": "otel-gateway" }, ports });
+    expect(p(gw.headlessService).metadata.name).toBe("otel-gateway-headless");
+    expect(p(gw.headlessService).spec).toEqual({ clusterIP: "None", selector: { "app.kubernetes.io/name": "otel-gateway" }, ports });
+    const container = p(gw.deployment).spec.template.spec.containers[0];
+    expect(container.ports.map((x: any) => x.containerPort)).toEqual([4317, 4318, 13133]);
+    expect(container.readinessProbe).toEqual({ httpGet: { path: "/", port: "health" } });
+    expect(container.securityContext.capabilities).toEqual({ drop: ["ALL"] });
+  });
+
+  test("clusterRules adds a ClusterRole bound to the gateway's ServiceAccount", () => {
+    const rules = [{ apiGroups: [""], resources: ["pods", "nodes"], verbs: ["get", "list", "watch"] }];
+    const gw = OtelCollectorGateway({ name: "gw", namespace: "obs", clusterRules: rules });
+    expect(p(gw.clusterRole).rules).toEqual(rules);
+    expect(p(gw.clusterRoleBinding).subjects).toEqual([{ kind: "ServiceAccount", name: "gw-sa", namespace: "obs" }]);
+    expect(p(gw.clusterRoleBinding).roleRef.name).toBe("gw-role");
+  });
+
+  test("the Deployment and ConfigMap say they are a gateway and name each other", () => {
+    const gw = OtelCollectorGateway({ name: "gw" });
+    expect(p(gw.deployment).metadata.annotations).toEqual({ [A.role]: "gateway", [A.config]: "gw-config" });
+    expect(p(gw.configMap).metadata.annotations).toEqual({ [A.role]: "gateway", [A.workload]: "Deployment/gw" });
+    expect(p(gw.deployment).metadata.labels["app.kubernetes.io/component"]).toBe("gateway");
+  });
+
+  test("defaults override a member", () => {
+    const gw = OtelCollectorGateway({ defaults: { deployment: { spec: { replicas: 5 } }, headlessService: { spec: { publishNotReadyAddresses: true } } } });
+    expect(p(gw.deployment).spec.replicas).toBe(5);
+    expect(p(gw.headlessService).spec.publishNotReadyAddresses).toBe(true);
+  });
+});
+
+describe("gatewayExporter", () => {
+  test("by default, an otlp exporter at the gateway's ClusterIP Service", () => {
+    const exporter = gatewayExporter(OtelCollectorGateway({}));
+    expect(exporter.componentId).toBe("otlp/gateway");
+    expect(p(exporter)).toEqual({ name: "gateway", endpoint: "otel-gateway.observability.svc:4317", tls: { insecure: true } });
+  });
+
+  test("with loadBalance, a loadbalancing exporter on the headless Service through the k8s resolver", () => {
+    const exporter = gatewayExporter(OtelCollectorGateway({}), { loadBalance: true });
+    expect(exporter.componentId).toBe("loadbalancing/gateway");
+    expect(p(exporter)).toEqual({
+      name: "gateway",
+      routing_key: "traceID",
+      protocol: { otlp: { tls: { insecure: true } } },
+      resolver: { k8s: { service: "otel-gateway-headless.observability", ports: [4317] } },
+    });
+  });
+
+  test("the dns resolver resolves the headless Service's name", () => {
+    const exporter = gatewayExporter(OtelCollectorGateway({}), { loadBalance: true, resolver: "dns" });
+    expect(p(exporter).resolver).toEqual({ dns: { hostname: "otel-gateway-headless.observability.svc", port: "4317" } });
+  });
+
+  test.each([
+    [{ name: "tail", namespace: "observability" }, "tail.observability.svc:4317", "tail-headless.observability"],
+    [{ name: "otel-gateway", namespace: "telemetry" }, "otel-gateway.telemetry.svc:4317", "otel-gateway-headless.telemetry"],
+    [{ name: "edge", namespace: "prod-obs" }, "edge.prod-obs.svc:4317", "edge-headless.prod-obs"],
+  ])("renaming the gateway or moving its namespace moves the agent's endpoint (%o)", (props, endpoint, service) => {
+    const gw = OtelCollectorGateway(props);
+    const direct = config(agentOf(gatewayExporter(gw)));
+    expect(direct.exporters?.["otlp/gateway"]).toMatchObject({ endpoint });
+    const balanced = config(agentOf(gatewayExporter(gw, { loadBalance: true })));
+    expect(balanced.exporters?.["loadbalancing/gateway"]).toMatchObject({ resolver: { k8s: { service } } });
+  });
+
+  test("the port follows the gateway's receiver", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:14317" } } });
+    const gw = OtelCollectorGateway({ config: [new Pipeline({ signal: "traces", receivers: [otlp], exporters: [new DebugExporter({})] })] });
+    expect(p(gatewayExporter(gw)).endpoint).toBe("otel-gateway.observability.svc:14317");
+    expect(p(gatewayExporter(gw, { loadBalance: true })).resolver.k8s.ports).toEqual([14317]);
+  });
+
+  test("a gateway without an OTLP gRPC port is refused with the ports it has", () => {
+    const otlp = new OtlpReceiver({ protocols: { http: { endpoint: "0.0.0.0:4318" } } });
+    const gw = OtelCollectorGateway({ config: [new Pipeline({ signal: "traces", receivers: [otlp], exporters: [new DebugExporter({})] })] });
+    expect(() => gatewayExporter(gw)).toThrow(/no port named "otlp-grpc" \(it has: otlp-http\)/);
+  });
+
+  test("the otel topology reports the gateway as the exporter's endpoint", () => {
+    const agent = agentOf(gatewayExporter(OtelCollectorGateway({ namespace: "obs" }), { loadBalance: true }));
+    const exporters = collectorTopology(config(agent)).exporters;
+    expect(exporters.map((e: any) => e.endpoints)).toEqual([["otel-gateway-headless.obs:4317"]]);
+  });
+});
+
+describe("OtelCollector wired to a gateway", () => {
+  test("through loadbalancing with the k8s resolver: a Role in the gateway's namespace for the agent's ServiceAccount", () => {
+    const gw = OtelCollectorGateway({ namespace: "gateways" });
+    const agent = agentOf(gatewayExporter(gw, { loadBalance: true }), { name: "agent", namespace: "agents" });
+    expect(p(agent.endpointsRole).metadata).toMatchObject({ name: "agent-endpoints", namespace: "gateways" });
+    expect(p(agent.endpointsRole).rules).toEqual([
+      { apiGroups: [""], resources: ["endpoints"], verbs: ["get", "list", "watch"] },
+      { apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: ["get", "list", "watch"] },
+    ]);
+    expect(p(agent.endpointsRoleBinding).metadata.namespace).toBe("gateways");
+    expect(p(agent.endpointsRoleBinding).roleRef).toEqual({ apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: "agent-endpoints" });
+    expect(p(agent.endpointsRoleBinding).subjects).toEqual([{ kind: "ServiceAccount", name: "agent-sa", namespace: "agents" }]);
+  });
+
+  test("through the Service or the dns resolver: no Role", () => {
+    const gw = OtelCollectorGateway({});
+    expect(agentOf(gatewayExporter(gw)).endpointsRole).toBeUndefined();
+    expect(agentOf(gatewayExporter(gw, { loadBalance: true, resolver: "dns" })).endpointsRole).toBeUndefined();
+    expect(OtelCollector({}).endpointsRole).toBeUndefined();
+  });
+
+  test("a hand-written loadbalancing exporter with the k8s resolver gets the Role too", () => {
+    const lb = new LoadBalancingExporter({ name: "gw", resolver: { k8s: { service: "gw-headless" } } });
+    const agent = agentOf(lb, { namespace: "obs" });
+    expect(p(agent.endpointsRole).metadata.namespace).toBe("obs");
+    expect(p(agent.configMap).metadata.annotations[A.gateways]).toBeUndefined();
+  });
+
+  test("resolvers in two namespaces are refused", () => {
+    const otlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const a = gatewayExporter(OtelCollectorGateway({ namespace: "one" }), { loadBalance: true, name: "a" });
+    const b = gatewayExporter(OtelCollectorGateway({ namespace: "two" }), { loadBalance: true, name: "b" });
+    expect(() =>
+      OtelCollector({ config: [new Pipeline({ signal: "traces", receivers: [otlp], exporters: [a, b] })] }),
+    ).toThrow(/resolve Services in one and two/);
+  });
+
+  test("the agent's ConfigMap and DaemonSet name the gateway and how they reach it", () => {
+    const gw = OtelCollectorGateway({ name: "gw", namespace: "obs" });
+    const balanced = agentOf(gatewayExporter(gw, { loadBalance: true }), { name: "agent" });
+    expect(p(balanced.configMap).metadata.annotations).toEqual({
+      [A.role]: "agent",
+      [A.workload]: "DaemonSet/agent",
+      [A.gateways]: "obs/gw=loadbalancing",
+    });
+    expect(p(balanced.daemonSet).metadata.annotations).toEqual({
+      [A.role]: "agent",
+      [A.config]: "agent-config",
+      [A.gateways]: "obs/gw=loadbalancing",
+    });
+    const direct = agentOf(gatewayExporter(gw), { name: "agent" });
+    expect(p(direct.configMap).metadata.annotations[A.gateways]).toBe("obs/gw=service");
+  });
+
+  test("an unwired agent says it is an agent and nothing more", () => {
+    const agent = OtelCollector({});
+    expect(p(agent.configMap).metadata.annotations).toEqual({ [A.role]: "agent", [A.workload]: "DaemonSet/otel-collector" });
+  });
+});
+
+// What a post-synth check sees: only the built YAML. Starting from each
+// collector ConfigMap, the annotations reach its workload and the gateway it
+// sends to, with no knowledge of the composites.
+describe("deployment shape in the built manifests", () => {
+  test("a check can join each collector config to its workload, replicas and gateway routing", () => {
+    const tail = new TailSamplingProcessor({
+      decision_wait: "5s",
+      policies: [{ name: "errors", type: "status_code", status_code: { status_codes: ["ERROR"] } }],
+    });
+    const gwOtlp = new OtlpReceiver({ protocols: { grpc: { endpoint: "0.0.0.0:4317" } } });
+    const gateway = OtelCollectorGateway({
+      replicas: 3,
+      config: [new Pipeline({ signal: "traces", receivers: [gwOtlp], processors: [tail], exporters: [new DebugExporter({})] })],
+    });
+    const agent = agentOf(gatewayExporter(gateway, { loadBalance: true }), { name: "agent" });
+    const docs = manifests({ gateway, agent });
+
+    const find = (kind: string, ns: string, name: string) =>
+      docs.find((d) => d.kind === kind && d.metadata.namespace === ns && d.metadata.name === name);
+
+    const shapes = docs
+      .filter((d) => d.kind === "ConfigMap" && d.metadata.annotations?.[A.role])
+      .map((cm) => {
+        const [kind, name] = cm.metadata.annotations[A.workload].split("/");
+        const workload = find(kind, cm.metadata.namespace, name)!;
+        expect(workload.metadata.annotations[A.config]).toBe(cm.metadata.name);
+        const cfg = load(cm.data["config.yaml"]) as CollectorConfig;
+        return {
+          role: cm.metadata.annotations[A.role],
+          kind: workload.kind,
+          replicas: workload.spec.replicas,
+          tailSampling: Object.keys(cfg.processors ?? {}).includes("tail_sampling"),
+          gateways: cm.metadata.annotations[A.gateways],
+        };
+      });
+
+    expect(shapes).toEqual([
+      { role: "gateway", kind: "Deployment", replicas: 3, tailSampling: true, gateways: undefined },
+      { role: "agent", kind: "DaemonSet", replicas: undefined, tailSampling: false, gateways: "observability/otel-gateway=loadbalancing" },
+    ]);
+    // The Role the k8s resolver needs is in the build, next to the gateway.
+    expect(find("Role", "observability", "agent-endpoints")).toBeDefined();
+  });
+});

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

@@ -0,0 +1,325 @@
+/**
+ * OtelCollectorGateway composite: an OpenTelemetry Collector gateway, the
+ * central tier that per-node agents export to.
+ *
+ * A Deployment runs the collector with `replicas` pods, its config mounted
+ * from a ConfigMap. A ClusterIP Service takes the agents' OTLP traffic, and a
+ * headless Service lists the individual pods, which is what the agents'
+ * `loadbalancing` exporter resolves when every span of a trace has to reach
+ * the same replica (tail sampling, spanmetrics). The config is declared with
+ * the otel lexicon; ports and probes are read back from it, as `OtelCollector`
+ * does.
+ *
+ * `gatewayExporter()` builds the agent side: an exporter whose endpoint comes
+ * from this composite's Services, so renaming the gateway or moving it to
+ * another namespace moves the agents with it.
+ */
+
+import { Composite, mergeDefaults } from "@intentius/chant";
+import type { Declarable } from "@intentius/chant/declarable";
+import {
+  otlpCollector,
+  LoadBalancingExporter,
+  OtlpExporter,
+  COLLECTOR_IMAGE,
+  type LoadBalancingRoutingKey,
+  type OTelComponent,
+  type Signal,
+  type TLSClientSettings,
+} from "@intentius/chant-lexicon-otel";
+import { Deployment, Service, ServiceAccount, ClusterRole, ClusterRoleBinding, ConfigMap, PodDisruptionBudget } from "../generated";
+import { collectorConfigMap, collectorContainer } from "./otel-collector-agent";
+import {
+  collectorRuntime,
+  markGatewayExporter,
+  OTEL_COLLECTOR_ANNOTATIONS,
+  type GatewayRouting,
+} from "./otel-collector-shape";
+
+/** One RBAC rule, as a ClusterRole lists it. */
+export interface CollectorPolicyRule {
+  apiGroups: string[];
+  resources: string[];
+  verbs: string[];
+  resourceNames?: string[];
+}
+
+export interface OtelCollectorGatewayProps {
+  /** Gateway name (default: "otel-gateway"). */
+  name?: string;
+  /** Namespace (default: "observability"). */
+  namespace?: string;
+  /** Number of collector pods (default: 2). */
+  replicas?: number;
+  /** Collector image (default: the contrib image at the otel lexicon's pinned collector version). */
+  image?: string;
+  /**
+   * The collector config, as otel lexicon entities (components and
+   * pipelines). Replaces the default config, and `exporters` and `signals`
+   * are then ignored.
+   */
+  config?: Iterable<Declarable>;
+  /** Exporters for the default config (default: one `debug` exporter). */
+  exporters?: OTelComponent<"exporter", string, any>[];
+  /** Signals the default config has pipelines for (default: traces, metrics and logs). */
+  signals?: Signal[];
+  /**
+   * Cluster-wide read access the config needs, e.g. for a `k8s_cluster`
+   * receiver or a `k8sattributes` processor. When given, the composite adds a
+   * ClusterRole with these rules bound to the gateway's ServiceAccount.
+   * Default: none.
+   */
+  clusterRules?: CollectorPolicyRule[];
+  /** Additional labels. */
+  labels?: Record<string, string>;
+  /** CPU request (default: "200m"). */
+  cpuRequest?: string;
+  /** Memory request (default: "512Mi"). */
+  memoryRequest?: string;
+  /** CPU limit (default: "1"). */
+  cpuLimit?: string;
+  /** Memory limit (default: "1Gi"). */
+  memoryLimit?: string;
+  /** Per-member defaults for fine-grained overrides. */
+  defaults?: {
+    deployment?: Partial<Record<string, unknown>>;
+    service?: Partial<Record<string, unknown>>;
+    headlessService?: Partial<Record<string, unknown>>;
+    serviceAccount?: Partial<Record<string, unknown>>;
+    configMap?: Partial<Record<string, unknown>>;
+    podDisruptionBudget?: Partial<Record<string, unknown>>;
+    clusterRole?: Partial<Record<string, unknown>>;
+    clusterRoleBinding?: Partial<Record<string, unknown>>;
+  };
+}
+
+export type OtelCollectorGatewayResult = {
+  deployment: InstanceType<typeof Deployment>;
+  service: InstanceType<typeof Service>;
+  headlessService: InstanceType<typeof Service>;
+  serviceAccount: InstanceType<typeof ServiceAccount>;
+  configMap: InstanceType<typeof ConfigMap>;
+  /** With more than one replica: at most one pod down at a time during voluntary disruptions. */
+  podDisruptionBudget?: InstanceType<typeof PodDisruptionBudget>;
+  clusterRole?: InstanceType<typeof ClusterRole>;
+  clusterRoleBinding?: InstanceType<typeof ClusterRoleBinding>;
+};
+
+/**
+ * Create an OtelCollectorGateway composite. Returns a Deployment, a ClusterIP
+ * Service, a headless Service, a ServiceAccount and a ConfigMap, a
+ * PodDisruptionBudget when there is more than one replica, and a ClusterRole
+ * and binding when `clusterRules` is set.
+ *
+ * @example
+ * ```ts
+ * import { OtelCollector, OtelCollectorGateway, gatewayExporter } from "@intentius/chant-lexicon-k8s";
+ *
+ * export const gateway = OtelCollectorGateway({ replicas: 3 });
+ * export const agent = OtelCollector({ exporters: [gatewayExporter(gateway, { loadBalance: true })], signals: ["traces"] });
+ * ```
+ */
+export const OtelCollectorGateway = Composite((props: OtelCollectorGatewayProps) => {
+  const {
+    name = "otel-gateway",
+    namespace = "observability",
+    replicas = 2,
+    image = COLLECTOR_IMAGE,
+    labels: extraLabels = {},
+    cpuRequest = "200m",
+    memoryRequest = "512Mi",
+    cpuLimit = "1",
+    memoryLimit = "1Gi",
+    defaults: defs,
+  } = props;
+
+  const commonLabels: Record<string, string> = {
+    "app.kubernetes.io/name": name,
+    "app.kubernetes.io/managed-by": "chant",
+    ...extraLabels,
+  };
+  const gatewayLabels = { ...commonLabels, "app.kubernetes.io/component": "gateway" };
+  const saName = `${name}-sa`;
+  const configMapName = `${name}-config`;
+
+  const entities = props.config ? [...props.config] : otlpCollector({ exporters: props.exporters, signals: props.signals });
+  const runtime = collectorRuntime(entities);
+
+  const container = collectorContainer({
+    name,
+    image,
+    configDir: runtime.configDir,
+    ports: runtime.containerPorts,
+    cpuRequest,
+    memoryRequest,
+    cpuLimit,
+    memoryLimit,
+    containerExtra: runtime.containerExtra,
+  });
+
+  const deployment = new Deployment(mergeDefaults({
+    metadata: {
+      name,
+      namespace,
+      labels: gatewayLabels,
+      annotations: {
+        [OTEL_COLLECTOR_ANNOTATIONS.role]: "gateway",
+        [OTEL_COLLECTOR_ANNOTATIONS.config]: configMapName,
+      },
+    },
+    spec: {
+      replicas,
+      selector: { matchLabels: { "app.kubernetes.io/name": name } },
+      template: {
+        metadata: { labels: { "app.kubernetes.io/name": name, "app.kubernetes.io/component": "gateway", ...extraLabels } },
+        spec: {
+          serviceAccountName: saName,
+          containers: [container],
+          volumes: [{ name: "config", configMap: { name: configMapName } }],
+        },
+      },
+    },
+  }, defs?.deployment));
+
+  const servicePorts = runtime.servicePorts.map((p) => ({ name: p.name, port: p.port, targetPort: p.name, protocol: "TCP" }));
+
+  const service = new Service(mergeDefaults({
+    metadata: { name, namespace, labels: gatewayLabels },
+    spec: {
+      type: "ClusterIP",
+      selector: { "app.kubernetes.io/name": name },
+      ports: servicePorts,
+    },
+  }, defs?.service));
+
+  // A headless Service's DNS name and Endpoints list every ready pod, which is
+  // what the agents' loadbalancing exporter hashes traces across.
+  const headlessService = new Service(mergeDefaults({
+    metadata: { name: `${name}-headless`, namespace, labels: gatewayLabels },
+    spec: {
+      clusterIP: "None",
+      selector: { "app.kubernetes.io/name": name },
+      ports: servicePorts,
+    },
+  }, defs?.headlessService));
+
+  const serviceAccount = new ServiceAccount(mergeDefaults({
+    metadata: { name: saName, namespace, labels: gatewayLabels },
+  }, defs?.serviceAccount));
+
+  const configMap = collectorConfigMap(
+    { namespace, commonLabels, configYaml: runtime.configYaml, defaults: defs },
+    configMapName,
+    {
+      [OTEL_COLLECTOR_ANNOTATIONS.role]: "gateway",
+      [OTEL_COLLECTOR_ANNOTATIONS.workload]: `Deployment/${name}`,
+    },
+  );
+
+  const pdb = replicas > 1
+    ? {
+        podDisruptionBudget: new PodDisruptionBudget(mergeDefaults({
+          metadata: { name, namespace, labels: gatewayLabels },
+          spec: { maxUnavailable: 1, selector: { matchLabels: { "app.kubernetes.io/name": name } } },
+        }, defs?.podDisruptionBudget)),
+      }
+    : {};
+
+  const rbac = props.clusterRules?.length
+    ? {
+        clusterRole: new ClusterRole(mergeDefaults({
+          metadata: { name: `${name}-role`, labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" } },
+          rules: props.clusterRules,
+        }, defs?.clusterRole)),
+        clusterRoleBinding: new ClusterRoleBinding(mergeDefaults({
+          metadata: { name: `${name}-binding`, labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" } },
+          roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "ClusterRole", name: `${name}-role` },
+          subjects: [{ kind: "ServiceAccount", name: saName, namespace }],
+        }, defs?.clusterRoleBinding)),
+      }
+    : {};
+
+  return { deployment, service, headlessService, serviceAccount, configMap, ...pdb, ...rbac };
+}, "OtelCollectorGateway");
+
+// ── Agent side ───────────────────────────────────────────────────────
+
+export interface GatewayExporterOptions {
+  /** Exporter name, so the id is `otlp/<name>` or `loadbalancing/<name>` (default: "gateway"). */
+  name?: string;
+  /**
+   * Send each trace to one gateway replica through the headless Service with
+   * a `loadbalancing` exporter, instead of to the ClusterIP Service with an
+   * `otlp` exporter. Needed in front of a multi-replica gateway that runs
+   * `tail_sampling` or `spanmetrics`. Default: false.
+   */
+  loadBalance?: boolean;
+  /**
+   * How the `loadbalancing` exporter finds the replicas: `k8s` watches the
+   * headless Service's Endpoints (the agent composite then adds the RBAC for
+   * it), `dns` resolves its name. Default: "k8s".
+   */
+  resolver?: "k8s" | "dns";
+  /** What the `loadbalancing` exporter hashes on (default: "traceID"). */
+  routingKey?: LoadBalancingRoutingKey;
+  /** The gateway Service port to send to, by name (default: "otlp-grpc"). */
+  port?: string;
+  /** TLS for the connection to the gateway (default: `{ insecure: true }`, plaintext inside the cluster). */
+  tls?: TLSClientSettings;
+}
+
+interface ServiceMeta {
+  name: string;
+  namespace: string;
+  ports: Array<{ name?: string; port: number }>;
+}
+
+function serviceMeta(service: InstanceType<typeof Service>): ServiceMeta {
+  const p = (service as unknown as { props: { metadata: { name: string; namespace: string }; spec: { ports?: ServiceMeta["ports"] } } }).props;
+  return { name: p.metadata.name, namespace: p.metadata.namespace, ports: p.spec.ports ?? [] };
+}
+
+/**
+ * The exporter an agent uses to send to a gateway, built from the gateway's
+ * own declaration: its Services' names, its namespace, and the port its
+ * config listens on.
+ *
+ * By default an `otlp` exporter at `<service>.<namespace>.svc:<port>`. With
+ * `loadBalance`, a `loadbalancing` exporter routing by trace id to the
+ * headless Service, through the `k8s` resolver (`<headless>.<namespace>`) or
+ * the `dns` resolver (`<headless>.<namespace>.svc`). Put it in the agent's
+ * pipelines like any other exporter; `OtelCollector` records the link in its
+ * annotations and adds the RBAC the `k8s` resolver needs.
+ */
+export function gatewayExporter(
+  gateway: OtelCollectorGatewayResult,
+  options: GatewayExporterOptions = {},
+): InstanceType<typeof OtlpExporter> | InstanceType<typeof LoadBalancingExporter> {
+  const { name = "gateway", loadBalance = false, resolver = "k8s", routingKey = "traceID", port: portName = "otlp-grpc", tls = { insecure: true } } = options;
+  const deploymentName = (gateway.deployment as unknown as { props: { metadata: { name: string } } }).props.metadata.name;
+  const target = serviceMeta(loadBalance ? gateway.headlessService : gateway.service);
+  const port = target.ports.find((p) => p.name === portName)?.port;
+  if (port === undefined) {
+    const names = target.ports.map((p) => p.name).join(", ") || "none";
+    throw new Error(
+      `gatewayExporter: Service ${target.namespace}/${target.name} has no port named "${portName}" (it has: ${names}); ` +
+        `give the gateway an OTLP gRPC receiver or pass the port name`,
+    );
+  }
+  const routing: GatewayRouting = loadBalance ? "loadbalancing" : "service";
+
+  const exporter = loadBalance
+    ? new LoadBalancingExporter({
+        name,
+        routing_key: routingKey,
+        protocol: { otlp: { tls } },
+        resolver:
+          resolver === "dns"
+            ? { dns: { hostname: `${target.name}.${target.namespace}.svc`, port: String(port) } }
+            : { k8s: { service: `${target.name}.${target.namespace}`, ports: [port] } },
+      })
+    : new OtlpExporter({ name, endpoint: `${target.name}.${target.namespace}.svc:${port}`, tls });
+
+  markGatewayExporter(exporter, { name: deploymentName, namespace: target.namespace, routing });
+  return exporter;
+}