Kubernetes branch

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

 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.

When the branch arrives from a non-loopback address, the root requires a token. Turn on Settings → Ingest → Require token in the app, set a token, and set the bind host to the interface you expose. See Privacy and local access for what that changes.

Step 2: configure the branch

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>:14317       # 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.