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 and your Kubernetes cluster's name:
Find and copy your .
Choose a display name for your cluster. For example, you could use the output of:bash$kubectl config current-context
Keep these values somewhere safe, as you will need them later during the installation process.
Install Kubernetes integration with Helm
New Relic has several Helm 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
MutatingAdmissionWebhookthat 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.
Although you can install these components separately, we strongly recommend you use the
nri-bundle chart. New Relic provides this chart, which acts as a wrapper or a meta-package for the individual charts mentioned above. The use of this chart enables you these advantages:
- It provides full control over which components are installed. Each component is installed as a separate Helm dependency. You can configure them individually using the parameters mentioned here.
- It ensures that their installed versions are compatible with each other.
- It ensures that their configuration values are consistent across the installed charts.
nri-bundle chart is the one that is installed and configured by our Kubernetes guided install.
Installing and configuring
nri-bundle with Helm
Ensure you're using the appropriate context in the machine where you will run Helm and
You can check the available contexts with:bash$kubectl config get-contexts
And switch to the desired context using:bash$kubectl config use-context _CONTEXT_NAME_
Add the New Relic Helm charts repo:bash$helm repo add newrelic https://helm-charts.newrelic.com
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 significantlyenabled: truenri-metadata-injection:# Deploy our webhook to link APM and Kubernetes entitiesenabled: truenri-kube-events:# Report Kubernetes eventsenabled: truenewrelic-logging:# Report logs for containers running in the clusterenabled: truekube-state-metrics:# Deploy kube-state-metrics in the cluster.# Set this to true unless it is already deployed.enabled: true
Make sure everything is configured properly in the chart by running the following command. Notice that we're specifying
--debug, so nothing will be installed in this step:bash$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 for your account.
global.cluster=K8S_CLUSTER_NAME: It's 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
truewill 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's 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.
Install the Kubernetes integration by running the command without
--dry-run:bash$helm upgrade --install newrelic-bundle newrelic/nri-bundle \>--namespace newrelic --create-namespace \>-f values-newrelic.yaml
Make sure you're using Kubernetes version 1.26.x or a lower version that we support.
Kubernetes 1.27.x is currently in an experimental release phase. If you find any issues, please contact support.
Check that pods are being deployed and reach a stable state:bash$kubectl -n newrelic get pods -w
You should see:
newrelic-nrk8s-kubeletpod for each node in your cluster.
newrelic-nrk8s-control-planepod for each master node in your cluster, if any.
newrelic-kube-state-metricspod, if you included KSM with our installation.
newrelic-nri-kube-eventspod, if you enabled Kubernetes events reporting.
prometheus-agentpod, if you enabled the Prometheus agent integration.
newrelic-newrelic-loggingpod for each node in your cluster, if you enabled the Logging integration.
Did this doc help with your installation?
Configure the integration
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.
nri-bundle chart wraps multiple individual charts to gather different telemetry data and send it to New Relic. The bundle allows to selectively enable the desired child charts depending on your needs. To configure each individual component, you must use Helm's dependency system, which in short means that the configuration for each child chart must be placed under a separate section (named after each child chart) in the values-newrelic.yml file. For example, to configure the
newrelic-infrastructure chart, you would add the following to the
# General settings that apply to all the child chartsglobal:licenseKey: _YOUR_NEW_RELIC_LICENSE_KEY_cluster: _K8S_CLUSTER_NAME_# ... Other settings as shown above# Specific configuration for the newrelic-infrastructure child chartnewrelic-infrastructure:verboseLog: true # Enable debug logsprivileged: false # Install with minimal privileges# Other options from https://github.com/newrelic/helm-charts/tree/master/charts/newrelic-infrastructure-v3# Specific configuration for the newrelic-logging child chartnewrelic-logging:fluentBit:retryLimit: 10
You can also pass child chart options through the command line by prefixing them with the child chart name and replace the nesting by dots:
helm upgrade --install newrelic-bundle newrelic/nri-bundle \--namespace=newrelic \--set global.licenseKey=_YOUR_NEW_RELIC_LICENSE_KEY_ \--set global.cluster=_K8S_CLUSTER_NAME_ \--set newrelic-infrastructure.privileged=false \--set newrelic-infrastructure.verboseLog=true \--set newrelic-logging.fluentBit.retryLimit=10
The full list of flags you can tweak (such as scrape-interval) for each child chart can be found in their respective repositories:
- Configure debug logs, privilege mode, control plane monitoring, etc.
- Configure how the webhook for APM linkage is deployed.
- Configure which Prometheus endpoints are scraped.
- Configure which logs or log attributes are sent to New Relic.
When specifying configuration options for the child charts, you must place them under a section named after the chart name in your
To pass child chart options through the command line, you need to prefix them with the child chart name and replace the nesting by dots.