How to deploy Observe Agent in a Custom Namespace

Data Ingestion
, ,
1

When integrating Observe into your Kubernetes cluster, the Observe Agent Helm chart typically installs into the default observe namespace. However, you might prefer to deploy it in a custom namespace (for example, observability) to align with your organization’s naming conventions or to isolate observability tooling.

This guide walks through the process of installing the Observe Agent into a custom namespace cleanly, ensuring all secrets, annotations, and Helm metadata are configured correctly.

:puzzle_piece: Prerequisites

Before you begin, make sure you have:

  • kubectl and helm installed and configured with access to your cluster.
  • Your Observe token handy (OBSERVE_TOKEN).
  • The Observe Helm repository added:
helm repo add observe https://observeinc.github.io/helm-charts
helm repo update

:building_construction: Step 1 — Create the Namespace

Create the target namespace for your deployment (e.g., observability):

kubectl create namespace observability

:locked_with_key: Step 2 — Create the Agent Credentials Secret

The Observe Agent needs credentials to send telemetry to your Observe instance.
Create a Kubernetes secret in your custom namespace with your Observe token:

kubectl -n observability create secret generic agent-credentials \
  --from-literal=OBSERVE_TOKEN=<your_observe_token_here>

:label: Step 3 — Annotate and Label the Secret

Helm uses annotations and labels to manage resources it deploys.
To make the secret Helm-managed (so it won’t get overwritten or orphaned), annotate and label it appropriately:

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

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

These ensure Helm recognizes the pre-created secret during the chart installation.

:gear: Step 4 — Install the Observe Agent Helm Chart

Now you can install the Observe Agent into the custom namespace.
The Helm chart supports namespace overrides for each internal component, so specify them all to ensure resources are created in the right place.

helm install observe-agent observe/agent -n observability \
  --set cluster.namespaceOverride.value="observability" \
  --set cluster-events.namespaceOverride="observability" \
  --set cluster-metrics.namespaceOverride="observability" \
  --set prometheus-scraper.namespaceOverride="observability" \
  --set node-logs-metrics.namespaceOverride="observability" \
  --set monitor.namespaceOverride="observability" \
  --set forwarder.namespaceOverride="observability" \
  --set observe.collectionEndpoint.value="https://<your-collector>.collect.observe-staging.com/" \
  --set cluster.name="k8s-cluster" \
  --set node.enabled="true" \
  --set application.prometheusScrape.enabled="false" \
  --set node.forwarder.enabled="true" \
  --set node.forwarder.metrics.outputFormat="otel"

:memo: Tip:
If your Observe account is in production, replace collect.observe-staging.com with your production collector endpoint.

:brain: Step 5 — Verify the Deployment

Check that all components are running under your custom namespace:

kubectl get pods -n observability

You should see pods similar to:

observe-agent-cluster-events-xxxxx
observe-agent-cluster-metrics-xxxxx
observe-agent-forwarder-xxxxx
observe-agent-monitor-xxxxx
observe-agent-node-logs-metrics-xxxxx
observe-agent-prometheus-scraper-xxxxx

And confirm metrics and logs are successfully flowing into your Observe instance.

:receipt: Step 6 — Upgrade or Uninstall (Optional)

Upgrades and uninstalls work the same as in the default namespace—just specify your namespace:

# Upgrade
helm upgrade observe-agent observe/agent -n observability

# Uninstall
helm uninstall observe-agent -n observability