--- title: Install OpenTelemetry Collector on Kubernetes source: https://docs.newrelic.com/docs/kubernetes-pixie/k8s-otel/install --- You can monitor your Kubernetes cluster using OpenTelemetry, which provides a standardized way to collect and send telemetry data to New Relic. This integration allows you to gain insights into your Kubernetes environment, including metrics, events, and logs. New Relic recommends using the [New Relic distribution of OpenTelemetry (NRDOT) for Kubernetes](https://github.com/newrelic/nrdot-collector-releases/tree/main/distributions/nrdot-collector-k8s). This distribution is pre-configured to work seamlessly with New Relic and includes all necessary components and configurations to effectively monitor your Kubernetes cluster. However, if you prefer to use your own OpenTelemetry Collector, you can do so by ensuring it includes the required components for Kubernetes monitoring. ## Requirements [#requirements] To send Kubernetes telemetry data to New Relic, you need an OpenTelemetry Collector. Our [NRDOT](https://github.com/newrelic/nrdot-collector-releases/tree/main/distributions/nrdot-collector-k8s) is configured to automatically monitor your Kubernetes cluster. It deploys all necessary components through our [`nr-k8s-otel-collector`](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector) Helm chart. If you opt for a different OpenTelemetry Collector, ensure it includes all the key components for comprehensive Kubernetes monitoring: **Required OpenTelemetry collectors components** - [Attributes processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/attributesprocessor) - [Filter processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor) - [Filelog receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/filelogreceiver) - [GroupByAttrs processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/groupbyattrsprocessor) - [Hostmetrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver) - [K8sAttributes processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/k8sattributesprocessor) - [K8sevents receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/k8seventsreceiver) - [Kubelet receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/kubeletstatsreceiver) - [MetricsTransform processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/metricstransformprocessor) - [Prometheus receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/prometheusreceiver) - [ResourceDetection processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor) - [Resource processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourceprocessor) - [Transform processor](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor) ### Supported Environments [#supported-envs] Our OpenTelemetry monitoring for Kubernetes provides robust support across various deployment environments. Supported platforms include: - **Cloud vendors:** - Amazon EKS - Microsoft AKS - Google GKE - Oracle OKE - Red Hat OpenShift - **On-Premise clusters:** We offer support for on-premise Kubernetes clusters. - **Kubernetes versions:** Support aligns with the Kubernetes versions currently supported by each vendor, ensuring compatibility and effective monitoring solutions across these environments. > #### ⚠️ IMPORTANT > > Windows nodes are not supported. ## Install your Kubernetes cluster with OpenTelemetry [#install] You can install OpenTelemetry for Kubernetes using one of the following methods: > #### 💡 TIP > > For advanced configuration options, refer to [Advanced configuration for OpenTelemetry Kubernetes](https://docs.newrelic.com/docs/kubernetes-pixie/k8s-otel/advance-config). **Helm install** ## Helm install [#helm-install] The Helm installation method is the recommended approach for deploying OpenTelemetry on Kubernetes. This method simplifies the deployment process and allows for easy configuration management. You can use either the NRDOT or your own OpenTelemetry Collector. New Relic recommends using the NRDOT for Kubernetes, which is pre-configured to work seamlessly with New Relic. This distribution includes all necessary components and configurations to effectively monitor your Kubernetes cluster. However, if you prefer to use your own OpenTelemetry Collector, you can do so by ensuring it includes the required components for Kubernetes monitoring. **To install Helm chart:** 1. Download the [Helm chart `values.yaml` file](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector/values.yaml#L20-L24) and adapt it to meet your specific requirements. - The cluster name and license key are mandatory. - For more information, refer to [configuration parameters](#config-params). 2. Install the [Helm chart](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector) using your `values.yaml` file. ```shell helm repo add newrelic https://helm-charts.newrelic.com helm upgrade nr-k8s-otel-collector newrelic/nr-k8s-otel-collector -f your-custom-values.yaml -n newrelic --create-namespace --install ``` 3. Ensure the pods have successfully spun up. ```shell kubectl get pods -n newrelic --watch ``` You should see pods with names such as `nr-k8s-otel-collector-` in the `newrelic` namespace. 4. Verify that New Relic is receiving the necessary data, including metrics, events, and logs, by running the following queries. For more information, refer to [Introduction to the query builder](https://docs.newrelic.com/docs/query-your-data/explore-query-data/query-builder/introduction-query-builder/). ```sql FROM Metric SELECT * WHERE k8s.cluster.name='' FROM OtlpInfrastructureEvent SELECT * WHERE k8s.cluster.name='' FROM Log SELECT * WHERE k8s.cluster.name='' ``` > #### 💡 TIP > > If you want to use a different OpenTelemetry Collector to collect Kubernetes telemetry data, update the `image` settings in your `values.yaml` file to specify your desired OpenTelemetry Collector: > > ````yaml > image: > repository: otel/opentelemetry-collector-contrib # Example: Using the contrib distro > tag: "latest" # Or a specific stable version like "0.98.0" > ``` > > > ```` **Manifests install** The Manifest installation method provides a way to set up OpenTelemetry for Kubernetes without using Helm. This method is suitable for users who prefer a more hands-on approach or have specific requirements that necessitate manual configuration. **To perform a manifest installation:** 1. Copy the contents of the `nr-k8s-otel-collector`'s [rendered examples directory](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector/examples/k8s/rendered) to your local workspace. This directory contains the Kubernetes manifest files. 2. Update the [`secret.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-k8s-otel-collector/examples/k8s/rendered/secret.yaml) file in your local `rendered` directory. Replace `` with your New Relic License Key, encoded in Base64. ```yaml data: licenseKey: ``` To `Base64` encode your license key: - **Linux/macOS:** Use `echo -n "YOUR_LICENSE_KEY" | base64`. - **Windows (PowerShell):** Use `[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes("YOUR_LICENSE_KEY"))`. 3. Manually update your cluster name in both [`daemonset-configmap.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-k8s-otel-collector/examples/k8s/rendered/daemonset-configmap.yaml) and [`deployment-configmap.yaml`](https://github.com/newrelic/helm-charts/blob/master/charts/nr-k8s-otel-collector/examples/k8s/rendered/deployment-configmap.yaml) files within your local `rendered` directory. Locate instances of `k8s.cluster.name` and replace `` with the desired name for your cluster. ```yaml - key: k8s.cluster.name action: upsert value: ``` 4. After updating these required fields, create the `newrelic` namespace and deploy the manifests to your cluster using `kubectl`. ```bash kubectl create namespace newrelic kubectl apply -n newrelic -R -f rendered ``` > #### 💡 TIP > > When deploying without Helm, components deployed via the rendered manifests might include a prefix, such as `example-`. This prefix is typically used in Helm chart templates for dynamic naming based on the Helm release name. If you prefer cleaner naming conventions, you can adjust these prefixes directly in the manifest files before applying them. ## Configuration parameters in `values.yaml` [#config-params] The `values.yaml` file in the [`nr-k8s-otel-collector`](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector) Helm chart repository contains all the configuration parameters you can use to customize your OpenTelemetry Collector deployment. This file allows you to set various options, such as cluster name, license key, and other collector settings. **Configuration parameters** | Parameter Name | Data Type | Description | Example Value | | --------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kube-state-metrics.enabled` | Boolean | Specifies whether to install the [`kube-state-metrics` Helm chart](https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-state-metrics). This parameter is mandatory if `infrastructure.enabled` is set to `true` and you do not provide your own instance of Kube State Metrics (KSM) version 1.8 or later. KSM versions 2.0 and above disable labels and annotations metrics by default; you can enable these by using the `metricLabelsAllowlist` or `metricAnnotationsAllowList` options in your KSM configuration. | `true` | | `kube-state-metrics.prometheusScrape` | Boolean | Disables Prometheus from automatically discovering KSM endpoints. This prevents potential duplication of scraped data if KSM is already being monitored by another Prometheus instance. | `false` | | `provider` | String | Specifies the cloud vendor or environment where your Kubernetes cluster is deployed. This parameter sets known configuration constraints specific to your provider. Currently, supported values are `"GKE_AUTOPILOT"` for Google Kubernetes Engine Autopilot clusters and `"OPEN_SHIFT"` for Red Hat OpenShift. | `"GKE_AUTOPILOT"` | | `image.repository` | String | Defines the Docker image repository for the OpenTelemetry Collector. You can specify your own collector image, provided it meets the necessary requirements for Kubernetes monitoring. | `"newrelic/nrdot-collector-k8s"` | | `image.pullPolicy` | String | Determines the image pull policy. The default is `IfNotPresent`, which skips pulling an image if it already exists locally. If this parameter is defined without a specific value, it defaults to `Always`. | `"IfNotPresent"` | | `image.tag` | String | Overrides the default image tag. By default, the tag is set to the chart's `appVersion`. Use this parameter to specify a particular version of the collector image. | `"1.1.0"` | | `cluster` | String | Defines the name of the Kubernetes cluster being monitored. This is a mandatory parameter. You can also configure it using `global.cluster`. | `"my-eks-cluster"` | | `licenseKey` | String | Specifies your New Relic License Key for authentication. This is a mandatory parameter. You can also configure it using `global.licenseKey`. | `"NRAL-ABCDEFGHIJKLMN"` | | `customSecretName` | String | Specifies the name of a user-created Kubernetes Secret that holds the New Relic License Key. Use this option if you prefer not to include the license key directly in your `values.yaml` file. You can also configure it using `global.customSecretName`. | `"my-nr-license-secret"` | | `customSecretLicenseKey` | String | Specifies the key within the Kubernetes Secret (defined by `customSecretName`) where the license key is located. Use this option when obtaining the license key from a Secret. You can also configure it using `global.customSecretLicenseKey`. | `"licenseKey"` | | `proxy` | String | Configures the OpenTelemetry Collector instances (both Daemonset and Deployment) to send all telemetry data through the specified HTTP/HTTPS proxy. | `"http://your-proxy.example.com:3128"` | | `podLabels` | Map (key-value) | Specifies additional labels to be added to all chart pods. These labels can be used for organizing and selecting Kubernetes resources. | `{app.kubernetes.io/component: "otel-collector"}` | | `labels` | Map (key-value) | Specifies additional labels to be added to all Kubernetes objects created by the chart. These labels apply broadly to deployments, services, and other resources. | `{environment: "production"}` | | `priorityClassName` | String | Sets the `priorityClassName` for all pods deployed by the chart. This controls the scheduling priority of the pods. You can also configure it using `global.priorityClassName`. | `"system-cluster-critical"` | | `dnsConfig` | Map (key-value) | Sets the `dnsConfig` for all pods deployed by the chart. This allows for custom DNS settings for the pods. You can also configure it using `global.dnsConfig`. | `{nameservers: ["8.8.8.8"]}` | | `daemonset.nodeSelector` | Map (key-value) | Sets the node selector for Daemonset pods, controlling which nodes they are scheduled on. This parameter overrides global node selectors. | `{kubernetes.io/os: "linux"}` | | `daemonset.tolerations` | List | Specifies tolerations for Daemonset pods, allowing them to be scheduled on nodes with matching taints. This parameter overrides global tolerations. | `[{key: "node-role.kubernetes.io/master", effect: "NoSchedule"}]` | | `daemonset.affinity` | Map (key-value) | Configures affinities for Daemonset pods, influencing their scheduling based on node or pod labels. This parameter overrides global affinities. | `{nodeAffinity: {requiredDuringSchedulingIgnoredDuringExecution: {nodeSelectorTerms: [{matchExpressions: [{key: "disktype", operator: "In", values: ["ssd"]}]}]}}}` | | `daemonset.podAnnotations` | Map (key-value) | Specifies additional annotations to be added to the Daemonset pods. | `{prometheus.io/scrape: "true"}` | | `daemonset.podSecurityContext` | Map (key-value) | Sets the security context at the pod level for the Daemonset. This parameter overrides global pod security contexts. | `{runAsUser: 1000}` | | `daemonset.containerSecurityContext` | Map (key-value) | Sets the security context at the container level for the Daemonset. This parameter overrides global container security contexts. This chart defaults to `privileged: false`. | `{privileged: false}` | | `daemonset.resources` | Map (key-value) | Defines the compute resources (CPU and memory requests and limits) for the Daemonset containers. | `{limits: {cpu: "500m", memory: "512Mi"}, requests: {cpu: "200m", memory: "256Mi"}}` | | `daemonset.envs` | List | Specifies additional environment variables to be set for the Daemonset containers. | `[{name: "DEBUG_MODE", value: "true"}]` | | `daemonset.envsFrom` | List | Specifies additional environment variable sources for the Daemonset containers, typically from Secrets or ConfigMaps. | `[{secretRef: {name: "my-daemonset-secret"}}]` | | `daemonset.configMap.overrideConfig` | Map (key-value) | Provides a complete OpenTelemetry configuration for the Daemonset. If set, this parameter overrides the default configuration and disables other configuration parameters specific to the Daemonset. | `receivers: {hostmetrics: {collection_interval: 30s}}` | | `daemonset.configMap.extraConfig` | Map (key-value) | Specifies additional OpenTelemetry configuration for the Daemonset. If set, this parameter extends the default configuration by adding more receivers, processors, exporters, connectors, or pipelines. | `receivers: {custom_receiver: {}}` | | `deployment.nodeSelector` | Map (key-value) | Sets the node selector for Deployment pods, controlling which nodes they are scheduled on. This parameter overrides global node selectors. | `{kubernetes.io/hostname: "control-plane-node"}` | | `deployment.tolerations` | List | Specifies tolerations for Deployment pods, allowing them to be scheduled on nodes with matching taints. This parameter overrides global tolerations. | `[{key: "CriticalAddonsOnly", operator: "Exists"}]` | | `deployment.affinity` | Map (key-value) | Configures affinities for Deployment pods, influencing their scheduling based on node or pod labels. This parameter overrides global affinities. | `{podAntiAffinity: {requiredDuringSchedulingIgnoredDuringExecution: [{labelSelector: {matchLabels: {app: "my-app"}}, topologyKey: "kubernetes.io/hostname"}]}}` | | `deployment.podAnnotations` | Map (key-value) | Specifies additional annotations to be added to the Deployment pods. | `{sidecar.istio.io/inject: "false"}` | | `deployment.podSecurityContext` | Map (key-value) | Sets the security context at the pod level for the Deployment. This parameter overrides global pod security contexts. | `{fsGroup: 2000}` | | `deployment.containerSecurityContext` | Map (key-value) | Sets the security context at the container level for the Deployment. This parameter overrides global container security contexts. | `{runAsNonRoot: true}` | | `deployment.resources` | Map (key-value) | Defines the compute resources (CPU and memory requests and limits) for the Deployment containers. | `{limits: {cpu: "200m", memory: "256Mi"}, requests: {cpu: "100m", memory: "128Mi"}}` | | `deployment.envs` | List | Specifies additional environment variables to be set for the Deployment containers. | `[{name: "ENV_VAR", value: "some_value"}]` | | `deployment.envsFrom` | List | Specifies additional environment variable sources for the Deployment containers, typically from Secrets or ConfigMaps. | `[{configMapRef: {name: "my-deployment-config"}}]` | | `deployment.configMap.overrideConfig` | Map (key-value) | Provides a complete OpenTelemetry configuration for the Deployment. If set, this parameter overrides the default configuration and disables other configuration parameters specific to the Deployment. | `receivers: {k8s_events: {collection_interval: 5s}}` | | `deployment.configMap.extraConfig` | Map (key-value) | Specifies additional OpenTelemetry configuration for the Deployment. If set, this parameter extends the default configuration by adding more receivers, processors, exporters, connectors, or pipelines. | `exporters: {log: {verbosity: "detailed"}}` | | `nodeSelector` | Map (key-value) | Sets the node selector for all pods deployed by the chart, affecting both Daemonset and Deployment. This parameter can also be configured using `global.nodeSelector`. | `{disktype: "ssd"}` | | `tolerations` | List | Sets tolerations for all pods deployed by the chart, allowing them to be scheduled on nodes with matching taints. This parameter can also be configured using `global.tolerations`. | `[{key: "taint-key", operator: "Exists", effect: "NoSchedule"}]` | | `affinity` | Map (key-value) | Configures affinities for all pods deployed by the chart, influencing their scheduling based on node or pod labels. This parameter can also be configured using `global.affinity`. | `{podAffinity: {requiredDuringSchedulingIgnoredDuringExecution: [{labelSelector: {matchLabels: {app: "otel-collector"}}, topologyKey: "kubernetes.io/hostname"}]}}` | | `podSecurityContext` | Map (key-value) | Sets the security context at the pod level for all pods deployed by the chart. This parameter can also be configured using `global.securityContext.pod`. | `{runAsGroup: 3000}` | | `containerSecurityContext` | Map (key-value) | Sets the security context at the container level for all containers in pods deployed by the chart. This parameter can also be configured using `global.securityContext.container`. | `{allowPrivilegeEscalation: false}` | | `rbac.create` | Boolean | Specifies whether Role-Based Access Control (RBAC) resources, such as Service Accounts, Roles, and RoleBindings, should be created by the Helm chart. | `true` or `false` | | `serviceAccount.create` | Boolean | Specifies whether a Kubernetes ServiceAccount should be created for the collector pods. If set to `true` and `serviceAccount.name` is not specified, a name is generated using the full name template. | `true` or `false` | | `serviceAccount.name` | String | Specifies a custom name for the ServiceAccount. If not set and `serviceAccount.create` is `true`, the chart generates a name. | `"my-otel-sa"` | | `serviceAccount.annotations` | Map (key-value) | Specifies any additional annotations to add to the created ServiceAccount. | `{eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/MyEKSFargateRole"}` | | `verboseLog` | Boolean | Enables debug-level logging for this integration. If set globally (using `global.verboseLog`), it enables debug logs for all integrations. | `true` or `false` | | `nrStaging` | Boolean | Directs the collector to send all data to the New Relic staging backend. This option requires a valid staging license key. This parameter can also be configured using `global.nrStaging`. | `true` or `false` | | `receivers.prometheus.enabled` | Boolean | Specifies whether the `prometheus` receiver is enabled for data collection. | `true` or `false` | | `receivers.prometheus.scrapeInterval` | String | Sets the scrape interval for the `prometheus` receiver, determining how frequently metrics are collected. | `1m` | | `receivers.k8sEvents.enabled` | Boolean | Specifies whether the `k8sEvents` receiver is enabled for collecting Kubernetes events. | `true` or `false` | | `receivers.hostmetrics.enabled` | Boolean | Specifies whether the `hostmetrics` receiver is enabled for collecting host-level metrics. | `true` or `false` | | `receivers.hostmetrics.scrapeInterval` | String | Sets the scrape interval for the `hostmetrics` receiver. | `1m` | | `receivers.kubeletstats.enabled` | Boolean | Specifies whether the `kubeletstats` receiver is enabled for collecting metrics from the Kubelet. | `true` or `false` | | `receivers.kubeletstats.scrapeInterval` | String | Sets the scrape interval for the `kubeletstats` receiver. | `1m` | | `receivers.filelog.enabled` | Boolean | Specifies whether the `filelog` receiver is enabled for collecting logs from files, typically container logs. | `true` or `false` | | `lowDataMode` | Boolean | Enables a mode that sends only the essential metrics required to illuminate the New Relic Kubernetes user interface. This helps reduce data ingestion volume. | `true` or `false` | ## Alerts [#alerts] You can install essential alert policies by going through the guided installation flow in Integrations & Agents. This automatically sets up alert policy named **Kubernetes (OpenTelemetry) alert policy** in your New Relic account with multiple alert conditions designed for Kubernetes observability. Customize these conditions to suit your specific monitoring needs. ![Kubernetes OpenTelemetry alert policy](https://docs.newrelic.com/images/alert-k8s-policy.webp "Kubernetes OpenTelemetry alert policy") ## Find and use data [#find] Check out these documents to learn more on how to find data: - [Explore your Kubernetes cluster](https://docs.newrelic.com/docs/kubernetes-pixie/kubernetes-integration/understand-use-data/kubernetes-cluster-explorer/) to know the status of your cluster, from the control plane to nodes and pods. - [Kubernetes APM summary page](https://docs.newrelic.com/docs/apm/apm-ui-pages/monitoring/kubernetes-summary-page/) which offers insights into your Kubernetes integration alongside your monitored applications. ## Metrics [#metrics] - The `LowDataMode` is the default mode. To view the full list of metrics refer to [`LowDataMode` list](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector/docs/metrics-lowDataMode.md). - [Metrics - Full list](https://github.com/newrelic/helm-charts/tree/master/charts/nr-k8s-otel-collector/docs/metrics-full.md) ## Uninstall [#uninstall] ### Helm uninstall [#helm-uninstall] To stop monitoring a Kubernetes cluster with OpenTelemetry, run this command: ```shell helm uninstall nr-k8s-otel-collector -n newrelic ``` ### Manifests uninstall [#manifests-uninstall] To stop monitoring a Kubernetes cluster with OpenTelemetry, run this command: ```shell kubectl delete -R -f rendered kubectl delete namespaces newrelic ``` ## Support [#support] If you have issues with the OpenTelemetry observability for Kubernetes, refer to: - [Troubleshooting guide](https://docs.newrelic.com/docs/kubernetes-pixie/k8s-otel/troubleshooting/) - [Issues section on GitHub](https://github.com/newrelic/helm-charts/issues) for any similar problems or consider opening a new issue. ## Related articles [#related-docs] [Advanced configuration for OpenTelemetry Kubernetes](https://docs.newrelic.com/docs/kubernetes-pixie/k8s-otel/advance-config/) Customize your OpenTelemetry Collector configuration for Kubernetes in New Relic. [Troubleshooting OpenTelemetry for Kubernetes](https://docs.newrelic.com/docs/kubernetes-pixie/k8s-otel/troubleshooting/) Learn how to troubleshoot issues with the OpenTelemetry Collector in Kubernetes.