@intentius/chant-lexicon-k8s 0.95.1 → 0.97.0

package/src/composites/catalog.ts

@@ -2153,6 +2153,7 @@ export const compositeCatalog: CompositeEntry[] = [
       "ClusterRoleBinding",
       "ConfigMap",
       "DaemonSet",
+      "Pipeline",
       "ServiceAccount"
     ],
     "params": [
@@ -2460,6 +2461,12 @@ export const compositeCatalog: CompositeEntry[] = [
         "required": false,
         "description": "Alert rules — if provided, creates a PrometheusRule."
       },
+      {
+        "name": "ruleGroups",
+        "type": "Array<RuleGroupEntity | RuleGroupProps>",
+        "required": false,
+        "description": "Rule groups from the prometheus lexicon — if provided, creates a PrometheusRule holding them, after the `alertRules` group when both are set."
+      },
       {
         "name": "replicas",
         "type": "number",
@@ -2894,6 +2901,8 @@ export const compositeCatalog: CompositeEntry[] = [
       "ClusterRoleBinding",
       "ConfigMap",
       "DaemonSet",
+      "Role",
+      "RoleBinding",
       "Service",
       "ServiceAccount"
     ],
@@ -2972,6 +2981,106 @@ export const compositeCatalog: CompositeEntry[] = [
       }
     ]
   },
+  {
+    "name": "OtelCollectorGateway",
+    "lexicon": "k8s",
+    "description": "Create an OtelCollectorGateway composite.",
+    "bundles": [
+      "ClusterRole",
+      "ClusterRoleBinding",
+      "ConfigMap",
+      "Deployment",
+      "PodDisruptionBudget",
+      "Service",
+      "ServiceAccount"
+    ],
+    "params": [
+      {
+        "name": "name",
+        "type": "string",
+        "required": false,
+        "description": "Gateway name (default: \"otel-gateway\")."
+      },
+      {
+        "name": "namespace",
+        "type": "string",
+        "required": false,
+        "description": "Namespace (default: \"observability\")."
+      },
+      {
+        "name": "replicas",
+        "type": "number",
+        "required": false,
+        "description": "Number of collector pods (default: 2)."
+      },
+      {
+        "name": "image",
+        "type": "string",
+        "required": false,
+        "description": "Collector image (default: the contrib image at the otel lexicon's pinned collector version)."
+      },
+      {
+        "name": "config",
+        "type": "Iterable<Declarable>",
+        "required": false,
+        "description": "The collector config, as otel lexicon entities (components and pipelines)."
+      },
+      {
+        "name": "exporters",
+        "type": "OTelComponent<\"exporter\", string, any>[]",
+        "required": false,
+        "description": "Exporters for the default config (default: one `debug` exporter)."
+      },
+      {
+        "name": "signals",
+        "type": "Signal[]",
+        "required": false,
+        "description": "Signals the default config has pipelines for (default: traces, metrics and logs)."
+      },
+      {
+        "name": "clusterRules",
+        "type": "CollectorPolicyRule[]",
+        "required": false,
+        "description": "Cluster-wide read access the config needs, e.g. for a `k8s_cluster` receiver or a `k8sattributes` processor."
+      },
+      {
+        "name": "labels",
+        "type": "Record<string, string>",
+        "required": false,
+        "description": "Additional labels."
+      },
+      {
+        "name": "cpuRequest",
+        "type": "string",
+        "required": false,
+        "description": "CPU request (default: \"200m\")."
+      },
+      {
+        "name": "memoryRequest",
+        "type": "string",
+        "required": false,
+        "description": "Memory request (default: \"512Mi\")."
+      },
+      {
+        "name": "cpuLimit",
+        "type": "string",
+        "required": false,
+        "description": "CPU limit (default: \"1\")."
+      },
+      {
+        "name": "memoryLimit",
+        "type": "string",
+        "required": false,
+        "description": "Memory limit (default: \"1Gi\")."
+      },
+      {
+        "name": "defaults",
+        "type": "{ deployment?: Partial<Record<string, unknown>>; service?: Partial<Record<string, unknown>>; headlessService?: Partia...",
+        "required": false,
+        "description": "Per-member defaults for fine-grained overrides."
+      }
+    ]
+  },
   {
     "name": "RayCluster",
     "lexicon": "k8s",

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

@@ -0,0 +1,51 @@
+/**
+ * GkeOtelCollector's rendered manifests, held to a snapshot (#2898).
+ *
+ * `OtelCollector`, `OtelCollectorGateway` and `GkeOtelCollector` share the
+ * collector resources in `otel-collector-agent.ts`. The snapshot was recorded
+ * before the gateway work touched that file, so any change to the GKE output
+ * made through the shared code fails here.
+ */
+import { describe, expect, test } from "vitest";
+import { expandComposite } from "@intentius/chant";
+import { k8sSerializer } from "../serializer";
+import { GkeOtelCollector } from "./gke-otel-collector";
+
+function manifests(instance: ReturnType<typeof GkeOtelCollector>): string {
+  const out = k8sSerializer.serialize(expandComposite("collector", instance));
+  return typeof out === "string" ? out : out.primary;
+}
+
+describe("GkeOtelCollector output", () => {
+  test("with Workload Identity", () => {
+    expect(
+      manifests(
+        GkeOtelCollector({
+          clusterName: "test-cluster",
+          projectId: "test-project",
+          gcpServiceAccountEmail: "otel@test-project.iam.gserviceaccount.com",
+        }),
+      ),
+    ).toMatchSnapshot();
+  });
+
+  test("with every prop set", () => {
+    expect(
+      manifests(
+        GkeOtelCollector({
+          clusterName: "c1",
+          projectId: "p-123456",
+          name: "otel",
+          namespace: "telemetry",
+          image: "otel/opentelemetry-collector-contrib:0.100.0",
+          labels: { team: "obs" },
+          cpuRequest: "50m",
+          memoryRequest: "128Mi",
+          cpuLimit: "1",
+          memoryLimit: "1Gi",
+          defaults: { daemonSet: { spec: { updateStrategy: { type: "OnDelete" } } } },
+        }),
+      ),
+    ).toMatchSnapshot();
+  });
+});

package/src/composites/index.ts

@@ -67,6 +67,15 @@ export { GkeFluentBitAgent } from "./gke-fluent-bit-agent";
 export type { GkeFluentBitAgentProps, GkeFluentBitAgentResult } from "./gke-fluent-bit-agent";
 export { OtelCollector } from "./otel-collector";
 export type { OtelCollectorProps, OtelCollectorResult } from "./otel-collector";
+export { OtelCollectorGateway, gatewayExporter } from "./otel-collector-gateway";
+export type {
+  OtelCollectorGatewayProps,
+  OtelCollectorGatewayResult,
+  GatewayExporterOptions,
+  CollectorPolicyRule,
+} from "./otel-collector-gateway";
+export { OTEL_COLLECTOR_ANNOTATIONS } from "./otel-collector-shape";
+export type { CollectorRole, GatewayRouting } from "./otel-collector-shape";
 export { GkeOtelCollector } from "./gke-otel-collector";
 export type { GkeOtelCollectorProps, GkeOtelCollectorResult } from "./gke-otel-collector";
 export { GkeExternalDnsAgent } from "./gke-external-dns-agent";

package/src/composites/monitored-service.ts

@@ -4,9 +4,15 @@
  * Observability pattern. ServiceMonitor and PrometheusRule are CRDs
  * from the Prometheus Operator (monitoring.coreos.com/v1), returned
  * as raw objects that can be serialized alongside native K8s resources.
+ *
+ * Rules come in two forms. `ruleGroups` takes `RuleGroup`s from the
+ * prometheus lexicon (`@intentius/chant-lexicon-prometheus`), typed and
+ * checked there, and rendered here exactly as they would be in a rule file.
+ * `alertRules` is the older shorthand for one group of alerts and still works.
  */
 
 import { Composite, mergeDefaults } from "@intentius/chant";
+import { ruleGroupConfig, type RuleGroupEntity, type RuleGroupProps } from "@intentius/chant-lexicon-prometheus";
 import { Deployment, Service, ServiceMonitor, PrometheusRule } from "../generated";
 import type { ContainerSecurityContext } from "./security-context";
 
@@ -38,6 +44,11 @@ export interface MonitoredServiceProps {
   scrapeInterval?: string;
   /** Alert rules — if provided, creates a PrometheusRule. */
   alertRules?: AlertRule[];
+  /**
+   * Rule groups from the prometheus lexicon — if provided, creates a
+   * PrometheusRule holding them, after the `alertRules` group when both are set.
+   */
+  ruleGroups?: Array<RuleGroupEntity | RuleGroupProps>;
   /** Number of replicas (default: 2). */
   replicas?: number;
   /** Additional labels to apply to all resources. */
@@ -89,6 +100,14 @@ export interface MonitoredServiceResult {
  *     { name: "HighErrorRate", expr: 'rate(http_errors_total[5m]) > 0.1', for: "5m", severity: "critical" },
  *   ],
  * });
+ *
+ * // Or with typed rule groups from the prometheus lexicon:
+ * import { RuleGroup } from "@intentius/chant-lexicon-prometheus";
+ * const apiRules = new RuleGroup({
+ *   name: "api",
+ *   rules: [{ alert: "ApiDown", expr: 'up{job="api"} == 0', for: "5m", labels: { severity: "page" } }],
+ * });
+ * MonitoredService({ name: "api", image: "api:1.0", ruleGroups: [apiRules] });
  * ```
  */
 export const MonitoredService = Composite((props: MonitoredServiceProps) => {
@@ -100,6 +119,7 @@ export const MonitoredService = Composite((props: MonitoredServiceProps) => {
     metricsPath = "/metrics",
     scrapeInterval = "30s",
     alertRules,
+    ruleGroups,
     replicas = 2,
     labels: extraLabels = {},
     cpuLimit = "500m",
@@ -197,29 +217,33 @@ export const MonitoredService = Composite((props: MonitoredServiceProps) => {
 
   const result: Record<string, any> = { deployment, service, serviceMonitor };
 
+  const groups: Array<Record<string, unknown>> = [];
   if (alertRules && alertRules.length > 0) {
+    groups.push({
+      name: `${name}.rules`,
+      rules: alertRules.map((rule) => ({
+        alert: rule.name,
+        expr: rule.expr,
+        ...(rule.for && { for: rule.for }),
+        labels: {
+          ...(rule.severity && { severity: rule.severity }),
+        },
+        ...(rule.annotations && { annotations: rule.annotations }),
+      })),
+    });
+  }
+  for (const group of ruleGroups ?? []) {
+    groups.push(ruleGroupConfig(group) as unknown as Record<string, unknown>);
+  }
+
+  if (groups.length > 0) {
     result.prometheusRule = new PrometheusRule(mergeDefaults({
       metadata: {
         name: `${name}-alerts`,
         ...(namespace && { namespace }),
         labels: { ...commonLabels, "app.kubernetes.io/component": "monitoring" },
       },
-      spec: {
-        groups: [
-          {
-            name: `${name}.rules`,
-            rules: alertRules.map((rule) => ({
-              alert: rule.name,
-              expr: rule.expr,
-              ...(rule.for && { for: rule.for }),
-              labels: {
-                ...(rule.severity && { severity: rule.severity }),
-              },
-              ...(rule.annotations && { annotations: rule.annotations }),
-            })),
-          },
-        ],
-      },
+      spec: { groups },
     }, defs?.prometheusRule));
   }
 

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

@@ -8,6 +8,9 @@
  * `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";
@@ -34,6 +37,10 @@ export interface CollectorAgentOptions {
   containerExtra?: Record<string, unknown>;
   /** Annotations on the ServiceAccount, such as a cloud identity binding. */
   serviceAccountAnnotations?: Record<string, string>;
+  /** Annotations on the DaemonSet, such as the deployment-shape markers in `otel-collector-shape.ts`. */
+  workloadAnnotations?: Record<string, string>;
+  /** Annotations on the ConfigMap. */
+  configMapAnnotations?: Record<string, string>;
   defaults?: {
     daemonSet?: Partial<Record<string, unknown>>;
     serviceAccount?: Partial<Record<string, unknown>>;
@@ -58,32 +65,14 @@ export function collectorAgentResources(opts: CollectorAgentOptions): CollectorA
   const bindingName = `${name}-binding`;
   const configMapName = `${name}-config`;
 
-  const container: Record<string, unknown> = {
-    name,
-    image: opts.image,
-    args: [`--config=${opts.configDir}/config.yaml`],
-    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 },
-    ],
-    securityContext: {
-      runAsNonRoot: true,
-      runAsUser: 10001,
-      readOnlyRootFilesystem: true,
-      allowPrivilegeEscalation: false,
-    },
-    ...opts.containerExtra,
-  };
+  const container = collectorContainer(opts);
 
   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 } },
@@ -144,16 +133,63 @@ export function collectorAgentResources(opts: CollectorAgentOptions): CollectorA
     ],
   }, defs?.clusterRoleBinding));
 
-  const configMap = new ConfigMap(mergeDefaults({
+  const configMap = collectorConfigMap(opts, configMapName, opts.configMapAnnotations);
+
+  return { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap };
+}
+
+/** The fields the collector container and its ConfigMap are built from. */
+export type CollectorContainerOptions = Pick<
+  CollectorAgentOptions,
+  "name" | "image" | "configDir" | "ports" | "cpuRequest" | "memoryRequest" | "cpuLimit" | "memoryLimit" | "containerExtra"
+>;
+
+/**
+ * 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: CollectorContainerOptions): Record<string, unknown> {
+  return {
+    name: opts.name,
+    image: opts.image,
+    args: [`--config=${opts.configDir}/config.yaml`],
+    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 },
+    ],
+    securityContext: {
+      runAsNonRoot: true,
+      runAsUser: 10001,
+      readOnlyRootFilesystem: true,
+      allowPrivilegeEscalation: false,
+    },
+    ...opts.containerExtra,
+  };
+}
+
+/** The ConfigMap holding the rendered collector config under `config.yaml`. */
+export function collectorConfigMap(
+  opts: Pick<CollectorAgentOptions, "namespace" | "commonLabels" | "configYaml"> & {
+    defaults?: { configMap?: Partial<Record<string, unknown>> };
+  },
+  configMapName: string,
+  annotations?: Record<string, string>,
+): InstanceType<typeof ConfigMap> {
+  return new ConfigMap(mergeDefaults({
     metadata: {
       name: configMapName,
-      namespace,
-      labels: { ...commonLabels, "app.kubernetes.io/component": "config" },
+      namespace: opts.namespace,
+      labels: { ...opts.commonLabels, "app.kubernetes.io/component": "config" },
+      ...(annotations ? { annotations } : {}),
     },
     data: {
       "config.yaml": opts.configYaml,
     },
-  }, defs?.configMap));
-
-  return { daemonSet, serviceAccount, clusterRole, clusterRoleBinding, configMap };
+  }, opts.defaults?.configMap));
 }