Observability / Kubernetes

Connect a cluster

Install the Monocle agent in your Kubernetes cluster

An admin of your organization connects the cluster in Monocle, then installs the Monocle agent with Helm, Argo CD, or Flux. You need Kubernetes 1.33 or later. With the Helm CLI, you need Helm 3.8 or later.

Install the agent

On the Kubernetes page, click Connect a cluster. Enter a name such as prod-eu, then click Connect. Monocle shows the install steps for Helm, Argo CD, and Flux, with the cluster key filled in. Copy them now: the key appears only once.

Terminal
helm upgrade --install monocle-agent oci://ghcr.io/monocle-sh/charts/monocle-k8s-agent \
  --namespace monocle --create-namespace \
  --set monocle.apiKey=<cluster key> \
  --set-string monocle.clusterName=prod-eu

Data appears on the Kubernetes page a few minutes later. Keep monocle.clusterName equal to the name you entered in Monocle. A cluster can't be renamed.

Send your services' telemetry through the agent. Monocle then shows the traces of each workload next to its pods, and the This environment scope finds your namespaces. Each service keeps its own DSN and environment.

deployment.yaml
env:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://monocle-agent.monocle.svc:4318
  - name: OTEL_EXPORTER_OTLP_HEADERS
    value: x-api-key=<DSN key>,x-monocle-env=production

If the agent of a node stops, the services on that node lose the telemetry they send until it runs again.

Replace the key

If the key leaks or you lose it, open the Kubernetes tab of your organization settings. In the menu of the cluster, click New key…, then Replace key. Monocle shows how to give the new key to the agent: with Helm values, or in the monocle-k8s-agent Secret for Argo CD and Flux, then restart the collectors. The old key stops working within 5 minutes, so do it right away.

Upgrade or uninstall

Terminal
helm upgrade monocle-agent oci://ghcr.io/monocle-sh/charts/monocle-k8s-agent \
  --namespace monocle --reset-then-reuse-values
helm uninstall monocle-agent --namespace monocle

--reset-then-reuse-values keeps the values you set and takes the defaults of the new version. It needs Helm 3.14 or later. With Argo CD or Flux, change the chart version in your manifest instead.

Troubleshooting

The install fails with "chart requires kubeVersion". The cluster runs a Kubernetes version older than 1.33.

No data after a few minutes. Check that the pods run with kubectl --namespace monocle get pods, and that the key in monocle.apiKey, or in the monocle-k8s-agent Secret, is the key of this cluster.

Pods show no CPU or memory on kind or minikube. Their kubelets use self-signed certificates. With the Helm CLI, add --set agent.config.receivers.kubeletstats.insecure_skip_verify=true to the command. With Argo CD or Flux, add the same value to the chart values (valuesObject or values):

YAML
agent:
  config:
    receivers:
      kubeletstats:
        insecure_skip_verify: true

The install fails on host ports, for example on GKE Autopilot. With the Helm CLI, add --set agent.ports.otlp.hostPort=0 --set agent.ports.otlp-http.hostPort=0 to the command. With Argo CD or Flux, add these values:

YAML
agent:
  ports:
    otlp:
      hostPort: 0
    otlp-http:
      hostPort: 0

The chart README lists every Helm value.

Search documentation

Search pages and sections of the Monocle documentation