Install Observe Agent on Kubernetes

Note

These instructions apply to tenants created on or after June 6, 2025. If your tenant was created earlier, follow the legacy guide: Install Observe Agent on Kubernetes [Legacy]. Interested in upgrading to the new experience? Open Docs & Support → Contact Support in the product and let us know.

Note

The Observe Agent on Kubernetes is designed to deliver the best-in-class user experience with Kubernetes Explorer. Use the Add Data for Kubernetes page in Observe to guide you through the installation process.

You may follow the instructions on this page to deploy the Observe Agent on Kubernetes, allowing you to gather raw events, logs, and metrics from Kubernetes.

Warning

Amazon EKS Auto Mode, Azure Kubernetes Service (AKS) Automatic, or GKE Autopilot is not supported yet.

This page provides instructions for installing the Observe Agent in a Kubernetes environment to collect metrics, logs, and application telemetry—including OpenTelemetry traces—and forward them to Observe.

Installation

Use the Add Data portal in the product to get the Observe Agent installed in your environment.

Add Data portal

Add the Observe Helm repository

Run the following commands to add the Observe Helm repository to your local Helm setup, allowing you to access and deploy Observe’s charts.

helm repo add observe https://observeinc.github.io/helm-charts
helm repo update

Deploy the Observe Agent

Run the following commands to create a Kubernetes namespace called observe and generate a secret. Replace <YOUR_INGEST_TOKEN> with your instance’s ingest token you create from the Add Data for Kubernetes page(ex: a1b2c3d4e5f6g7h8i9k0:l1m2n3o4p5q6r7s8t9u0v1w2x3y4z5a6).

kubectl create namespace observe
  kubectl -n observe create secret generic agent-credentials --from-literal=OBSERVE_TOKEN=<YOUR_INGEST_TOKEN> 

kubectl annotate secret agent-credentials -n observe \
  meta.helm.sh/release-name=observe-agent \
  meta.helm.sh/release-namespace=observe

kubectl label secret agent-credentials -n observe \
  app.kubernetes.io/managed-by=Helm

Run the following command to deploy the Observe Agent in the observe namespace using observe-agent-monitored-cluster as the name for your Kubernetes cluster. Replace <YOUR_OBSERVE_COLLECTION_ENDPOINT> with your instance’s collection endpoint (ex: https://123456789012.collect.observeinc.com/). For more information on configuring the agent, see values.yaml.

helm install observe-agent observe/agent -n observe \
--set observe.collectionEndpoint.value="<YOUR_OBSERVE_COLLECTION_ENDPOINT>" \
--set cluster.name="observe-agent-monitored-cluster" \
--set node.containers.logs.enabled="true" \
--set application.prometheusScrape.enabled="false" \
--set node.forwarder.enabled="true" \
--set node.forwarder.metrics.outputFormat="otel"

Run the following command to make sure the Observe Agent has been deployed successfully.

kubectl get pods -n observe

Run the following command to save the current configuration values to a file for future configuration adjustments and upgrades.

helm -n observe get values observe-agent -o yaml > observe-agent-values.yaml

Create observe-agent-values.yaml with the following configuration. Replace <YOUR_OBSERVE_COLLECTION_ENDPOINT> with your instance’s collection endpoint (ex: https://123456789012.collect.observeinc.com/). For more information on configuring the agent, see values.yaml.

agent:
  selfMonitor:
    enabled: false
application:
  prometheusScrape:
    enabled: false
cluster:
  events:
    enabled: true
  metrics:
    enabled: true
  name: observe-agent-monitored-cluster
node:
  containers:
    logs:
      enabled: true
    metrics:
      enabled: true
  forwarder:
    enabled: true
    metrics:
      outputFormat: otel
observe:
  collectionEndpoint:
    value: <OBSERVE_COLLECTION_ENDPOINT>
  token:
    create: false

Run the following command to deploy the Observe Agent in the observe namespace

helm install observe-agent observe/agent -n observe --values observe-agent-values.yaml

Run the following command to make sure the Observe Agent has been deployed successfully.

kubectl get pods -n observe

Configure application instrumentation

Once the Observe Agent is deployed, configure your application instrumentation or set the OTEL_EXPORTER_OTLP_ENDPOINT environment variable to one of the following addresses to send application telemetry including traces to the Observe Agent.

Note

When setting up the endpoint to send traces, make sure you use the path that your OTLP library requires. Some libraries need traces to go to /v1/traces, while others expect them at the root path /.

  • OTLP/HTTP endpoint: http://observe-agent-forwarder.observe.svc.cluster.local:4318

  • OTLP/grpc endpoint: http://observe-agent-forwarder.observe.svc.cluster.local:4317

For example, if you are using the OpenTelemetry Astronomy Shop Demo app, create the app.yaml.

default:
  envOverrides:
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: 'http://observe-agent-forwarder.observe.svc.cluster.local:4318'

Upgrade the helm chart for the OpenTelemetry Astronomy Shop Demo app.

helm upgrade --reuse-values -f app.yaml my-otel-demo open-telemetry/opentelemetry-demo

Learn more about how to instrument your app

Uninstall the Observe Agent

You can uninstall the agent from your Kubernetes cluster.

helm uninstall observe-agent -n observe
kubectl -n observe delete secret agent-credentials
kubectl delete namespace observe

Next steps

Use the Kubernetes Explorer to monitor your Kubernetes clusters. To analyze your trace data, explore both the Trace Explorer and the Service Explorer

Further reading