Document k8s cache (#2177)

* Document k8s cache

* bump chart + generate examples

* disclaimer on obi kubernetes api access

Author: NimrodAvni78

charts/opentelemetry-ebpf-instrumentation/Chart.yaml

@@ -1,7 +1,7 @@
 ---
 apiVersion: v2
 name: opentelemetry-ebpf-instrumentation
-version: 0.8.0
+version: 0.8.1
 description: OpenTelemetry eBPF instrumentation Helm chart for Kubernetes
 type: application
 home: https://opentelemetry.io/

charts/opentelemetry-ebpf-instrumentation/README.md

@@ -95,6 +95,45 @@ podAnnotations:
 This requires bundling the `ConfigMap` definition in the Helm release for
 checksum evaluation.
 
+### Centralizing Kubernetes metadata with `k8s-cache`
+
+By default each OBI Pod opens its own `list`/`watch` connections to the
+Kubernetes API server to read Pod, Node, and Service metadata for the entire
+cluster (needed to enrich destination/peer attributes on traces, flows and
+metrics). On large clusters, or when many OBI replicas run side by side
+(`DaemonSet`, large `Deployment`, sidecars), this fan-out can put significant
+load on the API server.
+
+`k8s-cache` is an optional companion `Deployment` shipped with OBI. It runs
+the Kubernetes informers once on behalf of every OBI Pod and streams the
+metadata back over gRPC, so OBI Pods no longer hit the API server for
+informer traffic.
+
+> **Note:** Even when `k8s-cache` is enabled, OBI Pods still need their own
+> `ServiceAccount` and may perform limited direct Kubernetes API lookups for
+> node and cluster metadata. The cache eliminates the per-Pod informer
+> watch traffic, not all API access.
+
+The cache is disabled by default. To enable it, set `k8sCache.replicas` to a
+non-zero value:
+
+```yaml
+k8sCache:
+  replicas: 1
+```
+
+A single replica is usually enough. For high availability or very large
+clusters, increase the replica count — OBI Pods load-balance across them
+through the cache `Service` and reconnect to a healthy replica on failure.
+
+When `k8sCache.replicas > 0` the chart deploys the cache `Deployment` and
+`Service`, and automatically points the OBI `DaemonSet` at it by setting
+`OTEL_EBPF_KUBE_META_CACHE_ADDRESS` to `<k8sCache.service.name>:<k8sCache.service.port>`.
+See the `k8sCache` block in [values.yaml](./values.yaml) for image, resource,
+and metrics settings, and the
+[OBI Kubernetes setup guide](https://opentelemetry.io/docs/zero-code/obi/setup/kubernetes/#centralizing-kubernetes-metadata-with-k8s-cache)
+for background.
+
 ### Pod Annotations with Template Support
 
 The `podAnnotations` values support Helm templating, enabling dynamic values:

charts/opentelemetry-ebpf-instrumentation/examples/default/rendered/clusterrole.yaml

@@ -5,7 +5,7 @@ kind: ClusterRole
 metadata:
   name: example-opentelemetry-ebpf-instrumentation
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/default/rendered/clusterrolebinding.yaml

@@ -5,7 +5,7 @@ kind: ClusterRoleBinding
 metadata:
   name: example-opentelemetry-ebpf-instrumentation
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/default/rendered/configmap.yaml

@@ -6,7 +6,7 @@ metadata:
   name: example-opentelemetry-ebpf-instrumentation
   namespace: default
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/default/rendered/daemonset.yaml

@@ -6,7 +6,7 @@ metadata:
   name: example-opentelemetry-ebpf-instrumentation
   namespace: default
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"
@@ -23,10 +23,10 @@ spec:
   template:
     metadata:
       annotations:
-        checksum/config: 2f8c668f767b5920a9572351969fb1d67d2dd03d1b8e048e959b66e234ffabf6
+        checksum/config: bffeb93bcea4aec5857780862be8b5b7784d83b01e62540bc7a25bd8dc128cc0
 
       labels:
-        helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+        helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
         app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
         app.kubernetes.io/instance: example
         app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/default/rendered/serviceaccount.yaml

@@ -6,7 +6,7 @@ metadata:
   name: example-opentelemetry-ebpf-instrumentation
   namespace: default
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/with-k8s-cache/rendered/cache-deployment.yaml

@@ -6,7 +6,7 @@ metadata:
   name: opentelemetry-ebpf-instrumentation-k8s-cache
   namespace: default
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation-k8s-cache
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"
@@ -21,7 +21,7 @@ spec:
   template:
     metadata:
       labels:
-        helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+        helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
         app.kubernetes.io/name: opentelemetry-ebpf-instrumentation-k8s-cache
         app.kubernetes.io/instance: example
         app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/with-k8s-cache/rendered/cache-service.yaml

@@ -6,7 +6,7 @@ metadata:
   name: opentelemetry-ebpf-instrumentation-k8s-cache
   namespace: default
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation-k8s-cache
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"

charts/opentelemetry-ebpf-instrumentation/examples/with-k8s-cache/rendered/clusterrole.yaml

@@ -5,7 +5,7 @@ kind: ClusterRole
 metadata:
   name: example-opentelemetry-ebpf-instrumentation
   labels:
-    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.0
+    helm.sh/chart: opentelemetry-ebpf-instrumentation-0.8.1
     app.kubernetes.io/name: opentelemetry-ebpf-instrumentation
     app.kubernetes.io/instance: example
     app.kubernetes.io/version: "v0.8.0"