@intentius/chant-lexicon-k8s 0.124.31 → 0.124.32

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

@@ -0,0 +1,176 @@
+/**
+ * What a collector pod needs from its node, worked out from the collector
+ * config it runs, the way `agentClusterRules` works out its RBAC (chant
+ * #3103). `OtelCollector` and `GkeOtelCollector` add the result to their
+ * DaemonSet, and WK8605 reports a workload that runs such a config without it.
+ *
+ * Only components a pipeline runs count, since the collector starts no
+ * other. A config that reads nothing from the node gets nothing, so its
+ * DaemonSet is unchanged. Each requirement cites the component's README at
+ * collector-contrib v0.130.0, the version the otel lexicon pins:
+ *
+ * - The node's name, from the downward API (`spec.nodeName`), in each
+ *   variable a `k8sattributes` processor names in `filter.node_from_env_var`
+ *   (processor/k8sattributesprocessor README, "Deployment scenarios": "Use
+ *   the downward API to inject the node name as an environment variable"),
+ *   and in each `${env:VAR}` a `kubeletstats` receiver's `node` uses, or its
+ *   `endpoint` uses when the variable's name ends in `NODE_NAME`
+ *   (receiver/kubeletstatsreceiver README, "Service Account Authentication
+ *   Example"). An `endpoint` variable ending in `NODE_IP` or `HOST_IP` gets
+ *   `status.hostIP` instead. Any other variable is the caller's to set.
+ * - The host root, read-only at a `hostmetrics` receiver's `root_path`
+ *   (receiver/hostmetricsreceiver README, "Collecting host metrics from
+ *   inside a container (Linux only)": bind mount the host filesystem, then
+ *   configure `root_path`). Mounted with `HostToContainer` propagation so
+ *   filesystems the node mounts later show up, as the upstream Helm chart's
+ *   hostMetrics preset does.
+ * - The directories a `filelog` receiver's `include` patterns read, read-only
+ *   at the same path (receiver/filelogreceiver README, "Configuration":
+ *   `include` is a list of file glob patterns the receiver reads). The mount
+ *   is the fixed directory part of each pattern, so `/var/log/pods/*\/*\/*.log`
+ *   mounts `/var/log/pods`. `/var/log/containers` holds symlinks into
+ *   `/var/log/pods`, so reading it mounts both. A pattern with no fixed
+ *   directory below `/`, or one that would cover the config directory, is
+ *   left to the caller.
+ *
+ * `readsLogs` is set when a `filelog` receiver reads a host directory: the
+ * kubelet's container logs there are owned by root, which the composites
+ * deal with (see `logAccess` on `OtelCollector`).
+ */
+import { canonicalTypeOf } from "@intentius/chant-lexicon-otel/model";
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Component ids of one kind that some pipeline runs. */
+function runningIds(config, kind) {
+    const ids = new Set();
+    const pipelines = isRecord(config.service) && isRecord(config.service.pipelines) ? config.service.pipelines : {};
+    for (const p of Object.values(pipelines)) {
+        const list = isRecord(p) ? p[kind] : undefined;
+        if (Array.isArray(list))
+            for (const id of list)
+                if (typeof id === "string")
+                    ids.add(id);
+    }
+    return ids;
+}
+/** [id, settings] of each running component of `type`, under its old or new name (`kubelet_stats`). */
+function running(config, kind, type) {
+    const ids = runningIds(config, kind);
+    const section = isRecord(config[kind]) ? config[kind] : {};
+    const componentKind = kind === "receivers" ? "receiver" : "processor";
+    return Object.entries(section)
+        .filter(([id]) => ids.has(id) && canonicalTypeOf(componentKind, id) === type)
+        .map(([id, cfg]) => [id, isRecord(cfg) ? cfg : {}]);
+}
+/** The variables a string reads as `${env:NAME}`. */
+function envRefs(value) {
+    if (typeof value !== "string")
+        return [];
+    return [...value.matchAll(/\$\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g)].map((m) => m[1]);
+}
+/** The directory part of a glob before its first wildcard: `/var/log/pods/*\/x.log` is `/var/log/pods`. */
+export function fixedDirectory(pattern) {
+    if (!pattern.startsWith("/"))
+        return undefined;
+    const parts = pattern.split("/");
+    const fixed = [];
+    for (const part of parts) {
+        if (/[*?[{]/.test(part))
+            break;
+        fixed.push(part);
+    }
+    // No wildcard at all: a file, so its directory.
+    if (fixed.length === parts.length)
+        fixed.pop();
+    const dir = fixed.join("/").replace(/\/+$/, "");
+    return dir === "" ? undefined : dir;
+}
+function within(path, dir) {
+    return path === dir || path.startsWith(`${dir}/`);
+}
+function volumeName(prefix, path) {
+    const slug = path.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+    return `${prefix}-${slug}`.slice(0, 63).replace(/-+$/, "");
+}
+/**
+ * What a collector config needs from the node. `configDir` is where the
+ * collector's own config is mounted; a log directory covering it is skipped.
+ */
+export function collectorNodeAccess(config, configDir = "/etc/otel") {
+    const env = new Map();
+    const setEnv = (name, fieldPath) => {
+        if (!env.has(name))
+            env.set(name, fieldPath);
+    };
+    for (const [, p] of running(config, "processors", "k8sattributes")) {
+        const name = isRecord(p.filter) ? p.filter.node_from_env_var : undefined;
+        if (typeof name === "string" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            setEnv(name, "spec.nodeName");
+    }
+    for (const [, r] of running(config, "receivers", "kubeletstats")) {
+        for (const name of envRefs(r.node))
+            setEnv(name, "spec.nodeName");
+        for (const name of envRefs(r.endpoint)) {
+            if (/(NODE|HOST)_IP$/.test(name))
+                setEnv(name, "status.hostIP");
+            else if (/NODE_NAME$/.test(name))
+                setEnv(name, "spec.nodeName");
+        }
+    }
+    const mounts = [];
+    const rootPaths = new Set();
+    for (const [id, r] of running(config, "receivers", "hostmetrics")) {
+        const root = typeof r.root_path === "string" ? r.root_path.replace(/\/+$/, "") : "";
+        if (!root.startsWith("/") || rootPaths.has(root))
+            continue;
+        rootPaths.add(root);
+        mounts.push({
+            name: rootPaths.size === 1 ? "hostfs" : volumeName("hostfs", root),
+            hostPath: "/",
+            mountPath: root,
+            component: id,
+            partial: true,
+            mountPropagation: "HostToContainer",
+        });
+    }
+    const logDirs = [];
+    for (const [id, r] of running(config, "receivers", "filelog")) {
+        const include = Array.isArray(r.include) ? r.include : [];
+        for (const pattern of include) {
+            if (typeof pattern !== "string")
+                continue;
+            const dir = fixedDirectory(pattern);
+            if (!dir || within(configDir, dir))
+                continue;
+            logDirs.push({ dir, component: id });
+            if (within(dir, "/var/log/containers"))
+                logDirs.push({ dir: "/var/log/pods", component: id });
+        }
+    }
+    // One mount per directory, the outermost of nested ones.
+    const kept = logDirs.filter(({ dir }, i) => !logDirs.some((o, j) => (o.dir !== dir && within(dir, o.dir)) || (o.dir === dir && j < i)));
+    for (const { dir, component } of kept) {
+        if ([...rootPaths].some((root) => within(dir, root)))
+            continue;
+        mounts.push({ name: volumeName("host", dir), hostPath: dir, mountPath: dir, component });
+    }
+    return {
+        env: [...env].map(([name, fieldPath]) => ({ name, valueFrom: { fieldRef: { fieldPath } } })),
+        mounts,
+        readsLogs: kept.length > 0,
+    };
+}
+/** The pod volumes for a set of mounts. */
+export function nodeVolumes(mounts) {
+    return mounts.map((m) => ({ name: m.name, hostPath: { path: m.hostPath } }));
+}
+/** The container volume mounts for a set of mounts, all read-only. */
+export function nodeVolumeMounts(mounts) {
+    return mounts.map((m) => ({
+        name: m.name,
+        mountPath: m.mountPath,
+        readOnly: true,
+        ...(m.mountPropagation ? { mountPropagation: m.mountPropagation } : {}),
+    }));
+}

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

@@ -0,0 +1,115 @@
+/**
+ * The RBAC the collector composites grant, worked out from the collector
+ * config they deploy.
+ *
+ * `agentClusterRules` is the ClusterRole `OtelCollector` and
+ * `GkeOtelCollector` share: what the `k8sattributes` processor needs, plus
+ * what the config's Kubernetes receivers need. Each rule cites the
+ * component's RBAC requirements at collector-contrib v0.130.0, the version the
+ * otel lexicon pins.
+ *
+ * `namespacedRoles` builds one Role and RoleBinding per namespace, for access
+ * a collector needs in namespaces other than its own: Endpoints for a
+ * `loadbalancing` exporter's `k8s` resolver, Leases for a
+ * `k8s_leader_elector` extension.
+ */
+import { mergeDefaults } from "@intentius/chant";
+import { canonicalTypeOf } from "@intentius/chant-lexicon-otel/model";
+import { Role, RoleBinding } from "../generated/index.js";
+const READ = ["get", "list", "watch"];
+/** The configs of the components of `kind` whose type is `type`, under its old or new name (`k8s_attributes`). */
+function componentsOfType(kind, section, type) {
+    return Object.entries(section ?? {})
+        .filter(([id]) => canonicalTypeOf(kind, id) === type)
+        .map(([, cfg]) => (cfg && typeof cfg === "object" ? cfg : {}));
+}
+/**
+ * The agent ClusterRole's rules for a collector config.
+ *
+ * Always, for `k8sattributes` (processor/k8sattributesprocessor README,
+ * "Cluster-scoped RBAC"): `get`, `list` and `watch` on pods, namespaces and
+ * nodes, and on `apps` replicasets for `k8s.deployment.name`, which is
+ * extracted by default. The processor lists ReplicaSets through `apps/v1`
+ * only, so the README's `extensions` group is left out. When a
+ * `k8sattributes` processor extracts labels or annotations `from: deployment`,
+ * `apps` deployments are added.
+ *
+ * For each `kubeletstats` receiver (receiver/kubeletstatsreceiver README,
+ * "Role-based access control"): `get` on `nodes/stats`; `get` on
+ * `nodes/proxy` when it sets `extra_metadata_labels` or enables a
+ * `*_request_utilization` or `*_limit_utilization` metric; and, when it sets
+ * `k8s_api_config`, `get` on persistentvolumeclaims and persistentvolumes,
+ * which it reads for volume metadata (scraper.go).
+ *
+ * Other components that read the Kubernetes API, such as `k8s_cluster`
+ * (which belongs on a gateway, see WK8603), add their rules through
+ * `defaults.clusterRole.rules`, which are appended.
+ */
+export function agentClusterRules(config) {
+    const apps = ["replicasets"];
+    const k8sattributes = componentsOfType("processor", config.processors, "k8sattributes");
+    const fromDeployment = k8sattributes.some((p) => {
+        const extract = p.extract;
+        return [...(extract?.labels ?? []), ...(extract?.annotations ?? [])].some((f) => f?.from === "deployment");
+    });
+    if (fromDeployment)
+        apps.push("deployments");
+    const rules = [
+        { apiGroups: [""], resources: ["pods", "namespaces", "nodes"], verbs: READ },
+        { apiGroups: ["apps"], resources: apps, verbs: READ },
+    ];
+    const kubeletstats = componentsOfType("receiver", config.receivers, "kubeletstats");
+    if (kubeletstats.length) {
+        const nodeSubresources = ["nodes/stats"];
+        const needsProxy = kubeletstats.some((r) => {
+            const labels = r.extra_metadata_labels;
+            if (Array.isArray(labels) && labels.length)
+                return true;
+            const metrics = (r.metrics ?? {});
+            return Object.entries(metrics).some(([metric, toggle]) => /_(request|limit)_utilization$/.test(metric) && toggle?.enabled === true);
+        });
+        if (needsProxy)
+            nodeSubresources.push("nodes/proxy");
+        rules.push({ apiGroups: [""], resources: nodeSubresources, verbs: ["get"] });
+        if (kubeletstats.some((r) => r.k8s_api_config)) {
+            rules.push({ apiGroups: [""], resources: ["persistentvolumeclaims", "persistentvolumes"], verbs: ["get"] });
+        }
+    }
+    return rules;
+}
+function pascal(namespace) {
+    return namespace
+        .split(/[^a-zA-Z0-9]+/)
+        .filter(Boolean)
+        .map((part) => part[0].toUpperCase() + part.slice(1))
+        .join("");
+}
+/**
+ * One Role and RoleBinding per namespace, as composite members. The first
+ * namespace's are `<key>Role` and `<key>RoleBinding`, so a single-namespace
+ * config keeps the member names it had before; each further namespace's are
+ * `<key>RoleIn<Namespace>` and `<key>RoleBindingIn<Namespace>`, with the
+ * namespace in PascalCase (`team-a` gives `endpointsRoleInTeamA`).
+ */
+export function namespacedRoles(opts) {
+    const out = {};
+    const seen = new Map();
+    opts.namespaces.forEach((namespace, i) => {
+        const suffix = i === 0 ? "" : `In${pascal(namespace)}`;
+        const clash = seen.get(suffix);
+        if (clash !== undefined) {
+            throw new Error(`${opts.name}: namespaces ${clash} and ${namespace} give the same member name ${opts.key}Role${suffix}`);
+        }
+        seen.set(suffix, namespace);
+        out[`${opts.key}Role${suffix}`] = new Role(mergeDefaults({
+            metadata: { name: opts.name, namespace, labels: opts.labels },
+            rules: opts.rules,
+        }, opts.roleDefaults));
+        out[`${opts.key}RoleBinding${suffix}`] = new RoleBinding(mergeDefaults({
+            metadata: { name: opts.name, namespace, labels: opts.labels },
+            roleRef: { apiGroup: "rbac.authorization.k8s.io", kind: "Role", name: opts.name },
+            subjects: [{ kind: "ServiceAccount", name: opts.serviceAccount.name, namespace: opts.serviceAccount.namespace }],
+        }, opts.roleBindingDefaults));
+    });
+    return out;
+}

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

@@ -0,0 +1,128 @@
+/**
+ * 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 { buildCollectorConfig, canonicalTypeOf, collectorEndpoints, collectorYaml, COLLECTOR_CONFIG_PATH, } 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` |
+ * | `header` | `OtelOperatorCollector`'s `OpenTelemetryCollector` | the config's `# chant:` header lines (custom-component pins, semconv use), one per line, which an object-valued `spec.config` has no comments to hold |
+ * | `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",
+    header: "otel.chant.dev/header",
+};
+const gatewayTargets = new WeakMap();
+/** Record which gateway an exporter entity was built for. */
+export function markGatewayExporter(exporter, target) {
+    gatewayTargets.set(exporter, target);
+}
+/** The gateways a built config's exporters were built for, in declaration order. */
+export function gatewayTargetsOf(built) {
+    const out = [];
+    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) {
+    return targets.map((t) => `${t.namespace}/${t.name}=${t.routing}`).join(",");
+}
+export function collectorRuntime(entities) {
+    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 && !p.protocol)?.name ?? "health") : undefined;
+    const probe = healthCheck ? { httpGet: { path: healthCheck.path, port: healthPortName } } : undefined;
+    const containerPorts = [
+        ...ports.map((p) => ({ containerPort: p.port, name: p.name, ...(p.protocol ? { protocol: p.protocol } : {}) })),
+        ...(healthCheck && !ports.some((p) => p.port === healthCheck.port && !p.protocol)
+            ? [{ containerPort: healthCheck.port, name: "health" }]
+            : []),
+    ];
+    return {
+        built,
+        configYaml: collectorYaml(entities),
+        configDir,
+        containerPorts,
+        servicePorts: ports.map((p) => ({ name: p.name, port: p.port, ...(p.protocol ? { protocol: p.protocol } : {}) })),
+        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, ownNamespace) {
+    const out = [];
+    for (const [id, cfg] of Object.entries(built.config.exporters ?? {})) {
+        if (canonicalTypeOf("exporter", id) !== "loadbalancing")
+            continue;
+        const service = cfg?.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;
+}
+/**
+ * The namespaces of the Leases a config's `k8s_leader_elector` extensions
+ * take, for those `service.extensions` enables (the collector starts no
+ * other). An elector without `lease_namespace` fails the otel lexicon's
+ * OTEL107 and is skipped here.
+ */
+export function leaderElectorLeaseNamespaces(built) {
+    const out = [];
+    const enabled = built.config.service?.extensions ?? [];
+    for (const [id, cfg] of Object.entries(built.config.extensions ?? {})) {
+        if (id !== "k8s_leader_elector" && !id.startsWith("k8s_leader_elector/"))
+            continue;
+        if (!enabled.includes(id))
+            continue;
+        const ns = cfg?.lease_namespace;
+        if (typeof ns !== "string" || ns === "")
+            continue;
+        if (!out.includes(ns))
+            out.push(ns);
+    }
+    return out;
+}

package/dist/composites/otel-collector.js

@@ -0,0 +1,115 @@
+/**
+ * OtelCollector composite: an OpenTelemetry Collector agent on any
+ * Kubernetes cluster.
+ *
+ * A DaemonSet runs the collector on every node, with its config mounted from
+ * a ConfigMap, and a Service with `internalTrafficPolicy: Local` sends each
+ * pod's OTLP traffic to the collector on its own node. The config is declared
+ * with the otel lexicon (`@intentius/chant-lexicon-otel`) and rendered with
+ * `collectorYaml`. The container ports, the Service ports and the probes are
+ * 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 { otlpCollector, COLLECTOR_IMAGE, } from "@intentius/chant-lexicon-otel";
+import { Service } from "../generated/index.js";
+import { collectorAgentResources } from "./otel-collector-agent.js";
+import { collectorNodeAccess } from "./otel-collector-node.js";
+import { agentClusterRules, namespacedRoles } from "./otel-collector-rbac.js";
+import { collectorRuntime, gatewaysAnnotation, gatewayTargetsOf, k8sResolverNamespaces, OTEL_COLLECTOR_ANNOTATIONS, } from "./otel-collector-shape.js";
+/**
+ * Create an OtelCollector composite. Returns a DaemonSet, Service,
+ * ServiceAccount, ClusterRole, ClusterRoleBinding and ConfigMap.
+ *
+ * @example
+ * ```ts
+ * import { OtelCollector } from "@intentius/chant-lexicon-k8s";
+ * import { OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * export const collector = OtelCollector({
+ *   exporters: [new OtlpExporter({ endpoint: "tempo.observability.svc:4317", tls: { insecure: true } })],
+ * });
+ * ```
+ */
+export const OtelCollector = Composite((props) => {
+    const { name = "otel-collector", namespace = "observability", image = COLLECTOR_IMAGE, labels: extraLabels = {}, logAccess = "group", cpuRequest = "100m", memoryRequest = "256Mi", cpuLimit = "500m", memoryLimit = "512Mi", defaults: defs, } = props;
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const entities = props.config ? [...props.config] : otlpCollector({ exporters: props.exporters, signals: props.signals });
+    const runtime = collectorRuntime(entities);
+    const configMapName = `${name}-config`;
+    // 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 = gateways.length ? { [OTEL_COLLECTOR_ANNOTATIONS.gateways]: gatewaysAnnotation(gateways) } : {};
+    const resources = collectorAgentResources({
+        name,
+        namespace,
+        image,
+        commonLabels,
+        extraLabels,
+        configYaml: runtime.configYaml,
+        configDir: runtime.configDir,
+        ports: runtime.containerPorts,
+        clusterRules: agentClusterRules(runtime.built.config),
+        // The node name, host mounts and log access the config's node-reading
+        // components need (#3103); nothing for a config that reads no node.
+        nodeAccess: collectorNodeAccess(runtime.built.config, runtime.configDir),
+        logAccess,
+        cpuRequest,
+        memoryRequest,
+        cpuLimit,
+        memoryLimit,
+        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,
+    });
+    const service = new Service(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "agent" },
+        },
+        spec: {
+            selector: { "app.kubernetes.io/name": name },
+            internalTrafficPolicy: "Local",
+            ports: runtime.servicePorts.map((p) => ({ name: p.name, port: p.port, targetPort: p.name, protocol: p.protocol ?? "TCP" })),
+        },
+    }, defs?.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), with one Role
+    // and RoleBinding in each namespace the resolvers point at.
+    const saName = resources.serviceAccount.props.metadata.name;
+    const endpointsRbac = namespacedRoles({
+        key: "endpoints",
+        name: `${name}-endpoints`,
+        namespaces: k8sResolverNamespaces(runtime.built, namespace),
+        rules: [
+            { apiGroups: [""], resources: ["endpoints"], verbs: ["get", "list", "watch"] },
+            { apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: ["get", "list", "watch"] },
+        ],
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        serviceAccount: { name: saName, namespace },
+        roleDefaults: defs?.endpointsRole,
+        roleBindingDefaults: defs?.endpointsRoleBinding,
+    });
+    return { ...resources, service, ...endpointsRbac };
+}, "OtelCollector");

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

@@ -0,0 +1,123 @@
+/**
+ * OtelOperatorCollector composite: an OpenTelemetry Collector run by the
+ * OpenTelemetry Operator, as an `OpenTelemetryCollector` custom resource
+ * (opentelemetry.io/v1beta1).
+ *
+ * `OtelCollector` builds the DaemonSet, ConfigMap and Service itself. Here the
+ * operator builds them from one custom resource, and the otel lexicon's
+ * config goes straight into `spec.config`, which v1beta1 declares as an
+ * object (`exporters`, `receivers` and `service` required). The ports, the
+ * node access (downward API variables, host mounts, log group) and the RBAC
+ * come from the same readers `OtelCollector` uses, so the two follow a config
+ * the same way.
+ *
+ * An object has no comment lines, so the `# chant:` header that carries
+ * custom-component pins and semconv use (see `buildCollectorConfig`) is kept
+ * in the `otel.chant.dev/header` annotation, one line per entry. `chant
+ * import` puts it back on top of the config when it reads the CR.
+ *
+ * The operator names the workload `<name>-collector` and, with
+ * `spec.serviceAccount` set as it is here, runs it as the ServiceAccount this
+ * composite makes. The ClusterRole is bound to that ServiceAccount.
+ */
+import { Composite, mergeDefaults } from "@intentius/chant";
+import { otlpCollector, COLLECTOR_IMAGE, } from "@intentius/chant-lexicon-otel";
+import { ServiceAccount, ClusterRole, ClusterRoleBinding, OpenTelemetryCollector } from "../generated/index.js";
+import { collectorNodeAccess, nodeVolumeMounts, nodeVolumes } from "./otel-collector-node.js";
+import { agentClusterRules, namespacedRoles } from "./otel-collector-rbac.js";
+import { collectorRuntime, gatewaysAnnotation, gatewayTargetsOf, k8sResolverNamespaces, OTEL_COLLECTOR_ANNOTATIONS, } from "./otel-collector-shape.js";
+/**
+ * Create an OtelOperatorCollector composite. Returns an OpenTelemetryCollector
+ * custom resource, a ServiceAccount, a ClusterRole and a ClusterRoleBinding.
+ *
+ * @example
+ * ```ts
+ * import { OtelOperatorCollector } from "@intentius/chant-lexicon-k8s";
+ * import { OtlpExporter } from "@intentius/chant-lexicon-otel";
+ *
+ * export const collector = OtelOperatorCollector({
+ *   mode: "deployment",
+ *   replicas: 2,
+ *   exporters: [new OtlpExporter({ endpoint: "tempo.observability.svc:4317", tls: { insecure: true } })],
+ * });
+ * ```
+ */
+export const OtelOperatorCollector = Composite((props) => {
+    const { name = "otel-collector", namespace = "observability", mode = "daemonset", image = COLLECTOR_IMAGE, labels: extraLabels = {}, logAccess = "group", cpuRequest = "100m", memoryRequest = "256Mi", cpuLimit = "500m", memoryLimit = "512Mi", defaults: defs, } = props;
+    if (mode === "daemonset" && props.replicas !== undefined) {
+        throw new Error(`${name}: a daemonset runs one collector per node, so replicas does not apply`);
+    }
+    const commonLabels = {
+        "app.kubernetes.io/name": name,
+        "app.kubernetes.io/managed-by": "chant",
+        ...extraLabels,
+    };
+    const entities = props.config ? [...props.config] : otlpCollector({ exporters: props.exporters, signals: props.signals });
+    const runtime = collectorRuntime(entities);
+    const gateways = gatewayTargetsOf(runtime.built);
+    const saName = `${name}-sa`;
+    const access = collectorNodeAccess(runtime.built.config, runtime.configDir);
+    const asRoot = access.readsLogs && logAccess === "root";
+    const container = runtime.containerExtra.securityContext;
+    const annotations = {
+        [OTEL_COLLECTOR_ANNOTATIONS.role]: mode === "daemonset" ? "agent" : "gateway",
+        ...(gateways.length ? { [OTEL_COLLECTOR_ANNOTATIONS.gateways]: gatewaysAnnotation(gateways) } : {}),
+        ...(runtime.built.header.length ? { [OTEL_COLLECTOR_ANNOTATIONS.header]: runtime.built.header.join("\n") } : {}),
+    };
+    const collector = new OpenTelemetryCollector(mergeDefaults({
+        metadata: {
+            name,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": mode === "daemonset" ? "agent" : "gateway" },
+            annotations,
+        },
+        spec: {
+            mode,
+            ...(props.replicas !== undefined ? { replicas: props.replicas } : {}),
+            image,
+            serviceAccount: saName,
+            config: runtime.built.config,
+            ports: runtime.servicePorts.map((p) => ({ name: p.name, port: p.port, protocol: p.protocol ?? "TCP" })),
+            resources: {
+                requests: { cpu: cpuRequest, memory: memoryRequest },
+                limits: { cpu: cpuLimit, memory: memoryLimit },
+            },
+            securityContext: asRoot ? { ...container, runAsNonRoot: false, runAsUser: 0 } : container,
+            ...(access.readsLogs && !asRoot ? { podSecurityContext: { supplementalGroups: [0] } } : {}),
+            ...(access.env.length ? { env: access.env } : {}),
+            ...(access.mounts.length ? { volumes: nodeVolumes(access.mounts), volumeMounts: nodeVolumeMounts(access.mounts) } : {}),
+            ...(mode === "daemonset" ? { tolerations: [{ operator: "Exists" }] } : {}),
+        },
+    }, defs?.collector));
+    const serviceAccount = new ServiceAccount(mergeDefaults({
+        metadata: {
+            name: saName,
+            namespace,
+            labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        },
+    }, defs?.serviceAccount));
+    const clusterRoleName = `${name}-role`;
+    const clusterRole = new ClusterRole(mergeDefaults({
+        metadata: { name: clusterRoleName, labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" } },
+        rules: agentClusterRules(runtime.built.config),
+    }, defs?.clusterRole));
+    const clusterRoleBinding = new ClusterRoleBinding(mergeDefaults({
+        metadata: { name: `${name}-binding`, 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 endpointsRbac = namespacedRoles({
+        key: "endpoints",
+        name: `${name}-endpoints`,
+        namespaces: k8sResolverNamespaces(runtime.built, namespace),
+        rules: [
+            { apiGroups: [""], resources: ["endpoints"], verbs: ["get", "list", "watch"] },
+            { apiGroups: ["discovery.k8s.io"], resources: ["endpointslices"], verbs: ["get", "list", "watch"] },
+        ],
+        labels: { ...commonLabels, "app.kubernetes.io/component": "rbac" },
+        serviceAccount: { name: saName, namespace },
+        roleDefaults: defs?.endpointsRole,
+        roleBindingDefaults: defs?.endpointsRoleBinding,
+    });
+    return { collector, serviceAccount, clusterRole, clusterRoleBinding, ...endpointsRbac };
+}, "OtelOperatorCollector");