The easiest way to install the Kubernetes integration is to use our automated installer to generate a manifest. It bundles not just the integration DaemonSets, but also other New Relic Kubernetes configurations, like Kubernetes events, Prometheus OpenMetrics, and New Relic log monitoring.
To use Kubernetes integrations and infrastructure monitoring, as well as the rest of our observability platform, join the New Relic family! Sign up to create your free account in only a few seconds. Then ingest up to 100GB of data for free each month. Forever.
You can use the automated installer for servers, VMs, and unprivileged environments. The installer can also help you with managed services or platforms after you review a few preliminary notes. We also have separate instructions if you need a custom manifest or prefer to do a manual unprivileged installation.
Before starting our automated installer, check out these notes for your managed services or platforms:
If the Kubernetes automated installer doesn't provide the settings you need, you can download our manifest template and install the integration manually.
To activate the Kubernetes integration, you must deploy the
newrelic-infra agent onto a Kubernetes cluster as a
Install kube-state-metrics and get it running on the cluster. For example:
curl -L -o kube-state-metrics-1.9.5.zip https://github.com/kubernetes/kube-state-metrics/archive/v1.9.5.zip && unzip kube-state-metrics-1.9.5.zip && kubectl apply -f kube-state-metrics-1.9.5/examples/standard
Download the manifest file:curl -O https://download.newrelic.com/infrastructure_agent/integrations/kubernetes/newrelic-infrastructure-k8s-latest.yaml
DaemonSetportion of your manifest, add your New Relic license key and a cluster name to identify your Kubernetes cluster. Both values are required.
- Recommendation: Do not change the
NRIA_DISPLAY_NAMEvalue in your manifest.
YOUR_CLUSTER_NAMEis your cluster’s id in New Relic Explorer. It doesn’t need to match the name of the cluster running in your environment.
- YAML key path:
env: - name: NRIA_LICENSE_KEY value: YOUR_LICENSE_KEY - name: CLUSTER_NAME value: YOUR_CLUSTER_NAME
- Recommendation: Do not change the
If you need to adapt the manifest to fit your environment, review the configure section in this doc.
kube-state-metricsis installed.kubectl get pods --all-namespaces | grep kube-state-metrics
DaemonSet:kubectl create -f newrelic-infrastructure-k8s-latest.yaml
Confirm that the
DaemonSethas been created successfully by looking for
newrelic-infrain the results generated by this command:kubectl get daemonsets
To confirm that the integration is working: wait a few minutes, then look for data in the New Relic Kubernetes cluster explorer.
In the future, the number of labels collected on Kubernetes objects will be limited per object type (containers, pods, nodes, etc.). If objects have labels above the limit, you will be able to configure important labels that should always be sent to New Relic. When the limitation is in place, this documentation will be updated.
Some of the New Relic pods are set up as
DaemonSet in the manifest file so that they can run on every host. These include
newrelic-logging. In rare circumstances, other pods may be scheduled first and starve the New Relic pods of resources. Since each of these pods have to run on a specific host, they will stay in pending status until that host has enough resources, even if there are other hosts available. This could end up occurring for long periods of time and result in reporting gaps.
To prevent this scenario, you can configure the Kubernetes scheduler to give New Relic pods a higher priority. Using the default scheduler:
disablePreemptionis not set to
true(by default it is
Create a PriorityClass for the New Relic
- Set the appropriate priority value, which should generally be higher than your other pods.
preemptionPolicyis set to
PreemptLowerPriorityby default. This allows New Relic pods assigned this priority class to remove lower-priority pods that are taking up resources.
Edit the manifest file to add
DaemonSetspecs. In the example below, the highlighted line sets the priority class for
apiVersion: apps/v1 kind: DaemonSet metadata: namespace: default labels: app: newrelic-infrastructure chart: newrelic-infrastructure-1.0.0 release: nri-bundle mode: privileged name: nri-bundle-newrelic-infrastructure spec: priorityClassName: your-priority-class ...
If you have already deployed the New Relic pods, re-deploy them and confirm they have been created:kubectl delete -f newrelic-infrastructure-k8s-latest.yamlkubectl create -f newrelic-infrastructure-k8s-latest.yamlkubectl get daemonsets
For platforms that have stringent security requirements, we provide an unprivileged version of the Kubernetes integration. Changes from the standard Kubernetes integration are:
- Runs the infrastructure agent and the Kubernetes integration as a standard user instead of root
- No access to the underlying host filesystem
- No access to
- Container's root filesystem mounted as read-only
allowPrivilegeEscalationis set to
hostnetworkis set to
The tradeoff is that the solution will only collect metrics from Kubernetes, but it will not collect any metric from the underlying hosts directly. Kubernetes provides some data (metrics and metadata) about its nodes (hosts).
Optional: To collect the underlying host metrics, the non-containerized infrastructure agent can be deployed on the underlying host. The infrastructure agent already supports running as non-root. The combination of the Kubernetes integration in its unprivileged version and the agent running on the host will report all the metrics that our standard solution for monitoring Kubernetes receives.
The Kubernetes integration comes with a default configuration that should work in most environments. To change the configuration, modify the manifest file:
Here are some additional configurations to consider:
- Do more configuration for control plane monitoring
- Link New Relic APM to the Kubernetes integration
- Monitor services that run on Kubernetes
The Kubernetes integration image comes with a default configurations for the agent that can be modified if needed. When installing with the manifest, you can modify the infrastructure agent configuration by editing the manifest and adding any needed configuration option of the agent as environment variables of the
config object is used to populate the
configMap that is mounted automatically in the location of the infrastructure agent configuration file in the pods created by the
To update a Kubernetes integration installed with the automated installer, just run the installer again. It will always offer a manifest pointing to the last released version of the integration.
If you are already running the Kubernetes integration and want to update the
newrelic-infra agent to the latest agent version:
Run this NRQL query to check which version you are currently running (this will return the image name by cluster):
SELECT latest(containerImage) FROM K8sContainerSample WHERE containerImage LIKE '%newrelic/infrastructure%' FACET clusterName SINCE 1 day ago
If you've set a name other than
newrelic/infrastructurefor the integration's container image, the above query won't yield results: to make it work, edit the name in the query.
Download the integration manifest file:curl -O https://download.newrelic.com/infrastructure_agent/integrations/kubernetes/newrelic-infrastructure-k8s-latest.yaml
Copy the changes you made to the manifest. At a minimum, include
NRIA_LICENSE_KEY, and paste your changes in the manifest you downloaded.
Install the latest
DaemonSetwith the following command (Kubernetes will automatically do a rollout upgrade for the integration's pods):kubectl apply -f newrelic-infrastructure-k8s-latest.yaml
To uninstall the Kubernetes integration:
newrelic-infrastructure-k8s-latest.yamlcorresponds to the filename of the manifest as you have saved it.
Example: If you are using the unprivileged version of the integration, the default filename will be
After you verify the filename, use the following command:kubectl delete -f newrelic-infrastructure-k8s-latest.yaml
You only need to execute this command once, regardless of the number of nodes in your cluster.
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 data security and licenses documentation.