Skip to main content

​
Add a cluster

  1. Go to Clusters in the sidebar.
  2. Click Add cluster.
  3. Fill in:
    • Name — a unique identifier used in sampling configs and reports (e.g. prod-us-east-1).
    • Display name — the human-readable label shown in the UI.
    • Kubeconfig — paste the full kubeconfig YAML for the cluster. Only the cluster, user, and context sections are needed.
  4. Click Save.
Obsy validates connectivity by making a lightweight API server call. If validation fails, check that:
  • The API server URL is reachable from Obsy’s backend
  • The service account or user has at least get and list permissions on pods and namespaces
  • The cluster’s network policies allow inbound HTTPS from Obsy’s CIDR

​
Install the OTel collector

After a cluster is registered, open it from the Clusters list and click OTel Collector in the sidebar, or go directly to OTel Collector and select the cluster. Click Install Collector. Obsy:
  1. Downloads the open-telemetry/opentelemetry-collector Helm chart.
  2. Generates a config file based on your connected platforms and sampling settings.
  3. Runs a Helm install into the obsy-system namespace (created if it doesn’t exist).
  4. Polls the deployment until all pods are running.
The install typically takes 60–120 seconds. The cluster card shows a Healthy status badge when the gateway and node collector are both running.

​
What gets deployed

ComponentDescription
GatewayA central collector that receives OTLP traffic from your services, applies sampling and filters, and exports to your platforms. Runs as a Deployment.
Node collectorA DaemonSet that collects host metrics, kubelet stats, and container logs from every node and forwards them to the gateway.

​
Namespace

All collector components run in the obsy-system namespace. The gateway listens on:
PortProtocolPurpose
4317gRPCOTLP/gRPC ingestion
4318HTTPOTLP/HTTP ingestion
8888HTTPCollector health metrics (Prometheus)
Point your services’ OTEL_EXPORTER_OTLP_ENDPOINT at http://obsy-gateway.obsy-system.svc.cluster.local:4317.

​
Removing a cluster

Go to Clusters, open the cluster detail, and click Remove cluster. This unregisters the cluster from Obsy but does not uninstall the collector Helm release — run helm uninstall obsy-collector -n obsy-system manually if you want to remove the collector too.

​
Troubleshooting

The API server is unreachable. Verify the server URL in your kubeconfig and that Obsy’s egress can reach it. Corporate firewalls and private clusters with no public endpoint require a network tunnel or private connectivity.
Check the Helm release status: helm list -n obsy-system. If it shows pending-upgrade, the previous install timed out. Obsy will auto-recover on the next sync. You can also click Reinstall on the cluster detail page.
Confirm your platform API key has write permissions. Open the collector pod logs: kubectl logs -n obsy-system -l app=obsy-gateway and look for exporter error lines.