Clarify and share Kubernetes OpenTelemetry setup

hugo/config/_default/menus/main.en.yaml

@@ -3392,76 +3392,81 @@ menu:
       parent: containers_kubernetes
       identifier: containers_kubernetes_installation
       weight: 401
+    - name: OpenTelemetry
+      url: containers/kubernetes/opentelemetry/
+      parent: containers_kubernetes
+      identifier: containers_kubernetes_opentelemetry
+      weight: 402
     - name: Migrate to the Datadog Operator
       url: containers/kubernetes/migration
       parent: containers_kubernetes
       identifier: containers_kubernetes_datadog_operator_migration
-      weight: 402
+      weight: 403
     - name: Further Configuration
       url: containers/kubernetes/configuration
       parent: containers_kubernetes
       identifier: containers_kubernetes_configuration
-      weight: 403
+      weight: 404
     - name: Distributions
       url: containers/kubernetes/distributions
       parent: containers_kubernetes
       identifier: containers_kubernetes_distributions
-      weight: 404
+      weight: 405
     - name: APM
       url: containers/kubernetes/apm/
       parent: containers_kubernetes
       identifier: containers_kubernetes_apm
-      weight: 405
+      weight: 406
     - name: App and API Protection
       url: containers/kubernetes/appsec/
       parent: containers_kubernetes
       identifier: containers_kubernetes_appsec
-      weight: 406
+      weight: 407
     - name: Log collection
       url: containers/kubernetes/log/
       parent: containers_kubernetes
       identifier: containers_kubernetes_log
-      weight: 407
+      weight: 408
     - name: Tag extraction
       url: containers/kubernetes/tag/
       parent: containers_kubernetes
       identifier: containers_kubernetes_tag
-      weight: 408
+      weight: 409
     - name: Integrations
       url: containers/kubernetes/integrations/
       parent: containers_kubernetes
       identifier: containers_kubernetes_integrations
-      weight: 409
+      weight: 410
     - name: Prometheus & OpenMetrics
       url: containers/kubernetes/prometheus/
       parent: containers_kubernetes
       identifier: containers_kubernetes_prometheus
-      weight: 410
+      weight: 411
     - name: Control plane monitoring
       url: containers/kubernetes/control_plane/
       parent: containers_kubernetes
       identifier: containers_kubernetes_control_plane
-      weight: 411
+      weight: 412
     - name: Data collected
       url: containers/kubernetes/data_collected/
       parent: containers_kubernetes
       identifier: containers_kubernetes_data_collected
-      weight: 412
+      weight: 413
     - name: kubectl Plugin
       url: containers/kubernetes/kubectl_plugin
       parent: containers_kubernetes
       identifier: containers_kubernetes_kubectlplugin
-      weight: 413
+      weight: 414
     - name: Datadog CSI Driver
       url: containers/kubernetes/csi_driver
       parent: containers_kubernetes
       identifier: csi_driver
-      weight: 414
+      weight: 415
     - name: Data security
       url: data_security/kubernetes
       parent: containers_kubernetes
       identifier: container_kubernetes_data_security
-      weight: 415
+      weight: 416
     - name: Cluster Agent
       url: containers/cluster_agent/
       parent: containers

hugo/content/en/containers/kubernetes/_index.md

@@ -1,6 +1,6 @@
 ---
 title: Kubernetes
-description: Install and configure the Datadog Agent on Kubernetes 
+description: Monitor Kubernetes with the Datadog Agent or OpenTelemetry.
 aliases:
     - /guides/basic_agent_usage/kubernetes
     - /agent/basic_agent_usage/kubernetes
@@ -41,6 +41,8 @@ further_reading:
   This foundation enablement session will focus on how Datadog can monitor Kubernetes. Learn how to configure Datadog for Kubernetes and how to get started. Explore the various views and tools Datadog offers to visualize and analyze your cluster and application metrics, traces, and logs.
 {{< /learning-center-callout >}}
 
+To collect Kubernetes infrastructure metrics with OpenTelemetry instead of the Datadog Agent, see [Kubernetes Metrics with OpenTelemetry][10].
+
 ## Agent installation
 
 You can install the Agent using either the [Datadog Operator][4] or Helm chart by following the [in-app installation guide in Fleet Automation][5]. This guided interface allows you to:
@@ -97,3 +99,4 @@ For Agent commands, see the [Agent Commands guides][9]. For information on the D
 [7]: /containers/kubernetes/installation
 [8]: https://docs.datadoghq.com/containers/guide/kubernetes_daemonset/
 [9]: /agent/configuration/agent-commands/
+[10]: /containers/kubernetes/opentelemetry/

hugo/content/en/containers/kubernetes/opentelemetry.md

@@ -0,0 +1,9 @@
+---
+title: Kubernetes Metrics with OpenTelemetry
+description: Set up OpenTelemetry Collectors for Kubernetes infrastructure metrics and Kubernetes Explorer.
+dependencies:
+- https://github.com/DataDog/documentation/blob/master/hugo/content/en/opentelemetry/integrations/kubernetes_metrics.md
+---
+
+<!-- Edit the shared guide in opentelemetry/integrations/kubernetes_metrics.md. -->
+{{< include-markdown "opentelemetry/integrations/kubernetes_metrics" >}}

hugo/content/en/containers/monitoring/kubernetes_explorer.md

@@ -80,6 +80,8 @@ For manual setup, see [Set up Kubernetes Explorer with a DaemonSet][1].
 
 You can populate the Kubernetes Explorer using a native OpenTelemetry pipeline instead of the Datadog Agent. This setup uses the [`k8sobjects`][1] receiver to collect Kubernetes resource data and forwards it through the [Datadog Exporter's][2] orchestrator explorer functionality.
 
+The following steps enable Explorer's resource views without collecting the metrics used by related dashboards. To collect those metrics and populate Explorer, follow [Kubernetes Metrics with OpenTelemetry][6] instead.
+
 {{< site-region region="gov,gov2" >}}<div class="alert alert-warning">This feature is not available for {{< region-param key="dd_site_name" >}}.</div>{{< /site-region >}}
 
 #### Prerequisites
@@ -96,24 +98,22 @@ Recommendations:
 - Use Kubernetes 1.33 or later, which includes [streaming list improvements][5] that reduce API server impact.
 - Start with smaller clusters. Limit the number of objects per resource type to fewer than 5,000 as a starting point, and scale up gradually while monitoring cluster health.
 
-The following steps walk through the required components for Kubernetes Explorer. For a complete reference example that also collects Kubernetes infrastructure metrics, see [Kubernetes Metrics][6].
-
 #### 1. Create a Datadog API key secret
 
-Create a Kubernetes secret to store your Datadog API key:
+Create a Kubernetes secret to store your Datadog API key. These steps use the `default` namespace for both the secret and the Collector:
 
 ```sh
 export DD_API_KEY="<YOUR_DATADOG_API_KEY>"
-kubectl create secret generic datadog-secret --from-literal api-key=$DD_API_KEY
+kubectl create secret generic datadog-secret \
+  --namespace default \
+  --from-literal="api-key=$DD_API_KEY"
 ```
 
 #### 2. Configure the cluster collector
 
-This setup deploys the OTel Collector as a Kubernetes Deployment. Create a `deployment-collector.yaml` file with the following configuration blocks, or merge them into your existing OpenTelemetry Collector values file.
-
-##### Collector image and mode
+Create `deployment-collector.yaml` with the following complete Helm values. Replace `<YOUR_DATADOG_SITE>` with your [Datadog site][7] and `<YOUR_CLUSTER_NAME>` with your cluster name.
 
-Set the Collector to run as a single-replica Deployment using the Contrib distribution:
+This configuration runs one Collector as a Deployment. It sets the cluster name explicitly, so cloud-provider detection is not required.
 
 ```yaml
 mode: deployment
@@ -130,13 +130,7 @@ extraEnvs:
       secretKeyRef:
         name: datadog-secret
         key: api-key
-```
-
-##### Kubernetes objects collection
-
-The `kubernetesObjects` [preset][4] automatically provisions the service account, RBAC permissions, and `k8sobjects` receiver defaults required to populate Kubernetes Explorer. Override the receiver `interval` to `3m`, which is required for Kubernetes Explorer:
 
-```yaml
 presets:
   kubernetesObjects:
     enabled: true
@@ -146,79 +140,41 @@ config:
   receivers:
     k8sobjects:
       interval: 3m
-```
-
-##### Datadog exporter
 
-Enable the `orchestrator_explorer` option in the Datadog Exporter. This is the setting that sends Kubernetes object data to the Explorer. Replace `<YOUR_DATADOG_SITE>` with your [Datadog site][7]:
+  processors:
+    resourcedetection:
+      detectors: [k8s_api]
+      override: false
+    resource/add-cluster-name:
+      attributes:
+        - key: k8s.cluster.name
+          value: "<YOUR_CLUSTER_NAME>"
+          action: upsert
 
-```yaml
-config:
   exporters:
     datadog:
       api:
-        site: <YOUR_DATADOG_SITE>
+        site: "<YOUR_DATADOG_SITE>"
         key: ${env:DD_API_KEY}
       orchestrator_explorer:
         enabled: true
-```
-
-##### Processors and pipeline
-
-Add a [`resourcedetection`][8] processor to detect the cluster UID and name.
-
-- The `k8s_api` detector is required to detect the cluster UID (`k8s.cluster.uid`).
-- Cluster name detection depends on your cloud provider. Check the [`resourcedetection` processor documentation][8] for supported providers (EKS, AKS, GCP) and required permissions.
-- If your provider is not supported, use a `resource/add-cluster-name` processor to set the cluster name manually. Replace `<YOUR_CLUSTER_NAME>` with your cluster name.
-
-Then connect the components in a `logs` pipeline.
-
-The following examples show two approaches. Use the cloud provider example if you run on EKS, AKS, or GCP. Use the manual fallback if your provider is not supported.
-
-**Cloud provider detection (EKS example):**
-
-```yaml
-  processors:
-    resourcedetection:
-      detectors: [k8s_api, eks]
-      override: false
-      eks:
-        resource_attributes:
-          k8s.cluster.name:
-            enabled: true
 
   service:
     pipelines:
       logs:
         receivers: [k8sobjects]
-        processors: [resourcedetection]
+        processors: [resourcedetection, resource/add-cluster-name]
         exporters: [datadog]
 ```
 
-Replace `eks` with your provider's detector (`aks`, `gcp`). See the [`resourcedetection` processor documentation][8] for provider-specific configuration.
+The `kubernetesObjects` preset configures the receiver, service account, and RBAC permissions. Keep the `3m` collection interval and the `k8s_api` detector, which identifies the cluster UID. The `logs` pipeline sends Kubernetes resource objects to Explorer; it does not collect application logs.
 
-**Manual fallback:**
+##### Automatic cluster name detection (optional)
 
-If the `resourcedetection` processor does not support your cloud provider, set the cluster name manually. Replace `<YOUR_CLUSTER_NAME>` with your cluster name:
+If you prefer automatic cluster name detection, make these changes in `deployment-collector.yaml` before deploying:
 
-```yaml
-  processors:
-    resourcedetection:
-      detectors: [k8s_api]
-      override: false
-    resource/add-cluster-name:
-      attributes:
-        - key: k8s.cluster.name
-          value: <YOUR_CLUSTER_NAME>
-          action: upsert
-
-  service:
-    pipelines:
-      logs:
-        receivers: [k8sobjects]
-        processors: [resourcedetection, resource/add-cluster-name]
-        exporters: [datadog]
-```
+1. Add your provider's detector to `resourcedetection.detectors`, keeping `k8s_api`. Follow the configuration and permissions guidance for [EKS][12], [AKS][13], or [GKE][14], including enabling the `k8s.cluster.name` resource attribute.
+2. Remove `resource/add-cluster-name` from both `config.processors` and the `logs` pipeline's `processors` list.
 
 #### 3. Deploy with Helm
 
@@ -229,6 +185,7 @@ helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm
 helm repo update
 
 helm install deployment-collector open-telemetry/opentelemetry-collector \
+  --namespace default \
   --values ./deployment-collector.yaml
 ```
 
@@ -238,7 +195,9 @@ Open the [Kubernetes Explorer][9] and filter by your OpenTelemetry cluster name.
 
 #### 5. Correlate logs, metrics, and traces with Kubernetes Explorer (optional)
 
-To navigate between Kubernetes resources and their related logs, metrics, and traces, add the [`k8sattributes`][10] and [`resourcedetection`][8] processors to your existing collector pipelines. For `resourcedetection` configuration, see [Processors and pipeline](#processors-and-pipeline) above.
+This step applies to Collectors that receive application telemetry, not the Explorer-only Collector above. To correlate that telemetry with Kubernetes resources, add the [`k8sattributes`][10] and [`resourcedetection`][8] processors to those Collectors' pipelines. Use the same cluster name as the Explorer Collector.
+
+The following fragment shows the processor configuration. Keep the existing receivers, exporters, and processors in your application-telemetry pipelines; replace `...` with the other processors in each pipeline.
 
 ```yaml
 processors:
@@ -282,19 +241,22 @@ service:
       processors: [k8sattributes, resourcedetection, ...]
 ```
 
-For a complete reference example, see the [DaemonSet collector configuration][11].
+For a complete application-telemetry Collector example, see the [DaemonSet collector configuration][11].
 
 [1]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8sobjectsreceiver
 [2]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/exporter/datadogexporter
 [3]: https://github.com/open-telemetry/opentelemetry-collector-contrib/releases/tag/v0.154.0
 [4]: https://github.com/open-telemetry/opentelemetry-helm-charts/tree/opentelemetry-collector-0.156.2/charts/opentelemetry-collector
 [5]: https://kubernetes.io/blog/2025/05/09/kubernetes-v1-33-streaming-list-responses/
-[6]: /opentelemetry/integrations/kubernetes_metrics/#setup
+[6]: /containers/kubernetes/opentelemetry/#setup
 [7]: /getting_started/site/
 [8]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor
 [9]: https://app.datadoghq.com/orchestration/overview
 [10]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor
 [11]: https://github.com/DataDog/opentelemetry-examples/blob/main/guides/kubernetes/configuration/daemonset-collector.yaml
+[12]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#amazon-eks
+[13]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#azure-aks
+[14]: https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#gcp-metadata
 
 {{% /tab %}}
 {{% tab "OpenTelemetry Kube Stack" %}}