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.

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