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.
To install the integration using Helm, we recommend our Kubernetes automated installer, which will prompt for almost all configuration options and autopopulate secrets and values for you. Additionally, our automated installer also allows to install our integration as plain manifests rather than a Helm release. See Kubernetes integration: install and configure for more details about how to use our automated installer.
This page describes in more depth how to install and configure the New Relic integration without using the automated installer.
Compatibility and requirements
Make sure Helm is installed on your machine. We strongly recommend using Helm 3 to manage the Kubernetes integration. Our charts are also compatible with Helm 2, but support for it might be removed in the future.
To install the Kubernetes integration using Helm, you will need your New Relic account license key and your Kubernetes cluster's name:
- Find and copy your New Relic license key.
- Find the name of your cluster with this command:
kubectl config current-context
Note this values somewhere safe as you will need them later during the installation process.
Install Kubernetes integration with Helm
Install with Helm 3 and nri-bundle (recommended)
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 of reporting most of the data that is surfaced in 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 askubectl get events
) to New Relic.nri-prometheus
: New Relic's Prometheus OpenMetrics Integration, automatically scrapes Prometheus endpoints present in the cluser and reports metrics to New Relic.nri-metadata-injection
: Sets up a minimalMutatingAdmissionWebhook
that injects a couple of environment to 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.
Additionally, New Relic provides nri-bundle
, a 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 is 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 automated installer.
Installing and configuring nri-bundle
with Helm
- Ensure you are using the appropriate context in the machine where you will run Helm and
kubectl
:
You can check the available contexts with:
kubectl config get-contexts
And switch to the desired context using:
kubectl config use-context CONTEXT_NAME
- Add the New Relic Helm charts repo:
helm repo add newrelic https://helm-charts.newrelic.com
- Make sure everything is configured properly in the chart by running the following command. Notice that we are specifying
--dry-run
and--debug
, so nothing will be installed in this step:
helm upgrade --install newrelic newrelic/nri-bundle \
--dry-run \
--debug \
--namespace newrelic --create-namespace \
--set global.licenseKey=YOUR_NEW_RELIC_LICENSE_KEY \
--set global.cluster=K8S_CLUSTER_NAME \
--set ksm.enabled=true \
--set newrelic-infrastructure.privileged=true \
--set infrastructure.enabled=true \
--set prometheus.enabled=true \
--set webhook.enabled=true \
--set kubeEvents.enabled=true \
--set logging.enabled=true
Please notice and adjust the following flags:
global.licenseKey=<var>YOUR_NEW_RELIC_LICENSE_KEY</var>
: Must be set to a valid License Key for your account.global.cluster=<var>K8S_CLUSTER_NAME</var>
: 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.ksm.enabled=<mark>true</mark>
: Setting this totrue
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-infrastructure.privileged=<mark>true</mark>
: Can be set tofalse
to install a trimmed down version of our integration that does not require extra privileges, such ashostPath
mounts or running containers as root.- Please note that this will disable detailed process collection from the host.
- For performance reasons, our logging solution still requires
hostPath
mounts, regardless of the value of this flag. If this is not allowedin your cluster, you will need to disable the logging solution by specifyinglogging.enabled=false
.
prometheus.enabled=true
: Will deploy our Prometheus OpenMetrics integration, which automatically collects data from prometheus endpoints present in the cluster.webhook.enabled=true
: Will install our minimal webhook, which adds environment variables that, in turn, allows linking applications instrumented with APM with infrastructure data.
Our chart has a comprehensive set of flags and tunables that can be edited to configure our solution to your particular needs. For a full list of all the flags that can be configured, please check the chart's README and the default values.yaml
file.
- Install the Kubernetes integration by running the customized command without
--debug
and--dry-run
:
helm upgrade --install newrelic newrelic/nri-bundle \
--namespace newrelic --create-namespace \
--set global.licenseKey=YOUR_NEW_RELIC_LICENSE_KEY \
--set global.cluster=K8S_CLUSTER_NAME \
--set ksm.enabled=true \
--set newrelic-infrastructure.privileged=true \
--set infrastructure.enabled=true \
--set prometheus.enabled=true \
--set webhook.enabled=true \
--set kubeEvents.enabled=true \
--set logging.enabled=true
- Wait a few seconds, then check that the
DaemonSet
and pods have been created:
kubectl -n newrelic get daemonsets,pods
- Make sure you see a
DaemonSet
, and one pod per node fornewrelic-infrastructure
, as well as oneDeployment
and one pod for any other component that you have enabled.
Install with Helm 2 and nri-bundle (legacy)
Upgrade using Helm
To update your Kubernetes integration installed via Helm:
- Update the local chart repository:
helm repo update
- Update the release by running again the appropriate
helm upgrade --install ...
command in the section above.
Monitor services running on Kubernetes
After having installed our Kubernetes integration, you can start instrumenting the services than run in your cluster. To learn more about how to do this, please check our Monitor services running on Kubernetes page.
Use your Kubernetes data
To learn more about how to use your Kubernetes data, please head to our detailed Find and use your Kubernetes data pages.
Reduce data ingest
Our charts support setting an option to reduce the amount of data ingest at the cost of dropping detailed information. To enable it, set global.lowDataMode=true
in the nri-bundle
chart.
lowDataMode
affects three specific components of the nri-bundle
chart outlined below.
Prometheus OpenMetrics Integration
If lowDataMode
is enabled, the following metrics are excluded by default as they are already collected and used by the New Relic Kubernetes Integration.
- kube_- container_- machine_- cadvisor_
New Relic Logging
If lowDataMode
is enabled, Labels and Annotations are set to Off
in the Filter section of the fluent-bit.conf file. This means that this detail will be dropped from the container log files which reduces the overall data ingest into New Relic.
The following fields are retained:
Allowlist_key container_nameAllowlist_key namespace_nameAllowlist_key pod_nameAllowlist_key streamAllowlist_key log
Low Data Mode Log Example
Complete Log Record
[ { "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 }]
Log Record after enabling lowDataMode
.
[ { "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 }]
New Relic Pixie Integration
If lowDataMode
is enabled, the newrelic-pixie
integration performs heavier sampling on Pixie spans and reduces the collection interval from 10 seconds to 15 seconds.
lowDataMode
settings:
HTTP_SPAN_LIMIT: 750DB_SPAN_LIMIT: 250COLLECT_INTERVAL_SEC: 15
The default settings for these parameters and others can be found in the newrelic-pixie-integration Github repo.
For more help
If you need more help, check out these support and learning resources:
- Browse the Explorers Hub to get help from the community and join in discussions.
- Find answers on our sites and learn how to use our support portal.
- Run New Relic Diagnostics, our troubleshooting tool for Linux, Windows, and macOS.
- Review New Relic's and and documentation.