Kubernetes Workload Observation

CollectorCtrl can show the OpenTelemetry Collectors you already run in Kubernetes next to your host collectors. You keep your Helm charts, GitOps controllers and deployment pipelines. A small in-cluster observer reports what is running; CollectorCtrl displays it.

How it works

1. You install the observer (Helm chart from CollectorCtrl-K8s-Operator) once per cluster.
2. For each collector workload you want to see, you create one CollectorMonitor resource.
3. The observer reads the workload, its pods and its mounted ConfigMap through the Kubernetes API and sends a snapshot to CollectorCtrl over a trusted wss:// OpAMP connection.
4. The observer only ever writes CollectorMonitor status. It never changes your workloads, ConfigMaps or application pods.

What you see in CollectorCtrl

The Fleet Inventory has three views: All, Host collectors and Kubernetes workloads. The Kubernetes view adds cluster and namespace filters. Opening a workload shows:

What CollectorCtrl will not do to observed workloads

Your deployment system remains in charge. Observed Kubernetes workloads are:

• Excluded from host configuration policies, canary rollouts, Supervisor upgrades, runtime templates and Telemetry Governor taps.
• Protected from host-only actions. Restart, remote commands, package deployment and instrumentation are rejected for them, whether requested from the UI, the REST API, the MCP server or Copilot. Mixed bulk operations list unsupported targets instead of reporting success.
• Not edited from CollectorCtrl. Git pull request workflows and emergency direct writes for workloads are not available in this release.

Install the observer

kubectl create namespace collectorctrl-system

kubectl create secret generic collectorctrl-auth \
  --namespace collectorctrl-system \
  --from-literal=enrollment-token=cce_YOUR_TOKEN

helm upgrade --install collectorctrl-observer ./helm-charts/collectorctrl-operator \
  --namespace collectorctrl-system \
  --set opamp.server=wss://collectorctrl.example.internal:4320/v1/opamp \
  --set opamp.enrollmentSecret=collectorctrl-auth

The chart pulls the published observer image, ghcr.io/collectorctrl/collectorctrl-k8s-operator/operator:latest, by default. Override image.repository and image.tag to use your own registry or a pinned build.

Common chart settings

OpenShift: add -f helm-charts/collectorctrl-operator/values-openshift.yaml before your own values. This lets the cluster's SCC assign the UID and fsGroup. Do not grant anyuid or privileged to work around an install error.

Monitor an existing collector

apiVersion: collectorctrl.io/v1alpha1
kind: CollectorMonitor
metadata:
  name: existing-gateway
  namespace: observability
  labels:
    k8s.cluster.name: production-eu
spec:
  workloadSelector:
    kind: Deployment          # Deployment, DaemonSet or StatefulSet
    name: otel-gateway
    matchLabels: {}
  collectorContainer: otel-collector   # required for multi-container pods
  opampServer: wss://collectorctrl.example.internal:4320/v1/opamp
  reportConfig: false                  # opt in to upload the config YAML
  healthCheck:
    interval: 30s

• One monitor selects exactly one workload. An ambiguous selector reports an error rather than picking one.
• If the container mounts several ConfigMaps or YAML keys, set configMapSelector.name and configMapSelector.key.
• Don't create two monitors for the same collector container; they would share one identity.
• Check discovery and connection errors with kubectl describe collectormonitor existing-gateway -n observability.

Upgrading an existing observer

If you installed an earlier observer build:

1. Create an Agent Enrollment token and reference it through opamp.enrollmentSecret.
2. Make sure persistent credential storage is available, and reuse it across upgrades.
3. Run one replica.
4. Set opamp.server to the trusted wss:// endpoint and use the same endpoint in every monitor. Add opampCAConfigMap for a private CA.
5. Installations that used a shared secret should first run with opamp.authMode=legacy and opamp.existingSecret (key secret-key) so credentials are issued and saved, then switch to enrollment and turn off server legacy mode.

Upgrade the server and the observer together.

Current limits

• Discovery covers Deployments, DaemonSets and StatefulSets with a selected collector container and mounted or projected ConfigMaps. Injected sidecars without a template ConfigMap mount, native OpenTelemetry Operator resources, Secret-backed configuration and OpenShift DeploymentConfig are not covered yet.
• Command-line config merges, environment expansion and remote config providers are not reconstructed.
• Cluster- or namespace-specific team permissions are not implemented yet; existing permissions and environment rules still apply.
• Old workload records need manual pruning. Deleting and recreating a workload creates a new fleet identity.
• Observed workloads count toward the existing agent capacity allowance.

Coming next

Platform validation across Kubernetes distributions, verified Git ownership and source bindings, then validated pull-request proposals for raw ConfigMaps, the official Helm chart and OpenTelemetryCollector resources.