> ## Documentation Index
> Fetch the complete documentation index at: https://docs.obsy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a cluster

> Register a Kubernetes cluster and install the OTel collector.

## 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

| Component          | Description                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Gateway**        | A central collector that receives OTLP traffic from your services, applies sampling and filters, and exports to your platforms. Runs as a `Deployment`. |
| **Node collector** | A `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:

| Port | Protocol | Purpose                               |
| ---- | -------- | ------------------------------------- |
| 4317 | gRPC     | OTLP/gRPC ingestion                   |
| 4318 | HTTP     | OTLP/HTTP ingestion                   |
| 8888 | HTTP     | Collector 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

<AccordionGroup>
  <Accordion title="Cluster shows 'Connection error'">
    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.
  </Accordion>

  <Accordion title="Collector stuck in 'Installing'">
    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.
  </Accordion>

  <Accordion title="No metrics in Datadog / Grafana after install">
    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.
  </Accordion>
</AccordionGroup>