@intentius/chant-lexicon-k8s 0.124.30 → 0.124.32

package/dist/composites/operator-stack.js

@@ -0,0 +1,268 @@
+/**
+ * OperatorStack composite (#1940, epic #1487) — the operating loop
+ * materialized in-cluster as a declared estate on gitops principles: one
+ * Namespace, one CronJob per hosted `ConvergeOp` tick, and RBAC scoped to
+ * what that tick can actually do. chant declares the loop that runs chant
+ * with its own k8s lexicon — the same estate discipline as any other app.
+ *
+ * ## Why a CronJob, not the operator daemon
+ *
+ * Issue #1485 ("chant operator: native durable ticks without Temporal")
+ * names cron, a systemd timer, a k8s CronJob, a CI schedule, and the
+ * `chant operator` daemon as interchangeable safe invokers of the same
+ * thing: one converge tick. A k8s CronJob invoking `chant run <name>` per
+ * tick is that issue's own "cron … invokes the tick" case, not a dependency
+ * on the daemon it proposes — #1485 is a separate, still-unmerged runtime
+ * (lease fencing, `chant operator status`, durable gate-as-fact semantics).
+ * `OperatorStack`'s container command is deliberately `chant run <name>`,
+ * the one-shot local tick `ConvergeOp` (#1484) already ships and tests
+ * against (`packages/core/src/op/composites/converge-op.ts`'s own doc:
+ * "one-shot runnable locally for a single tick"). When #1485 lands, a
+ * caller can override `command` to shell out to `chant operator tick`
+ * instead — this composite doesn't need to change for that; only the
+ * command a caller passes does.
+ *
+ * `concurrencyPolicy: "Forbid"` is the k8s-native analogue of
+ * `ConvergeOp`'s own `schedule.overlap: "skip"` policy — never queue a
+ * second tick behind one still running.
+ *
+ * ## RBAC derivation
+ *
+ * `ConvergeOp` adds no authority an environment did not already grant
+ * (#1484's Autonomy table). `OperatorStack` re-derives the same bound at the
+ * k8s RBAC layer, from the Op configs alone (see the Layering note below for
+ * what this module imports and what it restates): for each hosted
+ * ConvergeOp, walk its `dispatchTargets` (the OpConfigs its rule table's
+ * `run()` actions may name) through `classifyOpVerbClass`
+ * (`packages/core/src/op/op-verb-class.ts`, #1954), then keep only the
+ * highest verb class this host's `dial` could ever actually free-run —
+ * exactly `convergeTick`'s own `verbClassAllowedToDispatch` gate and
+ * `OPS014`'s build-time refusal, restated as an RBAC ceiling:
+ *
+ * - `dial: "observe"` never dispatches (report-only) → read-only RBAC,
+ *   regardless of what the rule table's targets could otherwise do.
+ * - `dial: "reconcile"` only free-runs a read-only target (OPS014 refuses a
+ *   mutating dispatch under reconcile in v1) → read-only RBAC.
+ * - `dial: "apply"` free-runs read-only and mutating targets → RBAC gains
+ *   create/update/patch, never delete.
+ * - A `dispatchTargets` entry that itself classifies `destructive` is
+ *   refused outright, at construction — OPS014 already refuses a
+ *   destructive `run()` target under any dial in v1 (a converge tick runs
+ *   unattended, and a destructive dispatch needs a person's approval before
+ *   it is attempted, not a gate read after the fact), so a `destructive` target
+ *   reaching this composite is either a config bypassing that build check
+ *   or a target `OperatorStack` should never grant permission toward.
+ *   `never delete`, unconditionally, in v1 — no verb class here ever grants
+ *   `delete`/`deletecollection`, and no rule ever uses `"*"`.
+ *
+ * Each hosted ConvergeOp gets its own ServiceAccount + Role + RoleBinding
+ * (never one shared identity across differently-scoped loops) — a read-only
+ * loop and a mutating loop sharing a Namespace get RBAC as different as
+ * their own dials allow, never the union.
+ *
+ * ## Layering
+ *
+ * `OperatorStackConvergeHost` restates the handful of `ConvergeOp` fields
+ * this composite actually needs (`name`, `schedule`, `env`, `dial`)
+ * structurally rather than importing `ConvergeOpConfig`: the CronJob is
+ * built from a host description, not from an Op config, and a caller that
+ * has neither should still be able to describe one. `dispatchTargets` takes
+ * plain `OpConfig`-shaped values from `@intentius/chant/op` (a dependency
+ * this lexicon already has via the `@intentius/chant` peer dependency),
+ * the same type `classifyOpVerbClass` itself takes.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { classifyOpVerbClass } from "@intentius/chant/op";
+import { Namespace, CronJob, ServiceAccount, Role, RoleBinding } from "../generated/index.js";
+import { validateCronJobSchedule } from "./cron-schedule.js";
+// ── RBAC derivation ──────────────────────────────────────────────────────
+/** Default RBAC resource kinds — the common workload surface a converge tick observes/acts on. Deliberately excludes `secrets`: a host that needs secret access opts in explicitly via its own `resources`. */
+export const DEFAULT_RESOURCE_RULES = [
+    { apiGroups: [""], resources: ["pods", "services", "configmaps", "persistentvolumeclaims", "events"] },
+    { apiGroups: ["apps"], resources: ["deployments", "statefulsets", "daemonsets", "replicasets"] },
+    { apiGroups: ["batch"], resources: ["jobs", "cronjobs"] },
+];
+const READ_VERBS = ["get", "list", "watch"];
+const MUTATE_VERBS = [...READ_VERBS, "create", "update", "patch"];
+/** RBAC verbs for a derived class. Never returns `delete`/`deletecollection`/`"*"` — v1 has no path to a destructive dispatch (see this module's RBAC derivation doc). */
+function rbacVerbsFor(verbClass) {
+    return verbClass === "mutating" ? MUTATE_VERBS : READ_VERBS;
+}
+/**
+ * Whether `dial` ever actually free-runs a dispatch classified `verbClass` —
+ * restates `convergeTick`'s own `verbClassAllowedToDispatch`
+ * (`packages/core/src/op/activities/converge.ts`) so the RBAC ceiling
+ * this composite grants matches the ceiling the tick itself enforces at
+ * runtime, without importing across the lexicon boundary (see this module's
+ * Layering doc).
+ */
+function dialAllowsVerbClass(dial, verbClass) {
+    if (verbClass === "read-only")
+        return true;
+    if (verbClass === "mutating")
+        return dial === "apply";
+    return false; // destructive: never free-run under any dial in v1.
+}
+/**
+ * Derive the highest verb class a host's ServiceAccount actually needs:
+ * the max, across `dispatchTargets`, of each target's own class — but only
+ * counting a target `dial` could ever actually dispatch (one it can't just
+ * gets reported, per `OPS014`/`convergeTick`, and needs no elevated grant).
+ * A `dispatchTargets` entry that classifies `destructive` is refused
+ * outright rather than silently ignored — see this module's RBAC
+ * derivation doc on why a destructive target reaching this composite is
+ * itself a refusal, not a no-op.
+ */
+export function deriveHostVerbClass(hostName, dial, dispatchTargets) {
+    let effective = "read-only";
+    for (const target of dispatchTargets) {
+        const verbClass = classifyOpVerbClass(target);
+        if (verbClass === "destructive") {
+            throw new Error(`OperatorStack host "${hostName}": a dispatchTargets entry classifies as destructive — ConvergeOp v1 refuses a destructive run() target under any dial ` +
+                `(OPS014; a converge tick runs unattended, and a destructive dispatch needs a person's approval before it is attempted, not a gate the tick reads after it has already committed to the run). ` +
+                `Remove it from dispatchTargets, and run the destructive op yourself through its gate.`);
+        }
+        if (!dialAllowsVerbClass(dial, verbClass))
+            continue; // dial refuses this dispatch — reported, not run; needs no elevated RBAC
+        if (verbClass === "mutating")
+            effective = "mutating";
+    }
+    return effective;
+}
+// ── Composite ────────────────────────────────────────────────────────────
+/**
+ * Create an OperatorStack composite — a Namespace hosting one CronJob (+
+ * least-privilege ServiceAccount/Role/RoleBinding) per ConvergeOp, the
+ * in-cluster declared estate for the operating loop.
+ *
+ * @example
+ * ```ts
+ * import { OperatorStack } from "@intentius/chant-lexicon-k8s";
+ *
+ * const stack = OperatorStack({
+ *   name: "chant-operator",
+ *   image: "ghcr.io/intentius/chant:0.49.0",
+ *   converge: [
+ *     { name: "fountain-observe", schedule: "*\/10 * * * *", env: "staging", dial: "observe" },
+ *     { name: "fountain-converge", schedule: "*\/10 * * * *", env: "staging", dial: "apply", dispatchTargets: [fountainApplyOp] },
+ *   ],
+ * });
+ * ```
+ */
+export const OperatorStack = Composite((props) => {
+    const { name, namespace: namespaceName = name, image, converge, defaultResources = DEFAULT_RESOURCE_RULES, successfulJobsHistoryLimit = 3, failedJobsHistoryLimit = 1, labels: extraLabels = {}, defaults: defs, } = props;
+    if (converge.length === 0) {
+        throw new Error(`OperatorStack "${name}": at least one ConvergeOp to host is required — a namespace with no CronJob has nothing to converge.`);
+    }
+    const seen = new Set();
+    for (const host of converge) {
+        if (!host.name || host.name.trim().length === 0) {
+            throw new Error(`OperatorStack "${name}": every hosted ConvergeOp needs a non-empty name.`);
+        }
+        if (seen.has(host.name)) {
+            throw new Error(`OperatorStack "${name}": duplicate hosted ConvergeOp name "${host.name}" — CronJob/ServiceAccount names would collide.`);
+        }
+        seen.add(host.name);
+        validateCronJobSchedule(`OperatorStack "${name}", host "${host.name}"`, host.schedule);
+    }
+    if (!image || image.trim().length === 0) {
+        throw new Error(`OperatorStack "${name}": image is required — the CronJob has nothing to run.`);
+    }
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        "app.kubernetes.io/component": "operator",
+        ...extraLabels,
+    };
+    const namespace = new Namespace(mergeDefaults({
+        metadata: {
+            name: namespaceName,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "namespace" },
+        },
+    }, defs?.namespace));
+    const result = { namespace };
+    for (const host of converge) {
+        const dial = host.dial ?? "observe";
+        const verbClass = deriveHostVerbClass(host.name, dial, host.dispatchTargets ?? []);
+        const resourceRules = host.resources ?? defaultResources;
+        const verbs = rbacVerbsFor(verbClass);
+        const saName = `${host.name}-sa`;
+        const roleName = `${host.name}-role`;
+        const bindingName = `${host.name}-binding`;
+        const hostLabels = {
+            ...commonLabels,
+            "app.kubernetes.io/instance": host.name,
+        };
+        const serviceAccount = new ServiceAccount(mergeDefaults({
+            metadata: {
+                name: saName,
+                namespace: namespaceName,
+                labels: hostLabels,
+            },
+        }, defs?.serviceAccount));
+        result[`serviceAccount_${host.name}`] = serviceAccount;
+        const role = new Role(mergeDefaults({
+            metadata: {
+                name: roleName,
+                namespace: namespaceName,
+                labels: { ...hostLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            rules: resourceRules.map((r) => ({ apiGroups: r.apiGroups, resources: r.resources, verbs })),
+        }, defs?.role));
+        result[`role_${host.name}`] = role;
+        const roleBinding = new RoleBinding(mergeDefaults({
+            metadata: {
+                name: bindingName,
+                namespace: namespaceName,
+                labels: { ...hostLabels, "app.kubernetes.io/component": "rbac" },
+            },
+            roleRef: {
+                apiGroup: "rbac.authorization.k8s.io",
+                kind: "Role",
+                name: roleName,
+            },
+            subjects: [
+                { kind: "ServiceAccount", name: saName, namespace: namespaceName },
+            ],
+        }, defs?.roleBinding));
+        result[`roleBinding_${host.name}`] = roleBinding;
+        const command = host.command ?? ["chant", "run", host.name];
+        const cronJob = new CronJob(mergeDefaults({
+            metadata: {
+                name: host.name,
+                namespace: namespaceName,
+                labels: { ...hostLabels, "app.kubernetes.io/component": "converge-tick" },
+            },
+            spec: {
+                schedule: host.schedule,
+                concurrencyPolicy: "Forbid",
+                successfulJobsHistoryLimit,
+                failedJobsHistoryLimit,
+                jobTemplate: {
+                    spec: {
+                        template: {
+                            metadata: { labels: { ...hostLabels, "app.kubernetes.io/component": "converge-tick" } },
+                            spec: {
+                                serviceAccountName: saName,
+                                restartPolicy: "OnFailure",
+                                containers: [
+                                    {
+                                        name: host.name,
+                                        image,
+                                        command,
+                                        env: [
+                                            { name: "CHANT_CONVERGE_ENV", value: host.env },
+                                            { name: "CHANT_CONVERGE_DIAL", value: dial },
+                                        ],
+                                    },
+                                ],
+                            },
+                        },
+                    },
+                },
+            },
+        }, defs?.cronJob));
+        result[`cronJob_${host.name}`] = cronJob;
+    }
+    return result;
+}, "OperatorStack");

package/dist/composites/otel-collector-agent.js

@@ -0,0 +1,142 @@
+/**
+ * The Kubernetes resources an OpenTelemetry Collector agent needs, shared by
+ * `OtelCollector` and `GkeOtelCollector`: a DaemonSet running the collector
+ * with its config mounted from a ConfigMap, and a ServiceAccount bound to a
+ * ClusterRole with the rules the caller works out from its config (see
+ * `agentClusterRules` in `otel-collector-rbac.ts`).
+ *
+ * The caller renders the collector config (with the otel lexicon's
+ * `collectorYaml`) and says which ports the container exposes. Everything
+ * platform-specific, such as a Workload Identity annotation or probes, comes
+ * in as an option, so each composite keeps its own output.
+ *
+ * `OtelCollectorGateway` runs the same container and ConfigMap
+ * (`collectorContainer`, `collectorConfigMap`) in a Deployment.
+ */
+import { mergeDefaults } from "@intentius/chant";
+import { DaemonSet, ServiceAccount, ClusterRole, ClusterRoleBinding, ConfigMap } from "../generated/index.js";
+import { nodeVolumeMounts, nodeVolumes } from "./otel-collector-node.js";
+export function collectorAgentResources(opts) {
+    const { name, namespace, commonLabels, extraLabels, defaults: defs } = opts;
+    const saName = `${name}-sa`;
+    const clusterRoleName = `${name}-role`;
+    const bindingName = `${name}-binding`;
+    const configMapName = `${name}-config`;
+    const access = opts.nodeAccess;
+    const asRoot = access?.readsLogs === true && opts.logAccess === "root";
+    const baseContainer = collectorContainer({
+        ...opts,
+        env: access?.env,
+        extraVolumeMounts: access ? nodeVolumeMounts(access.mounts) : undefined,
+    });
+    const container = asRoot ? runAsRoot(baseContainer) : baseContainer;
+    const podSecurity = access?.readsLogs && !asRoot ? { securityContext: { supplementalGroups: [0] } } : {};
+    const daemonSet = new DaemonSet(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+            ...(opts.workloadAnnotations ? { annotations: opts.workloadAnnotations } : {}),
+        },
+        spec: {
+            selector: { matchLabels: { "app.kubernetes.io/name": name } },
+            template: {
+                metadata: { labels: { "app.kubernetes.io/name": name, ...extraLabels } },
+                spec: {
+                    serviceAccountName: saName,
+                    containers: [container],
+                    volumes: [
+                        { name: "config", configMap: { name: configMapName } },
+                        ...(access ? nodeVolumes(access.mounts) : []),
+                    ],
+                    tolerations: [{ operator: "Exists" }],
+                    ...podSecurity,
+                },
+            },
+        },
+    }, defs?.daemonSet));
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+            ...(opts.serviceAccountAnnotations ? { annotations: opts.serviceAccountAnnotations } : {}),
+        },
+    }, defs?.serviceAccount));
+    const clusterRole = new ClusterRole(mergeDefaults({
+        metadata: {
+            name: clusterRoleName,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        rules: opts.clusterRules,
+    }, defs?.clusterRole));
+    const clusterRoleBinding = new ClusterRoleBinding(mergeDefaults({
+        metadata: {
+            name: bindingName,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+        roleRef: {
+            apiGroup: "rbac.authorization.k8s.io",
+            kind: "ClusterRole",
+            name: clusterRoleName,
+        },
+        subjects: [
+            {
+                kind: "ServiceAccount",
+                name: saName,
+                namespace,
+            },
+        ],
+    }, defs?.clusterRoleBinding));
+    const configMap = collectorConfigMap(opts, configMapName, opts.configMapAnnotations);
+    return { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap };
+}
+/**
+ * The collector container: the image, the config file argument, the ports,
+ * requests and limits, the config volume mount and a non-root security
+ * context, with `containerExtra` laid over the top. The agent DaemonSet and
+ * the gateway Deployment run the same container.
+ */
+export function collectorContainer(opts) {
+    return {
+        name: opts.name,
+        image: opts.image,
+        args: [`--config=${opts.configDir}/config.yaml`],
+        ...(opts.env?.length ? { env: opts.env } : {}),
+        ports: opts.ports,
+        resources: {
+            requests: { cpu: opts.cpuRequest, memory: opts.memoryRequest },
+            limits: { cpu: opts.cpuLimit, memory: opts.memoryLimit },
+        },
+        volumeMounts: [
+            { name: "config", mountPath: opts.configDir, readOnly: true },
+            ...(opts.extraVolumeMounts ?? []),
+        ],
+        securityContext: {
+            runAsNonRoot: true,
+            runAsUser: 10001,
+            readOnlyRootFilesystem: true,
+            allowPrivilegeEscalation: false,
+        },
+        ...opts.containerExtra,
+    };
+}
+/** The container run as user 0, for `logAccess: "root"`; the rest of its security context is kept. */
+function runAsRoot(container) {
+    const sc = (container.securityContext ?? {});
+    return { ...container, securityContext: { ...sc, runAsNonRoot: false, runAsUser: 0 } };
+}
+/** The ConfigMap holding the rendered collector config under `config.yaml`. */
+export function collectorConfigMap(opts, configMapName, annotations) {
+    return new ConfigMap(mergeDefaults({
+        metadata: {
+            name: configMapName,
+            namespace: opts.namespace,
+            labels: { ...opts.commonLabels, "app.kubernetes.io/component": "config" },
+            ...(annotations ? { annotations } : {}),
+        },
+        data: {
+            "config.yaml": opts.configYaml,
+        },
+    }, opts.defaults?.configMap));
+}

package/dist/composites/otel-collector-gateway.js

@@ -0,0 +1,216 @@
+/**
+ * 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 { otlpCollector, LoadBalancingExporter, OtlpExporter, OtlpHttpExporter, COLLECTOR_IMAGE, } from "@intentius/chant-lexicon-otel";
+import { Deployment, Service, ServiceAccount, ClusterRole, ClusterRoleBinding, PodDisruptionBudget, } from "../generated/index.js";
+import { collectorConfigMap, collectorContainer } from "./otel-collector-agent.js";
+import { namespacedRoles } from "./otel-collector-rbac.js";
+import { collectorRuntime, leaderElectorLeaseNamespaces, markGatewayExporter, OTEL_COLLECTOR_ANNOTATIONS, } from "./otel-collector-shape.js";
+/**
+ * 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, a ClusterRole
+ * and binding when `clusterRules` is set, and a Role and binding for Leases
+ * when the config enables a `k8s_leader_elector` extension.
+ *
+ * @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) => {
+    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 = {
+        "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: p.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)),
+        }
+        : {};
+    // A k8s_leader_elector extension takes a Lease in its lease_namespace, so
+    // the gateway's ServiceAccount gets the access the extension's README
+    // suggests (collector-contrib v0.130.0, extension/k8sleaderelector), with
+    // one Role and RoleBinding in each namespace the electors use.
+    const leaseRbac = namespacedRoles({
+        key: "lease",
+        name: `${name}-leases`,
+        namespaces: leaderElectorLeaseNamespaces(runtime.built),
+        rules: [
+            {
+                apiGroups: ["coordination.k8s.io"],
+                resources: ["leases"],
+                verbs: ["get", "list", "watch", "create", "update", "patch", "delete"],
+            },
+        ],
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        serviceAccount: { name: saName, namespace },
+        roleDefaults: defs?.leaseRole,
+        roleBindingDefaults: defs?.leaseRoleBinding,
+    });
+    return { deployment, service, headlessService, serviceAccount, configMap, ...pdb, ...rbac, ...leaseRbac };
+}, "OtelCollectorGateway");
+function serviceMeta(service) {
+    const p = service.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
+ * `protocol: "http"`, an `otlphttp` exporter at
+ * `http://<service>.<namespace>.svc:<port>` (`https://` when `tls` is not
+ * `insecure`), sending to the gateway's OTLP HTTP 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, options = {}) {
+    const { name = "gateway", protocol = "grpc", loadBalance = false, resolver = "k8s", routingKey = "traceID", tls = { insecure: true } } = options;
+    const portName = options.port ?? (protocol === "http" ? "otlp-http" : "otlp-grpc");
+    if (protocol === "http" && loadBalance) {
+        throw new Error(`gatewayExporter: the loadbalancing exporter sends OTLP over gRPC only; ` +
+            `use protocol "grpc" with loadBalance, or drop loadBalance to send OTLP over HTTP to the gateway's Service`);
+    }
+    const deploymentName = gateway.deployment.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 ${protocol === "http" ? "HTTP" : "gRPC"} receiver or pass the port name`);
+    }
+    const routing = 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] } },
+        })
+        : protocol === "http"
+            ? otlpHttpExporter(name, `${target.name}.${target.namespace}.svc:${port}`, tls)
+            : new OtlpExporter({ name, endpoint: `${target.name}.${target.namespace}.svc:${port}`, tls });
+    markGatewayExporter(exporter, { name: deploymentName, namespace: target.namespace, routing });
+    return exporter;
+}
+/**
+ * An `otlphttp` exporter to `host:port`. Its endpoint is a URL, so TLS is the
+ * scheme: `insecure` gives `http://`, anything else `https://` with the
+ * remaining TLS settings (a CA, a client certificate) kept.
+ */
+function otlpHttpExporter(name, hostPort, tls) {
+    const { insecure, ...rest } = tls;
+    const scheme = insecure ? "http" : "https";
+    return new OtlpHttpExporter({
+        name,
+        endpoint: `${scheme}://${hostPort}`,
+        ...(Object.keys(rest).length ? { tls: rest } : {}),
+    });
+}