The New Relic Kubernetes integration gives you full observability into the health and performance of your environment by leveraging the New Relic infrastructure agent. This agent collects telemetry data from your cluster using several New Relic integrations such as the Kubernetes events integration, the Prometheus Agent, and the New Relic Logs Kubernetes plugin.

Why use the guided install?

To install our Kubernetes integration, we recommend that you follow the instructions here for our guided install. We recommend this interactive installation tool for servers, VMs, and unprivileged environments. Here are some advantages of using the guided install:

It can provide either a Helm command with the required values filled, or a plain manifest if you don't want to use Helm.
It gives you control over which features are enabled and which data is collected.
It also offers a quickstart option that includes some optional, pre-built resources such as dashboards and alerts alongside the Kubernetes integration so that you can gain instant visibility into your Kubernetes clusters.

Tip

For some environments, you may need (or prefer) to do a manual install instead of the guided install. We have docs for the following: Manual install with Helm, Windows, and EKS Fargate.

Preliminary notes for your managed services or platforms

Before starting our guided install, check out these notes for your managed services or platforms:

The Kubernetes integration only monitors worker nodes in GKE as Google abstracts the management of master nodes away from the Kubernetes platform.

Before starting our guided install to deploy the Kubernetes integration on GKE, ensure you have sufficient permissions:

Go to console.cloud.google.com/iam-admin/iam and find your username.
Click edit.
Ensure you have permissions to create Roles and ClusterRoles: If you're not sure, add the Kubernetes Engine Cluster Admin role. If you cannot edit your user role, ask the owner of the GCP project to give you the necessary permissions.

To deploy the Kubernetes integration with OpenShift:

Add the service accounts used by the integration to your privileged Security Context Constraints:
```
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-newrelic-infrastructure
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-newrelic-infrastructure-controlplane
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-kube-state-metrics
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-newrelic-logging
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-nri-kube-events
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-nri-metadata-injection-admission
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:<release_name>-nrk8s-controlplane
oc adm policy add-scc-to-user privileged system:serviceaccount:<namespace>:default
```
Tip
The installer provides newrelic-bundle as default release_name and newrelic as default namespace.
Complete the steps in our guided install.
If you're using signed certificates, make sure they are properly configured by using the following variables in the DaemonSet portion of your manifest. Set the .pem file:
```
env:
  - name: NRIA_CA_BUNDLE_DIR
    value: YOUR_CA_BUNDLE_DIR
  - name: NRIA_CA_BUNDLE_FILE
    value: YOUR_CA_BUNDLE_NAME
```
Set your YAML key path to spec.template.spec.containers.name.env.
Save your changes.

Before you start the guided install

Take a look at the following to make sure you're ready:

If you're installing our integration on a managed cloud, please take a look at these preliminary notes before proceeding.
If custom manifests have been used instead of Helm, you will need to first remove the old installation using kubectl delete -f previous-manifest-file.yml, and then proceed through the guided installer again. This will generate an updated set of manifests that can be deployed using kubectl apply -f manifest-file.yml.
Make sure you're using the supported Kubernetes versions and make sure to check out the preliminary notes for your managed services or platforms on our compatibility and requirements page.
Make sure you have New Relic . You can set up an account that's free—no credit card required.
Make sure the newrelic dockerhub (https://hub.docker.com/u/newrelic) and Google's registry (registry.k8s.io) domains are added to your allow list. This is where the installation will pull container images from. Note, you may need to follow the commands to identify the additional Google registry domains to be added to your white list, because registry.k8s.io is typically redirected to your local registry domain (e.g., asia-northeast1-docker.pkg.dev) based on your region.

Start the guided install

We have some links below that will take you to the guided install that is right for you. After you start the installation process, you can use the tips in the remainder of this guide to help you make decisions about the various setup options.

Guided install option	Description
Guided install	Use this if your New Relic organization does not use the EU data center, and you don't need the bonus dashboards and alerts from the quickstart.
Guided install (EU)	Use this if your New Relic organization uses the EU data center, and you don't need the bonus dashboards and alerts from the quickstart.
Guided install with quickstart	Use this option if your New Relic organization does not use the EU data center, and you also want to install some bonus dashboards and alerts from the quickstart.

Once you start the guided install, use the following information to help you make decisions about the configurations.

Tip

The steps that follow skip the preliminary steps for the quickstart. If you chose the guided install with the quickstart, just click through the pages Confirm your Kubernetes quickstart installation and Installation plan to reach the main guided install pages described below.

Step 1 of 3

On the page Configure the Kubernetes Integration complete the following fields:

Field	Description
We'll send your data to this account	Choose the New Relic account that you want your Kubernetes data written to.
Cluster name	Cluster name is the name we will use to tag your Kubernetes data with so that you can filter for the data specific to the cluster you're installing this integration in. This is important if you choose to connect multiple clusters to your New Relic account so choose a name that you'll recognize!
Namespace for the integration	Namespace for the integration is the namespace we will use to house the Kubernetes integration in your cluster. We recommend using the default namespace of `newrelic`.

Step 2 of 3

On the page Select the additional data you want to gather, choose the options that are right for you:

Scrape Prometheus endpoints

By selecting this option, we will install Prometheus in agent mode to collect metrics from the Prometheus endpoints exposed in your cluster. Expand the collapsers to see details about each option:

We recommend this configuration because various other components of the Kubernetes integration, such as kube-state-metrics, newrelic-infrastructure, and nri-prometheus will already collect these metrics and configuring Prometheus to exclude those metrics will save your data ingest costs by removing any metric redundancies.

This configuration will filter out any metrics prefixed with kube_, container_, machine_, and cadvisor_.

Here's an example from newrelic-prometheus-configurator/charts/newrelic-prometheus-agent/static/lowdatamodedefaults.yaml:

low_data_mode:
- action: drop
  source_labels: [__name__]
  regex: "kube_.+|container_.+|machine_.+|cadvisor_.+"

New Relic provides quickstarts, which are pre-made dashboards, alerts, and entities for various services. Select this option to have Prometheus only scrape for services which have a pre-made quickstart and are ready to go for instant observability.

Here's an example from newrelic-prometheus-configurator/charts/newrelic-prometheus-agent/values.yaml showing in the app_values field which services will be scraped for the Prometheus quickstart option:

kubernetes:
    # NewRelic provides a list of Dashboards, alerts and entities for several Services. The integrations_filter configuration
    # allows to scrape only the targets having this experience out of the box.
    # If integrations_filter is enabled, then the jobs scrape merely the targets having one of the specified labels matching
    # one of the values of app_values.
    # Under the hood, a relabel_configs with 'action=keep' are generated, consider it in case any custom extra_relabel_config is needed.
    integrations_filter:
      # -- enabling the integration filters, merely the targets having one of the specified labels matching
      #    one of the values of app_values are scraped. Each job configuration can override this default.
      enabled: true
      # -- source_labels used to fetch label values in the relabel config added by the integration filters configuration
      source_labels: ["app.kubernetes.io/name", "app.newrelic.io/name", "k8s-app"]
      # -- app_values used to create the regex used in the relabel config added by the integration filters configuration.
      # Note that a single regex will be created from this list, example: '.*(?i)(app1|app2|app3).*'
      app_values: ["redis", "traefik", "calico", "nginx", "coredns", "kube-dns", "etcd", "cockroachdb", "velero", "harbor", "argocd"]

You'll find this option useful if you're an advanced user who has a good idea of what services you want to see Prometheus metrics from. Enter a comma-separated list of services you want Prometheus to scrape, and Prometheus will perform a wildcard match on the service name in order to find you metrics from your desired endpoint.

This option will only provide metrics from the services that match the submitted list, so be careful to validate the entry for correctness. To learn more about custom app labels, see Advanced configuration for the Prometheus agent.

The services you add to the submitted list will overwrite the data in app_values below, and Prometheus will only scrape metrics from those services.

Here is an example from newrelic-prometheus-configurator/charts/newrelic-prometheus-agent/values.yaml:

kubernetes:
    # NewRelic provides a list of Dashboards, alerts and entities for several Services. The integrations_filter configuration
    # allows to scrape only the targets having this experience out of the box.
    # If integrations_filter is enabled, then the jobs scrape merely the targets having one of the specified labels matching
    # one of the values of app_values.
    # Under the hood, a relabel_configs with 'action=keep' are generated, consider it in case any custom extra_relabel_config is needed.
    integrations_filter:
      # -- enabling the integration filters, merely the targets having one of the specified labels matching
      #    one of the values of app_values are scraped. Each job configuration can override this default.
      enabled: true
      # -- source_labels used to fetch label values in the relabel config added by the integration filters configuration
      source_labels: ["app.kubernetes.io/name", "app.newrelic.io/name", "k8s-app"]
      # -- app_values used to create the regex used in the relabel config added by the integration filters configuration.
      # Note that a single regex will be created from this list, example: '.*(?i)(app1|app2|app3).*'
      app_values: ["redis", "traefik", "calico", "nginx", "coredns", "kube-dns", "etcd", "cockroachdb", "velero", "harbor", "argocd"]

Gather log data

If you prefer more robust data, select this option to fully enrich your logs by adding label and annotation data.

Here's an example of a log with full data enrichment:

[
  {
    "cluster_name": "api-test",
    "kubernetes": {
      "annotations": {
        "kubernetes.io/psp": "eks.privileged"
      },
      "container_hash": "fryckbos/test@sha256:5b098eaf3c7d5b3585eb10cebee63665b6208bea31ef31a3f0856c5ffdda644b",
      "container_image": "fryckbos/test:latest",
      "container_name": "newrelic-logging",
      "docker_id": "134e1daf63761baa15e035b08b7aea04518a0f0e50af4215131a50c6a379a072",
      "host": "ip-192-168-17-123.ec2.internal",
      "labels": {
        "app": "newrelic-logging",
        "app.kubernetes.io/name": "newrelic-logging",
        "controller-revision-hash": "84db95db86",
        "pod-template-generation": "1",
        "release": "nri-bundle"
      },
      "namespace_name": "nrlogs",
      "pod_id": "54556e3e-719c-46b5-af69-020b75d69bf1",
      "pod_name": "nri-bundle-newrelic-logging-jxnbj"
    },
    "message": "[2021/09/14 12:30:49] [ info] [engine] started (pid=1)\n",
    "plugin": {
      "source": "kubernetes",
      "type": "fluent-bit",
      "version": "1.8.1"
    },
    "stream": "stderr",
    "time": "2021-09-14T12:30:49.138824971Z",
    "timestamp": 1631622649138
  }
]

If you want to prioritize data ingest costs, you can choose to gather log data with minimal enrichment, also known as low data mode. This option drops labels and annotations from your logs and only shares standard Kubernetes log data such as the name of the cluster, container, namespace, and pod, along with the message and timestamp.

When selecting the minimal enrichment mode, only the following log attributes are retained: cluster_name, container_name, namespace_name, pod_name, stream, message and log.

Here's an example of a log with minimal data enrichment:

[
  {
    "cluster_name": "api-test",
    "container_name": "newrelic-logging",
    "namespace_name": "nrlogs",
    "pod_name": "nri-bundle-newrelic-logging-jxnbj",
    "message": "[2021/09/14 12:30:49] [ info] [engine] started (pid=1)\n",
    "stream": "stderr",
    "timestamp": 1631622649138
  }
]

Enable service-level insights, full-body requests, and application profiles through Pixie

Pixie is an open source observability tool for Kubernetes applications that uses eBPF to automatically collect telemetry data. If you don't have Pixie installed on your cluster, but want to leverage Pixie's powerful telemetry data collection and visualization on the New Relic platform, check Enable service-level insights, full-body requests, and application profiles through Pixie.

If you're already using Community Cloud, select Community Cloud hosted Pixie is already running on this cluster. Keep the following in mind about the different ways Pixie can be hosted. New Relic provides a different level of integration support for each Pixie hosting option.

If you're using Pixie with a self-hosted Pixie Cloud, you can also connect Pixie to New Relic. This approach will enable the export of Pixie telemetry data into New Relic via the OpenTelemetry endpoint for long-term data retention and visibility. Unfortunately, if you're self-hosting your Pixie Cloud, New Relic does not support embedding Pixie's Live UI.

If you're self-hosting Pixie Cloud and would like to enable the export of Pixie telemetry data into New Relic, simply enable Pixie in the Kubernetes Integration without checking the Community Cloud hosted Pixie option. The Kubernetes Integration will detect that Pixie is running in your cluster and enable the data export for instant data visibility and insight.

Step 3 of 3

Finalize the Kubernetes installation setup by choosing one of the following installation methods in the last step of the guided install:

Guided Install (recommended): This option will automatically download and use the newrelic-cli CLI to install and configure the Kubernetes integration.
Helm 3: Use this option if you prefer using Helm to install and configure the Kubernetes integration. This option installs the nri-bundle Helm chart, which you can further configure with the options described here.
Manifest: Select this option if you prefer generating a Kubernetes manifest in YAML format and manually installing it with kubectl.

Use your Kubernetes data

Learn more about:

Unprivileged and privileged modes
Exploring your Kubernetes data in the UI
Using your Kubernetes data with queries, in charts, for alerts, etc.

Get started with Kubernetes

Why use the guided install?

Tip

Preliminary notes for your managed services or platforms

Amazon EKS / EKS Anywhere / EKS Anywhere on bare metal

Amazon EKS Fargate

Google Kubernetes Engine (GKE)

OpenShift container platform

Tip

Azure Kubernetes Service (AKS)

Before you start the guided install

Start the guided install

Navigating the Kubernetes integration guided install

Tip

Scrape Prometheus endpoints

Scrape all Prometheus endpoints except core Kubernetes system metrics (recommended)

Scrape all Prometheus endpoints

Scrape only Prometheus endpoints with quickstarts

Scrape only the certain labels

Gather log data

Forward all logs with full enrichment

Forward all logs with minimal enrichment (low data mode)

Enable service-level insights, full-body requests, and application profiles through Pixie

Community Cloud Pixie

Self-hosted Pixie

Use your Kubernetes data

Did this doc help with your installation?