From 1cd316ed766b037673484b6076abfa03a1101196 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Sun, 26 Apr 2026 15:17:02 +0300 Subject: [PATCH 01/11] document obi k8s-cache --- .../configure/metrics-traces-attributes.md | 11 +++ .../zero-code/obi/setup/kubernetes-helm.md | 28 ++++++ .../en/docs/zero-code/obi/setup/kubernetes.md | 87 +++++++++++++++++++ 3 files changed, 126 insertions(+) diff --git a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md index 1cfeff330e41..7a1b572b1e3f 100644 --- a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md +++ b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md @@ -311,6 +311,7 @@ attributes: | `informers_sync_timeout`
`OTEL_EBPF_KUBE_INFORMERS_SYNC_TIMEOUT` | Maximum time to wait for Kubernetes metadata before starting. For more information, refer to the [informers sync timeout section](#informers-sync-timeout). | Duration | 30s | | `reconnect_initial_interval`
`OTEL_EBPF_KUBE_RECONNECT_INITIAL_INTERVAL` | Initial delay before reconnecting to the Kubernetes API after connection loss. For more information, refer to the [reconnect initial interval section](#reconnect-initial-interval). | Duration | 5s | | `informers_resync_period`
`OTEL_EBPF_KUBE_INFORMERS_RESYNC_PERIOD` | Periodically resynchronize all Kubernetes metadata. For more information, refer to the [informers resynchronization period section](#informers-resynchronization-period). | Duration | 30m | +| `meta_cache_address`
`OTEL_EBPF_KUBE_META_CACHE_ADDRESS` | Address of an external `k8s-cache` service to fetch Kubernetes metadata from. For more information, refer to the [meta cache address section](#meta-cache-address). | string | (empty) | | `service_name_template`
`OTEL_EBPF_SERVICE_NAME_TEMPLATE` | Go template for service names. For more information, refer to the [service name template section](#service-name-template). | string | (empty) | ### Enable Kubernetes @@ -384,6 +385,16 @@ OBI immediately receives any update on resources' metadata. In addition, OBI periodically resynchronizes all Kubernetes metadata at the frequency you specify with this property. Higher values reduce the load on the Kubernetes API service. +### Meta cache address + +When set, OBI fetches Kubernetes metadata from an external `k8s-cache` service +over gRPC instead of running its own informers against the Kubernetes API +server. This is recommended on large clusters and DaemonSet deployments to avoid +overloading the Kubernetes API. + +For background and deployment instructions, see +[Centralizing Kubernetes metadata with k8s-cache](../../setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). + ### Service name template You can template service names using Go templates. This lets you create diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index aa45ca10bb10..a06aa2cda25b 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -22,6 +22,7 @@ Contents: - [Deploying OBI from helm](#deploying-obi-from-helm) - [Configuring OBI](#configuring-obi) - [Configuring OBI metadata](#configuring-obi-metadata) +- [Centralizing Kubernetes metadata with k8s-cache](#centralizing-kubernetes-metadata-with-k8s-cache) - [Providing secrets to the Helm configuration](#providing-secrets-to-the-helm-configuration) @@ -108,6 +109,33 @@ cluster roles, security contexts, etc. The [OBI Helm chart documentation](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-ebpf-instrumentation) describes the diverse configuration options. +## Centralizing Kubernetes metadata with k8s-cache + +By default each OBI Pod opens its own connections to the Kubernetes API server +to watch Pod, Node, and Service metadata. On large clusters this can overload +the API server and affect the whole cluster. + +To avoid that, the OBI Helm chart can deploy a small companion service called +`k8s-cache`. The cache watches the Kubernetes API once on behalf of all OBI Pods +and streams metadata to them over gRPC, so OBI no longer talks to the API server +directly. For more background on what `k8s-cache` is and when to use it, see the +[Kubernetes setup guide](../kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). + +To enable it, set `k8sCache.replicas` to a non-zero value in your +`helm-obi.yml`: + +```yaml +k8sCache: + replicas: 1 +``` + +A single replica is usually enough. For high availability or very large +clusters, increase the replica count — OBI Pods will load-balance across them +through the cache `Service` and reconnect to a healthy replica on failure. + +When `k8sCache.replicas` is `0` (the default), the cache is not deployed and +each OBI Pod uses its own local informers. + ## Providing secrets to the Helm configuration If you are submitting directly the metrics and traces to your observability diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index 26b58dc3eaa6..6db65f5399c8 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -412,6 +412,93 @@ metadata: --- ``` +## Centralizing Kubernetes metadata with k8s-cache + +When OBI runs as a DaemonSet, every OBI Pod opens its own `list` and `watch` +connections against the Kubernetes API server to fetch the metadata it needs to +decorate metrics and traces. On large clusters this fan-out can put significant +load on the API server, to the point where it can affect the whole cluster. + +To avoid that, OBI ships an optional companion service called `k8s-cache`. It +runs as a small `Deployment`, watches the Kubernetes API once on behalf of every OBI Pod, and streams the metadata to OBI +instances over gRPC. Each OBI Pod opens a single connection to the cache instead +of to the API server. + +Use `k8s-cache` when: + +- You run OBI as a DaemonSet on a large cluster. +- You run many OBI replicas (large `Deployment`, multiple sidecars, etc.) on the + same cluster. +- The Kubernetes API server is under pressure or rate-limited. + +If you do not configure a cache address, each OBI instance keeps its own local +in-process informers, which is fine for small clusters. + +`k8s-cache` is only relevant when running OBI on Kubernetes; it has no effect in +the standalone or Docker setups. + +To use the cache, deploy it and point OBI at its `Service` address with the +`OTEL_EBPF_KUBE_META_CACHE_ADDRESS` environment variable (or +`attributes.kubernetes.meta_cache_address` in YAML). The easiest way is to use +the +[OBI Helm chart](../kubernetes-helm/#centralizing-kubernetes-metadata-with-k8s-cache), +which sets up the `Deployment`, `Service`, and OBI wiring for you when you set +`k8sCache.replicas` to a non-zero value. + +If you prefer to deploy it manually, the cache is published as the +`ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/opentelemetry-ebpf-k8s-cache` +container image. A minimal manifest looks like: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: k8s-cache +spec: + replicas: 1 + selector: + matchLabels: + app: k8s-cache + template: + metadata: + labels: + app: k8s-cache + spec: + serviceAccountName: obi # needs list/watch on pods, nodes, services + containers: + - name: k8s-cache + image: ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/opentelemetry-ebpf-k8s-cache:latest + ports: + - containerPort: 50055 + name: grpc +--- +apiVersion: v1 +kind: Service +metadata: + name: k8s-cache +spec: + selector: + app: k8s-cache + ports: + - port: 50055 + name: grpc + protocol: TCP +``` + +Then point OBI at it from the DaemonSet: + +```yaml +env: + - name: OTEL_EBPF_KUBE_METADATA_ENABLE + value: 'true' + - name: OTEL_EBPF_KUBE_META_CACHE_ADDRESS + value: 'k8s-cache.default.svc:50055' +``` + +A single replica is usually enough. For high availability, run multiple replicas +behind the same `Service` — each OBI Pod connects to one and reconnects to +another on failure. + ## Providing an external configuration file In the previous examples, OBI was configured via environment variables. However, From be153513514c7438b3a220e2ef507a9c29a477d5 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Sun, 26 Apr 2026 15:47:03 +0300 Subject: [PATCH 02/11] format --- content/en/docs/zero-code/obi/setup/kubernetes.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index 6db65f5399c8..5b912c8e24fd 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -420,9 +420,9 @@ decorate metrics and traces. On large clusters this fan-out can put significant load on the API server, to the point where it can affect the whole cluster. To avoid that, OBI ships an optional companion service called `k8s-cache`. It -runs as a small `Deployment`, watches the Kubernetes API once on behalf of every OBI Pod, and streams the metadata to OBI -instances over gRPC. Each OBI Pod opens a single connection to the cache instead -of to the API server. +runs as a small `Deployment`, watches the Kubernetes API once on behalf of every +OBI Pod, and streams the metadata to OBI instances over gRPC. Each OBI Pod opens +a single connection to the cache instead of to the API server. Use `k8s-cache` when: From 777251009a6e4955ebc7721946c5ada055fd2e00 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Mon, 27 Apr 2026 13:22:02 +0300 Subject: [PATCH 03/11] add reference for english documentation from translations --- content/es/docs/zero-code/obi/setup/kubernetes.md | 6 ++++++ content/ja/docs/zero-code/obi/setup/kubernetes.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/content/es/docs/zero-code/obi/setup/kubernetes.md b/content/es/docs/zero-code/obi/setup/kubernetes.md index 933ec8dbf2b0..e3ea6381fe34 100644 --- a/content/es/docs/zero-code/obi/setup/kubernetes.md +++ b/content/es/docs/zero-code/obi/setup/kubernetes.md @@ -463,3 +463,9 @@ env: key: otelcol-secret name: headers ``` + +## Centralización de metadatos de Kubernetes con k8s-cache {#centralizing-kubernetes-metadata-with-k8s-cache} + +Esta sección aún no se ha traducido. Consulta la +[versión en inglés](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache) +para conocer los detalles sobre el servicio `k8s-cache`. diff --git a/content/ja/docs/zero-code/obi/setup/kubernetes.md b/content/ja/docs/zero-code/obi/setup/kubernetes.md index 3c5109c6b502..9213b5fb8f92 100644 --- a/content/ja/docs/zero-code/obi/setup/kubernetes.md +++ b/content/ja/docs/zero-code/obi/setup/kubernetes.md @@ -401,3 +401,9 @@ env: key: otelcol-secret name: headers ``` + +## k8s-cache による Kubernetes メタデータの集約 {#centralizing-kubernetes-metadata-with-k8s-cache} + +このセクションはまだ翻訳されていません。`k8s-cache` サービスの詳細については、 +[英語版](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache) +を参照してください。 From e8850f1462060770fea705edd931cb0d84dddad3 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Tue, 28 Apr 2026 11:20:52 +0300 Subject: [PATCH 04/11] PR comments --- .../zero-code/obi/setup/kubernetes-helm.md | 16 ++- .../en/docs/zero-code/obi/setup/kubernetes.md | 101 ++++++++++-------- static/refcache.json | 4 + 3 files changed, 70 insertions(+), 51 deletions(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index a06aa2cda25b..392fd9dfc510 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -112,13 +112,21 @@ describes the diverse configuration options. ## Centralizing Kubernetes metadata with k8s-cache By default each OBI Pod opens its own connections to the Kubernetes API server -to watch Pod, Node, and Service metadata. On large clusters this can overload -the API server and affect the whole cluster. +to watch Pod, Node, and Service metadata, not only from its local node, but from +the entire k8s cluster. This is done in order to enrich not only the source of +the request, but the destination info (for example, getting the service name for +an outbound http request to add +[peer](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) +attributes, or for +[service graph](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/servicegraphconnector) +metric destination). Querying the full k8s cluster metadata on large clusters +from each OBI pod can overload the API server and affect the whole cluster. To avoid that, the OBI Helm chart can deploy a small companion service called `k8s-cache`. The cache watches the Kubernetes API once on behalf of all OBI Pods -and streams metadata to them over gRPC, so OBI no longer talks to the API server -directly. For more background on what `k8s-cache` is and when to use it, see the +and streams metadata to them over gRPC, which removes OBI's per-Pod informer +traffic to the API server and substantially reduces API load. For more +background on what `k8s-cache` is and when to use it, see the [Kubernetes setup guide](../kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). To enable it, set `k8sCache.replicas` to a non-zero value in your diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index 5b912c8e24fd..a057bbaed782 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -358,50 +358,50 @@ spec: serviceAccount: obi hostPID: true # <-- Important. Required in Daemonset mode so OBI can discover all monitored processes containers: - - name: obi - terminationMessagePolicy: FallbackToLogsOnError - image: otel/ebpf-instrument:main - env: - - name: OTEL_EBPF_TRACE_PRINTER - value: "text" - - name: OTEL_EBPF_KUBE_METADATA_ENABLE - value: "autodetect" - - name: KUBE_NAMESPACE - valueFrom: - fieldRef: - fieldPath: metadata.namespace - ... - securityContext: - runAsUser: 0 - readOnlyRootFilesystem: true - capabilities: - add: - - BPF # <-- Important. Required for most eBPF probes to function correctly. - - SYS_PTRACE # <-- Important. Allows OBI to access the container namespaces and inspect executables. - - NET_RAW # <-- Important. Allows OBI to use socket filters for http requests. - - CHECKPOINT_RESTORE # <-- Important. Allows OBI to open ELF files. - - DAC_READ_SEARCH # <-- Important. Allows OBI to open ELF files. - - PERFMON # <-- Important. Allows OBI to load BPF programs. - #- SYS_RESOURCE # <-- pre 5.11 only. Allows OBI to increase the amount of locked memory. - #- SYS_ADMIN # <-- Required for Go application trace context propagation, or if kernel.perf_event_paranoid >= 3 on Debian distributions. - drop: - - ALL - volumeMounts: - - name: var-run-obi - mountPath: /var/run/obi - - name: cgroup - mountPath: /sys/fs/cgroup + - name: obi + terminationMessagePolicy: FallbackToLogsOnError + image: otel/ebpf-instrument:main + env: + - name: OTEL_EBPF_TRACE_PRINTER + value: "text" + - name: OTEL_EBPF_KUBE_METADATA_ENABLE + value: "autodetect" + - name: KUBE_NAMESPACE + valueFrom: + fieldRef: + fieldPath: metadata.namespace + ... + securityContext: + runAsUser: 0 + readOnlyRootFilesystem: true + capabilities: + add: + - BPF # <-- Important. Required for most eBPF probes to function correctly. + - SYS_PTRACE # <-- Important. Allows OBI to access the container namespaces and inspect executables. + - NET_RAW # <-- Important. Allows OBI to use socket filters for http requests. + - CHECKPOINT_RESTORE # <-- Important. Allows OBI to open ELF files. + - DAC_READ_SEARCH # <-- Important. Allows OBI to open ELF files. + - PERFMON # <-- Important. Allows OBI to load BPF programs. + #- SYS_RESOURCE # <-- pre 5.11 only. Allows OBI to increase the amount of locked memory. + #- SYS_ADMIN # <-- Required for Go application trace context propagation, or if kernel.perf_event_paranoid >= 3 on Debian distributions. + drop: + - ALL + volumeMounts: + - name: var-run-obi + mountPath: /var/run/obi + - name: cgroup + mountPath: /sys/fs/cgroup tolerations: - - effect: NoSchedule - operator: Exists - - effect: NoExecute - operator: Exists + - effect: NoSchedule + operator: Exists + - effect: NoExecute + operator: Exists volumes: - - name: var-run-obi - emptyDir: {} - - name: cgroup - hostPath: - path: /sys/fs/cgroup + - name: var-run-obi + emptyDir: { } + - name: cgroup + hostPath: + path: /sys/fs/cgroup --- apiVersion: apps/v1 kind: Deployment @@ -416,13 +416,20 @@ metadata: When OBI runs as a DaemonSet, every OBI Pod opens its own `list` and `watch` connections against the Kubernetes API server to fetch the metadata it needs to -decorate metrics and traces. On large clusters this fan-out can put significant -load on the API server, to the point where it can affect the whole cluster. +decorate metrics and traces, not only the local node metadata, but metadata from +the entire cluster. this is done to enrich information outside of the local +node, for example to add +[peer](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) +attributes to spans making requests between nodes on the cluster. On large +clusters this fan-out can put significant load on the API server, to the point +where it can affect the whole cluster. To avoid that, OBI ships an optional companion service called `k8s-cache`. It -runs as a small `Deployment`, watches the Kubernetes API once on behalf of every -OBI Pod, and streams the metadata to OBI instances over gRPC. Each OBI Pod opens -a single connection to the cache instead of to the API server. +runs as a small Deployment, watches the Kubernetes API once on behalf of every +OBI Pod, and streams the metadata to OBI instances over gRPC. This removes OBI's +per-Pod informer traffic to the API server and greatly reduces API load, though +OBI may still perform limited direct Kubernetes API lookups for node and cluster +metadata. Use `k8s-cache` when: diff --git a/static/refcache.json b/static/refcache.json index e98195f3fb77..9eb29909923f 100644 --- a/static/refcache.json +++ b/static/refcache.json @@ -20119,6 +20119,10 @@ "StatusCode": 206, "LastSeen": "2026-04-22T15:43:39.509211163Z" }, + "https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services": { + "StatusCode": 206, + "LastSeen": "2026-04-28T11:12:12.096928+03:00" + }, "https://opentracing.io": { "StatusCode": 206, "LastSeen": "2026-04-24T10:07:47.977740197Z" From 58dbc6e6d937de18225e7a2c60cec0db2ab830f1 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Tue, 28 Apr 2026 11:30:11 +0300 Subject: [PATCH 05/11] lint fixes --- content/en/docs/zero-code/obi/setup/kubernetes-helm.md | 8 ++++---- content/en/docs/zero-code/obi/setup/kubernetes.md | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index 392fd9dfc510..4bd147e4da74 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -113,13 +113,13 @@ describes the diverse configuration options. By default each OBI Pod opens its own connections to the Kubernetes API server to watch Pod, Node, and Service metadata, not only from its local node, but from -the entire k8s cluster. This is done in order to enrich not only the source of +the entire K8S cluster. This is done in order to enrich not only the source of the request, but the destination info (for example, getting the service name for -an outbound http request to add -[peer](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) +an outbound HTTP request to add +[peer](/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) attributes, or for [service graph](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/servicegraphconnector) -metric destination). Querying the full k8s cluster metadata on large clusters +metric destination). Querying the full K8S cluster metadata on large clusters from each OBI pod can overload the API server and affect the whole cluster. To avoid that, the OBI Helm chart can deploy a small companion service called diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index a057bbaed782..bd183ebaab38 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -419,7 +419,7 @@ connections against the Kubernetes API server to fetch the metadata it needs to decorate metrics and traces, not only the local node metadata, but metadata from the entire cluster. this is done to enrich information outside of the local node, for example to add -[peer](https://opentelemetry.io/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) +[peer](/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) attributes to spans making requests between nodes on the cluster. On large clusters this fan-out can put significant load on the API server, to the point where it can affect the whole cluster. From 6c4ad43c4465e1e9bf6d60b63deac98b2a0cfa1e Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Tue, 28 Apr 2026 13:26:27 +0300 Subject: [PATCH 06/11] lint fixes --- content/en/docs/zero-code/obi/setup/kubernetes-helm.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index 4bd147e4da74..e43da1131a43 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -113,13 +113,13 @@ describes the diverse configuration options. By default each OBI Pod opens its own connections to the Kubernetes API server to watch Pod, Node, and Service metadata, not only from its local node, but from -the entire K8S cluster. This is done in order to enrich not only the source of +the entire K8s cluster. This is done in order to enrich not only the source of the request, but the destination info (for example, getting the service name for an outbound HTTP request to add [peer](/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) attributes, or for [service graph](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/connector/servicegraphconnector) -metric destination). Querying the full K8S cluster metadata on large clusters +metric destination). Querying the full K8s cluster metadata on large clusters from each OBI pod can overload the API server and affect the whole cluster. To avoid that, the OBI Helm chart can deploy a small companion service called From d2ee317eb51a63d75d7b47cc8b4289464e23d7a1 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 <73278770+NimrodAvni78@users.noreply.github.com> Date: Thu, 30 Apr 2026 09:55:36 +0300 Subject: [PATCH 07/11] Update content/en/docs/zero-code/obi/setup/kubernetes.md Co-authored-by: Tyler Yahn --- content/en/docs/zero-code/obi/setup/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index bd183ebaab38..874a5537c91c 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -417,7 +417,7 @@ metadata: When OBI runs as a DaemonSet, every OBI Pod opens its own `list` and `watch` connections against the Kubernetes API server to fetch the metadata it needs to decorate metrics and traces, not only the local node metadata, but metadata from -the entire cluster. this is done to enrich information outside of the local +the entire cluster. This is done to enrich information outside of the local node, for example to add [peer](/docs/specs/semconv/registry/attributes/service/#service-attributes-for-peer-services) attributes to spans making requests between nodes on the cluster. On large From b72f8a2aacecce5e03add7a8547c55ff4b423ecb Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Sun, 3 May 2026 11:47:19 +0300 Subject: [PATCH 08/11] fix --- content/en/docs/zero-code/obi/setup/kubernetes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index 874a5537c91c..fd16d5ded9db 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -431,7 +431,7 @@ per-Pod informer traffic to the API server and greatly reduces API load, though OBI may still perform limited direct Kubernetes API lookups for node and cluster metadata. -Use `k8s-cache` when: +Use of `k8s-cache` is always recommended, but especially if: - You run OBI as a DaemonSet on a large cluster. - You run many OBI replicas (large `Deployment`, multiple sidecars, etc.) on the From 12cf4a0614682394e1b6e1b42750301f7b811c27 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 <73278770+NimrodAvni78@users.noreply.github.com> Date: Thu, 14 May 2026 09:35:55 +0300 Subject: [PATCH 09/11] Remove localized references Co-authored-by: Vitor Vasconcellos --- .../zero-code/obi/configure/metrics-traces-attributes.md | 2 +- content/en/docs/zero-code/obi/setup/kubernetes-helm.md | 2 +- content/en/docs/zero-code/obi/setup/kubernetes.md | 2 +- content/es/docs/zero-code/obi/setup/kubernetes.md | 5 ----- content/ja/docs/zero-code/obi/setup/kubernetes.md | 5 ----- 5 files changed, 3 insertions(+), 13 deletions(-) diff --git a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md index 43e594837ece..d53b7f516e4b 100644 --- a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md +++ b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md @@ -427,7 +427,7 @@ server. This is recommended on large clusters and DaemonSet deployments to avoid overloading the Kubernetes API. For background and deployment instructions, see -[Centralizing Kubernetes metadata with k8s-cache](../../setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). +[Centralizing Kubernetes metadata with k8s-cache](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). ### Service name template diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index e43da1131a43..75ed3deb731b 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -127,7 +127,7 @@ To avoid that, the OBI Helm chart can deploy a small companion service called and streams metadata to them over gRPC, which removes OBI's per-Pod informer traffic to the API server and substantially reduces API load. For more background on what `k8s-cache` is and when to use it, see the -[Kubernetes setup guide](../kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). +[Kubernetes setup guide](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). To enable it, set `k8sCache.replicas` to a non-zero value in your `helm-obi.yml`: diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index fd16d5ded9db..17faba420699 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -448,7 +448,7 @@ To use the cache, deploy it and point OBI at its `Service` address with the `OTEL_EBPF_KUBE_META_CACHE_ADDRESS` environment variable (or `attributes.kubernetes.meta_cache_address` in YAML). The easiest way is to use the -[OBI Helm chart](../kubernetes-helm/#centralizing-kubernetes-metadata-with-k8s-cache), +[OBI Helm chart](/docs/zero-code/obi/setup/kubernetes-helm/#centralizing-kubernetes-metadata-with-k8s-cache), which sets up the `Deployment`, `Service`, and OBI wiring for you when you set `k8sCache.replicas` to a non-zero value. diff --git a/content/es/docs/zero-code/obi/setup/kubernetes.md b/content/es/docs/zero-code/obi/setup/kubernetes.md index e3ea6381fe34..ac8e8f096bda 100644 --- a/content/es/docs/zero-code/obi/setup/kubernetes.md +++ b/content/es/docs/zero-code/obi/setup/kubernetes.md @@ -464,8 +464,3 @@ env: name: headers ``` -## Centralización de metadatos de Kubernetes con k8s-cache {#centralizing-kubernetes-metadata-with-k8s-cache} - -Esta sección aún no se ha traducido. Consulta la -[versión en inglés](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache) -para conocer los detalles sobre el servicio `k8s-cache`. diff --git a/content/ja/docs/zero-code/obi/setup/kubernetes.md b/content/ja/docs/zero-code/obi/setup/kubernetes.md index 9213b5fb8f92..363619ad0544 100644 --- a/content/ja/docs/zero-code/obi/setup/kubernetes.md +++ b/content/ja/docs/zero-code/obi/setup/kubernetes.md @@ -402,8 +402,3 @@ env: name: headers ``` -## k8s-cache による Kubernetes メタデータの集約 {#centralizing-kubernetes-metadata-with-k8s-cache} - -このセクションはまだ翻訳されていません。`k8s-cache` サービスの詳細については、 -[英語版](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache) -を参照してください。 From 0708b0773a449e12b8156837bad5d4c97ecde230 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Thu, 14 May 2026 09:42:25 +0300 Subject: [PATCH 10/11] fix --- content/es/docs/zero-code/obi/setup/kubernetes.md | 1 - content/ja/docs/zero-code/obi/setup/kubernetes.md | 1 - 2 files changed, 2 deletions(-) diff --git a/content/es/docs/zero-code/obi/setup/kubernetes.md b/content/es/docs/zero-code/obi/setup/kubernetes.md index ac8e8f096bda..933ec8dbf2b0 100644 --- a/content/es/docs/zero-code/obi/setup/kubernetes.md +++ b/content/es/docs/zero-code/obi/setup/kubernetes.md @@ -463,4 +463,3 @@ env: key: otelcol-secret name: headers ``` - diff --git a/content/ja/docs/zero-code/obi/setup/kubernetes.md b/content/ja/docs/zero-code/obi/setup/kubernetes.md index 363619ad0544..3c5109c6b502 100644 --- a/content/ja/docs/zero-code/obi/setup/kubernetes.md +++ b/content/ja/docs/zero-code/obi/setup/kubernetes.md @@ -401,4 +401,3 @@ env: key: otelcol-secret name: headers ``` - From 582b6eeaa8ee2da4fa8402418031b934b42ce0e5 Mon Sep 17 00:00:00 2001 From: NimrodAvni78 Date: Tue, 26 May 2026 14:37:51 +0300 Subject: [PATCH 11/11] Remove cross-reference links to new k8s-cache sections Per review feedback, ship the new sections without the cross-page links between them so the link checker passes. The cross-references can be added in a follow-up PR once the sections exist on main. --- .../zero-code/obi/configure/metrics-traces-attributes.md | 3 --- content/en/docs/zero-code/obi/setup/kubernetes-helm.md | 4 +--- content/en/docs/zero-code/obi/setup/kubernetes.md | 6 ++---- 3 files changed, 3 insertions(+), 10 deletions(-) diff --git a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md index d53b7f516e4b..0d3fc9b90f5b 100644 --- a/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md +++ b/content/en/docs/zero-code/obi/configure/metrics-traces-attributes.md @@ -426,9 +426,6 @@ over gRPC instead of running its own informers against the Kubernetes API server. This is recommended on large clusters and DaemonSet deployments to avoid overloading the Kubernetes API. -For background and deployment instructions, see -[Centralizing Kubernetes metadata with k8s-cache](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). - ### Service name template You can template service names using Go templates. This lets you create diff --git a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md index 75ed3deb731b..813d2ddd88eb 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes-helm.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes-helm.md @@ -125,9 +125,7 @@ from each OBI pod can overload the API server and affect the whole cluster. To avoid that, the OBI Helm chart can deploy a small companion service called `k8s-cache`. The cache watches the Kubernetes API once on behalf of all OBI Pods and streams metadata to them over gRPC, which removes OBI's per-Pod informer -traffic to the API server and substantially reduces API load. For more -background on what `k8s-cache` is and when to use it, see the -[Kubernetes setup guide](/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache). +traffic to the API server and substantially reduces API load. To enable it, set `k8sCache.replicas` to a non-zero value in your `helm-obi.yml`: diff --git a/content/en/docs/zero-code/obi/setup/kubernetes.md b/content/en/docs/zero-code/obi/setup/kubernetes.md index 17faba420699..eb50143764a6 100644 --- a/content/en/docs/zero-code/obi/setup/kubernetes.md +++ b/content/en/docs/zero-code/obi/setup/kubernetes.md @@ -447,10 +447,8 @@ the standalone or Docker setups. To use the cache, deploy it and point OBI at its `Service` address with the `OTEL_EBPF_KUBE_META_CACHE_ADDRESS` environment variable (or `attributes.kubernetes.meta_cache_address` in YAML). The easiest way is to use -the -[OBI Helm chart](/docs/zero-code/obi/setup/kubernetes-helm/#centralizing-kubernetes-metadata-with-k8s-cache), -which sets up the `Deployment`, `Service`, and OBI wiring for you when you set -`k8sCache.replicas` to a non-zero value. +the OBI Helm chart, which sets up the `Deployment`, `Service`, and OBI wiring +for you when you set `k8sCache.replicas` to a non-zero value. If you prefer to deploy it manually, the cache is published as the `ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/opentelemetry-ebpf-k8s-cache`