Install the Kubernetes integration using Helm

Helm is a package manager on top of Kubernetes. It facilitates installation, upgrades, or revision tracking, and it manages dependencies for the services that you install in Kubernetes. If you haven't already, create your free New Relic account below to start monitoring your data today.

To install the integration using Helm, we recommend our Kubernetes guided install, which will prompt for some configuration options and autopopulate secrets and values for you. Additionally, our guided install also allows installing our integration as plain manifests rather than a Helm release.

Compatibility and requirements

Make sure Helm is installed on your machine. Version 3 of the Kubernetes Integration requires Helm version 3.

To install the Kubernetes integration using Helm, you will need your New Relic license key and your Kubernetes cluster's name:

1. Find and copy your license key.

2. Choose a display name for your cluster. For example, you could use the output of:

   bash

   Copy

   $
   kubectl config current-context

Install Kubernetes integration with Helm

New Relic has several charts for the different components which offer different features for the platform:

• newrelic-infrastructure: Contains the main Kubernetes integration and the infrastructure agent. This is the core component for the New Relic Kubernetes experience, responsible for reporting most of the data that is surfaced in the Kubernetes Dashboard and the Kubernetes Cluster Explorer.
• newrelic-logging: Provides a DaemonSet with New Relic's Fluent Bit output plugin to easily forward your logs to New Relic.
• nri-kube-events: Collects and reports cluster events (such as kubectl get events) to New Relic.
• prometheus-agent: New Relic's Prometheus Configurator configures a Prometheus in agent mode and use our remote write endpoint to reports metrics to New Relic.
• nri-metadata-injection: Sets up a minimal MutatingAdmissionWebhook that injects a couple of environment variables in the containers. These contain metadata about the cluster and New Relic installation and will be later picked up by applications instrumented using APM, allowing to correlate APM and infrastructure data.
• nri-statsd: New Relic StatsD integration.

For convenience, New Relic provides the nri-bundle chart, which pulls a selectable set of the charts mentioned above. nri-bundle can also install Kube State Metrics and Pixie for you if needed.

While it's possible to install those charts separately, we strongly recommend using the nri-bundle chart for Kubernetes deployments, as it ensures that values across all the charts are consistent and provides full control over which components are installed, as well as the possibility to configure all of them as Helm dependencies. This is the same chart that is used and referenced by our Kubernetes guided install.

Installing and configuring nri-bundle with Helm

1. Ensure you're using the appropriate context in the machine where you will run Helm and kubectl:

   You can check the available contexts with:

   bash

   Copy

   $
   kubectl config get-contexts

   And switch to the desired context using:

   bash

   Copy

   $
   kubectl config use-context _CONTEXT_NAME_

2. Add the New Relic Helm charts repo:

   bash

   Copy

   $
   helm repo add newrelic https://helm-charts.newrelic.com

3. Create a file named values-newrelic.yaml, which will be used to define your configuration:

   global:
     licenseKey: _YOUR_NEW_RELIC_LICENSE_KEY_
     cluster: _K8S_CLUSTER_NAME_
   
   newrelic-prometheus-agent:
     # Automatically scrape prometheus metrics for annotated services in the cluster
     # Collecting prometheus metrics for large clusters might impact data usage significantly
     enabled: true
   nri-metadata-injection:
     # Deploy our webhook to link APM and Kubernetes entities
     enabled: true
   nri-kube-events:
     # Report Kubernetes events
     enabled: true
   newrelic-logging:
     # Report logs for containers running in the cluster
     enabled: true
   kube-state-metrics:
     # Deploy kube-state-metrics in the cluster.
     # Set this to true unless it is already deployed.
     enabled: true

   Copy

4. Make sure everything is configured properly in the chart by running the following command. Notice that we're specifying --dry-run and --debug, so nothing will be installed in this step:

   bash

   Copy

   $
   helm upgrade --install newrelic-bundle newrelic/nri-bundle \
   >
   --namespace newrelic --create-namespace \
   >
   -f values-newrelic.yaml \
   >
   --dry-run \
   >
   --debug

   Please notice and adjust the following flags:

   • global.licenseKey=YOUR_NEW_RELIC_LICENSE_KEY: Must be set to a valid license key for your account.
   • global.cluster=K8S_CLUSTER_NAME: Is used to identify the cluster in the New Relic UI, so should be a descriptive value not used by any other Kubernetes cluster configured in your New Relic account.
   • kube-state-metrics.enabled=true: Setting this to true will automatically install Kube State Metrics (KSM) for you, which is required for our integration to run. You can set this to false if KSM is already present in your cluster, even if it is on a different namespace.
   • newrelic-prometheus-agent.enabled=true: Will deploy our Prometheus Agent, which automatically collects data from Prometheus endpoints present in the cluster.
   • nri-metadata-injection.enabled=true: Will install our minimal webhook, which adds environment variables that, in turn, allows linking applications instrumented with New Relic APM to Kubernetes.

Our Kubernetes charts have a comprehensive set of flags and tunables that can be edited to better fit your particular needs. Please check the Configure the integration section below to see what can be changed.

5. Install the Kubernetes integration by running the command without --debug and --dry-run:

   bash

   Copy

   $
   helm upgrade --install newrelic-bundle newrelic/nri-bundle \
   >
   --namespace newrelic --create-namespace \
   >
   -f values-newrelic.yaml

   Important

   Make sure you're using Kubernetes version 1.25.x or a lower version that we support.

6. Check that pods are being deployed and reach a stable state:

   bash

   Copy

   $
   kubectl -n newrelic get pods -w

You should see:

1. One newrelic-nrk8s-ksm pod.
2. One newrelic-nrk8s-kubelet pod for each node in your cluster.
3. One newrelic-nrk8s-control-plane pod for each master node in your cluster, if any.
4. One newrelic-kube-state-metrics pod, if you included KSM with our installation.
5. One newrelic-nri-kube-events pod, if you enabled Kubernetes events reporting.
6. One prometheus-agent pod, if you enabled the Prometheus agent integration.
7. One newrelic-newrelic-logging pod for each node in your cluster, if you enabled the Logging integration.

Install with Helm 2 and nri-bundle (legacy)

Configure the integration

Our nri-bundle chart. whose installation instructions can be found above, acts as a wrapper or a meta-package for a couple of other charts, which are the ones containing the components for our solution. By offering such a wrapper we can provide a controlled set of our components with versions that we know are compatible with each other, while keeping the component's charts relatively simple.

To configure the individual integration components, you must use Helm's dependency system, which simply means that configuration for the children charts must be put under a section with the name of said chart. For example, to configure the newrelic-infrastructure chart, you would add the following to the values-newrelic.yaml:

global:
  licenseKey: _YOUR_NEW_RELIC_LICENSE_KEY_
  cluster: _K8S_CLUSTER_NAME_

# ... Other settings as shown above

# Configuration for newrelic-infrastructure
newrelic-infrastructure:
  verboseLog: true  # Enable debug logs
  privileged: false  # Install with minimal privileges
  # Other options from https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-infrastructure-v3

The full list of flags you can tweak (such as scrape-interval) is in our chart's repository:

• newrelic-infrastructure
• Configure debug logs, privilege mode, control plane monitoring, etc.
• nri-kube-events
• nri-metadata-injection
• Configure how the webhook for APM linkage is deployed.
• Configure which Prometheus endpoints are scraped.
• newrelic-logging
• Configure which logs are sent to New Relic.