From 5323d4d69a54575a9acd304ccd75e1aa476c2e92 Mon Sep 17 00:00:00 2001 From: Joe Sirianni Date: Fri, 13 Feb 2026 08:41:54 -0500 Subject: [PATCH] doc: Kubernetes guide --- docs/guide/kubernetes/assets/configmap.yaml | 279 ++++++++++++++++ docs/guide/kubernetes/assets/deployment.yaml | 322 +++++++++++++++++++ docs/guide/kubernetes/kubernetes.md | 45 +++ 3 files changed, 646 insertions(+) create mode 100644 docs/guide/kubernetes/assets/configmap.yaml create mode 100644 docs/guide/kubernetes/assets/deployment.yaml create mode 100644 docs/guide/kubernetes/kubernetes.md diff --git a/docs/guide/kubernetes/assets/configmap.yaml b/docs/guide/kubernetes/assets/configmap.yaml new file mode 100644 index 0000000..b32f683 --- /dev/null +++ b/docs/guide/kubernetes/assets/configmap.yaml @@ -0,0 +1,279 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-1 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4317 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8888 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-2 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4318 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8889 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-3 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4319 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8890 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-4 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4320 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8891 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-5 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4321 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8892 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-6 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4322 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8893 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-7 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4323 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8894 + level: normal +--- +apiVersion: v1 +kind: ConfigMap +metadata: + name: blitz-collector-config-8 +data: + config.yaml: | + receivers: + otlp: + protocols: + grpc: + endpoint: 0.0.0.0:4324 + + processors: + batch: + + exporters: + debug: + + service: + pipelines: + logs: + receivers: [otlp] + processors: [batch] + exporters: [debug] + + telemetry: + metrics: + readers: + - pull: + exporter: + prometheus: + host: localhost + port: 8895 + level: normal diff --git a/docs/guide/kubernetes/assets/deployment.yaml b/docs/guide/kubernetes/assets/deployment.yaml new file mode 100644 index 0000000..a84bd00 --- /dev/null +++ b/docs/guide/kubernetes/assets/deployment.yaml @@ -0,0 +1,322 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: blitz +spec: + # Scale this up for higher total throughput. + # Total Blitz containers = replicas * 8 + replicas: 1 + selector: + matchLabels: + app: blitz + template: + metadata: + labels: + app: blitz + spec: + containers: + - name: blitz-1 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4317 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-1 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-1 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4317 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-2 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4318 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-2 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-2 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4318 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-3 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4319 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-3 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-3 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4319 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-4 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4320 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-4 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-4 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4320 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-5 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4321 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-5 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-5 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4321 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-6 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4322 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-6 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-6 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4322 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-7 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4323 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-7 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-7 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4323 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + - name: blitz-8 + image: ghcr.io/observiq/blitz:latest + imagePullPolicy: IfNotPresent + args: + - --generator-type=nginx + - --generator-nginx-workers=1 + - --generator-nginx-rate=250ms + - --output-type=otlp-grpc + - --output-otlpgrpc-host=127.0.0.1 + - --output-otlpgrpc-port=4324 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + - name: otel-collector-8 + image: observiq/bindplane-agent:1.72.0 + imagePullPolicy: IfNotPresent + volumeMounts: + - name: otel-config-8 + mountPath: /etc/otel/config.yaml + subPath: config.yaml + ports: + - containerPort: 4324 + resources: + requests: + cpu: 50m + memory: 100Mi + limits: + memory: 100Mi + + volumes: + - name: otel-config-1 + configMap: + name: blitz-collector-config-1 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-2 + configMap: + name: blitz-collector-config-2 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-3 + configMap: + name: blitz-collector-config-3 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-4 + configMap: + name: blitz-collector-config-4 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-5 + configMap: + name: blitz-collector-config-5 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-6 + configMap: + name: blitz-collector-config-6 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-7 + configMap: + name: blitz-collector-config-7 + items: + - key: config.yaml + path: config.yaml + - name: otel-config-8 + configMap: + name: blitz-collector-config-8 + items: + - key: config.yaml + path: config.yaml diff --git a/docs/guide/kubernetes/kubernetes.md b/docs/guide/kubernetes/kubernetes.md new file mode 100644 index 0000000..a393d5e --- /dev/null +++ b/docs/guide/kubernetes/kubernetes.md @@ -0,0 +1,45 @@ +## Kubernetes: highly scaled Blitz with sidecar collectors + +This guide shows a simple pattern for running Blitz at scale in Kubernetes: + +- **Each Pod runs several Blitz containers** +- **Each Blitz container sends OTLP to a dedicated OpenTelemetry Collector sidecar over `localhost`** +- **Each collector is configured by a ConfigMap and exports using the `debug` exporter** +- **Each collector binds to unique TCP ports to avoid port collision** + +### How the ConfigMaps and Deployment work together + +- **Collector config**: Each collector sidecar listens on a unique OTLP/gRPC port (4317–4324) and Prometheus (own metrics) port. There ports are defined in the collector config. +- **ConfigMap → volume**: Each collector mounts its config from a ConfigMap via `volumes[].configMap` + `volumeMounts[].subPath`. +- **Blitz → localhost**: Each Blitz container is configured to send to `127.0.0.1:`, matching its paired collector. + +In one Pod, the pairs look like this: + +- **`blitz-1` → `otel-collector-1`** on `127.0.0.1:4317` +- **`blitz-2` → `otel-collector-2`** on `127.0.0.1:4318` +- … +- **`blitz-8` → `otel-collector-8`** on `127.0.0.1:4324` + +### Complete example (recommended) + +Use the full, ready-to-apply manifests: + +- [`assets/configmap.yaml`](./assets/configmap.yaml) +- [`assets/deployment.yaml`](./assets/deployment.yaml) + +From the repo root: + +```bash +kubectl apply -f docs/guide/kubernetes/assets/configmap.yaml +kubectl apply -f docs/guide/kubernetes/assets/deployment.yaml +``` + +```bash +kubectl get pods -l app=blitz +kubectl logs -l app=blitz -c otel-collector-1 --tail=50 +``` + +### Scaling + +- **Scale Pods**: `kubectl scale deployment/blitz --replicas=` +- **Adjust per-container rate**: change `--generator-*-rate` (each Blitz container runs independently)