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.
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-euKeep the key out of Git: create the Secret with kubectl, or sync it from your secret manager, for example with External Secrets.
kubectl create namespace monocle
kubectl -n monocle create secret generic monocle-k8s-agent \
--from-literal=apiKey=<cluster key>Then commit the Application. With createSecret: false, the chart reads the key from that Secret.
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
name: monocle-agent
namespace: argocd
spec:
project: default
source:
repoURL: ghcr.io/monocle-sh/charts
chart: monocle-k8s-agent
targetRevision: 0.3.0
helm:
valuesObject:
monocle:
createSecret: false
clusterName: "prod-eu"
destination:
server: https://kubernetes.default.svc
namespace: monocle
syncPolicy:
automated: {}Keep the key out of Git: create the Secret with kubectl, or sync it from your secret manager, for example with SOPS or External Secrets.
kubectl create namespace monocle
kubectl -n monocle create secret generic monocle-k8s-agent \
--from-literal=apiKey=<cluster key>Then commit the chart source and the HelmRelease. With createSecret: false, the chart reads the key from that Secret.
apiVersion: source.toolkit.fluxcd.io/v1
kind: OCIRepository
metadata:
name: monocle-k8s-agent
namespace: monocle
spec:
interval: 12h
url: oci://ghcr.io/monocle-sh/charts/monocle-k8s-agent
ref:
tag: 0.3.0
layerSelector:
mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip
operation: copy
---
apiVersion: helm.toolkit.fluxcd.io/v2
kind: HelmRelease
metadata:
name: monocle-agent
namespace: monocle
spec:
interval: 1h
chartRef:
kind: OCIRepository
name: monocle-k8s-agent
values:
monocle:
createSecret: false
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.
Link your services to their pods
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.
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=productionIn the DSN, replace https://ingest.monocle.sh with the address of the agent:
env:
- name: MONOCLE_DSN
value: http://<DSN key>@monocle-agent.monocle.svc:4318/<service ID>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
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):
agent:
config:
receivers:
kubeletstats:
insecure_skip_verify: trueThe 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:
agent:
ports:
otlp:
hostPort: 0
otlp-http:
hostPort: 0The chart README lists every Helm value.