---
title: "Kubernetes branch"
description: "Run a branch collector inside a cluster and forward to the root on your Mac through a tunnel."
source: "https://getloggerhead.com/docs/collectors/kubernetes-branch/"
---

# Kubernetes branch

> Run a branch collector inside a cluster and forward to the root on your Mac through a tunnel.

The root receiver binds `127.0.0.1` on your Mac. A cluster cannot reach that address on its own. Run a branch collector in the cluster and give it a route to the Mac.

## The shape

```text
 Pods ──▶ branch collector (in the cluster) ──▶ tunnel ──▶ 127.0.0.1:<effective port> on the Mac
```

The branch does the cluster work: it reads pod logs and cluster metrics with the `k8s_cluster` and `kubeletstats` receivers from the contrib image, stamps `loggerhead.collector.id`, and forwards over OTLP.

## Step 1: open a route to the Mac

Pick one:

- A **mesh network** such as Tailscale on both the Mac and the cluster nodes. Then the branch sends to the Mac's mesh address.
- An **SSH reverse tunnel** from a cluster node to the Mac.

An ingest token for the root receiver is planned work, so the app does not ask for one yet. Until it lands, keep the root on the loopback interface and reach it through the mesh address or the tunnel. See [Privacy and local access](/docs/mcp-server/privacy-and-local-access/) for what that changes.

## Step 2: configure the branch

```yaml title="branch-k8s.yaml"
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
  k8s_cluster: {}
  kubeletstats:
    auth_type: serviceAccount
    endpoint: https://${env:K8S_NODE_NAME}:10250

processors:
  resource:
    attributes:
      - key: loggerhead.collector.id
        value: k8s-staging
        action: upsert
  batch: {}

exporters:
  otlp:
    endpoint: <mac address>:4317       # the effective port on the Mac
    headers:
      authorization: "Bearer ${env:LOGGERHEAD_INGEST_TOKEN}"
    tls:
      insecure: false
      ca_file: /etc/loggerhead/backend-ca.pem

service:
  pipelines:
    logs:    { receivers: [otlp], processors: [resource, batch], exporters: [otlp] }
    metrics: { receivers: [otlp, k8s_cluster, kubeletstats], processors: [resource, batch], exporters: [otlp] }
    traces:  { receivers: [otlp], processors: [resource, batch], exporters: [otlp] }
```

Deploy the collector with the upstream Helm chart or the OpenTelemetry Operator. Use the `otel/opentelemetry-collector-contrib` image.

## Step 3: check it

The branch appears on the **Collectors** page as `k8s-staging` and reads **online** while records arrive. Filter the Logs page by that collector to see only cluster traffic.

:::note[Coming soon]
A managed route from a cluster to your Mac, with a one-time enrolment code, is in progress. It removes the tunnel step.
:::