Install New Relic eBPF agent for Kubernetes

You can install the New Relic eBPF agent on your Kubernetes cluster to monitor your entire system health. The eBPF agent provides deep visibility into application performance without requiring code changes or deploying language-specific agents.

Install New Relic eBPF agent

Before you begin

You must meet the prerequisites outlined in the eBPF compatibility and requirements documentation for Kubernetes clusters.

Install the eBPF agent

To install the eBPF agent:

Log in to your New Relic account.
Go to left navigation pane > + Integration & Agents > eBPF Agent.
On the Select an account screen, select the account you want to install the eBPF agent on, and click Continue.
On the Select an installation method page, select Kubernetes, and click Continue.
On the Enter your user key screen, select one of the following options, then click Continue:
- Use an existing key: If you already have a user key, provide the user key. For more information, refer to User keys.
- Create a new key: If you don't have a user key, click Create a new key to create one.
On the Configure the Kubernetes integration screen:
1. Enter the deployment name for the Kubernetes.
2. (Optional) Enter the namespace for the integration. The default namespace is newrelic.
3. Click Continue.
Dica
If you choose a custom namespace for your New Relic instrumentation (instead of the default newrelic), we recommend excluding that namespace from monitoring by adding it to the dropDataForNamespaces configuration parameter. This prevents the eBPF agent from monitoring the instrumentation pods themselves. For example, if you use newrelic-mon as your namespace, set: dropDataForNamespaces: ["kube-system", "newrelic-mon"].
On the Install the Kubernetes integration screen:
1. Copy and paste the displayed command to install the eBPF agent on your Kubernetes cluster using Helm.
2. (Optional) To download the values.yaml configuration file, click Download. For more on the configuration parameters, refer to K8s configuration parameters.
3. (Optional) Update the values.yaml file as needed and save it.
4. (Optional) To apply the configuration changes, run the following command:
  bash
```
$helm repo update ; helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent -n newrelic --values values.yaml
```
5. To verify the installation, run the following command:
  bash
```
$kubectl get pods -n newrelic
```

Access the eBPF data in New Relic

Once the eBPF agent is installed, it automatically starts collecting data from your Linux host. You can access this data in New Relic's OpenTelemetry UI. For more information on New Relic OpenTelemetry UI, refer OpenTelemetry APM UI.

To view the eBPF data in New Relic:

Go to one.newrelic.com > APM & Services.
In the search banner, set the search criteria as instrumentation.name = nr_ebpf:

Upgrade the eBPF agent

To upgrade the eBPF agent in a Kubernetes cluster:

For a standard upgrade: Use the following Helm command to upgrade to the latest version:

bash

$KSM_IMAGE_VERSION="v2.13.0" && helm repo add newrelic https://helm-charts.newrelic.com && helm repo update && kubectl create namespace "newrelic" ; helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent --set licenseKey=<key> --set cluster="<cluster-name>" --namespace=newrelic

For a specific version upgrade: To upgrade to a specific version, use the --version flag:

bash

$KSM_IMAGE_VERSION="v2.13.0" && helm repo add newrelic https://helm-charts.newrelic.com && helm repo update && kubectl create namespace "newrelic" ; helm upgrade --install nr-ebpf-agent newrelic/nr-ebpf-agent --set licenseKey=<key> --set cluster="<cluster-name>" --namespace=newrelic --version=0.2.5

Replace <key> with your New Relic license key and <cluster-name> with your cluster name.

Configuration parameters

The values.yaml file contains the following configuration sections:

These parameters control the core identity and data destination for the eBPF agent.

Parameter	Description	Data Type	Example
`cluster`	Specifies the name of your Kubernetes cluster. This field is mandatory.	`String`	`"production-cluster"`
`licenseKey`	Specifies your New Relic license key. Required if `customSecretName` is not used.	`String`	`"8356...FFFFNRAL"`
`nrStaging`	If `true`, sends data to New Relic's staging environment.	`Boolean`	`true`
`customSecretName`	Specifies the name of a Kubernetes secret that contains your license key. Use this to avoid providing the key directly.	`String`	`"newrelic-license-secret"`
`customSecretLicenseKey`	Specifies the key within the secret where the license key value is stored. Used with `customSecretName`.	`String`	`"license"`
`region`	Specifies your New Relic account region (`US` or `EU`). Required when using `customSecretName`.	`String`	`"US"`
`proxy`	Specifies the URL of a proxy server, including the port, to route all outgoing agent data through.	`String`	`"http://user:pass@host:port"`
`logLevel`	Defines the logging verbosity level for the agent. Valid options: `OFF`, `FATAL`, `ERROR`, `WARNING`, `INFO`, `DEBUG`.	`String`	`"INFO"`
`logFilePath`	Specifies a file path inside the agent container for log output. If the path is invalid, logs are directed to stdout.	`String`	`"/var/log/nr-ebpf-agent.log"`
`downloadedPackagedHeadersPath`	Sets the absolute path of the complete directory where the required linux headers are manually downloaded and placed for the eBPF agent to use. This is useful under restricted environments where agent is not able to download required linux headers. The required headers are identified by the agent based on the kernel version. The absolute path in case of K8s should also be prepended with /host when necessary. Use only after NR support recommendation.	`String`	`"/path/to/downloaded/headers/dir"`
`distroKernelHeadersPath`	Sets the absolute path of the complete directory where the linux headers are present for the eBPF agent to use. This is useful where required linux headers could not be installed or path could not be determined. The absolute path in case of K8s should also be prepended with /host when necessary. Use only after NR support recommendation.	`String`	`"/host/usr/src/linux-headers-6.8.0-pl"`
`vizierPort`	Vizier server port on which agent receives pxl scripts from the client. Default to 12345	`String`	`"12345"`
`apmDataReporting`	Enable APM data reporting. When enabled, the agent collects and reports application performance monitoring data.	`String`	`true`
`tcpStatsReporting`	Enable TCP statistics reporting. When enabled, the agent collects and reports low level tcp metrics and starts network monitoring.	`String`	`true`

These parameters control which data is collected and sent to New Relic, helping you manage data ingestion.

Parameter	Description	Data Type	Example
`dropDataNewRelic`	If `true`, drops all telemetry originating from the `newrelic` namespace to prevent self-monitoring.	`Boolean`	`true`
`dropDataForNamespaces`	Specifies a list of Kubernetes namespaces from which all telemetry will be dropped.	`String`	`["kube-system", "monitoring"]`
`dropDataServiceNameRegex`	Defines a Go-style regular expression. Data from services with names matching this pattern will be dropped.	`String`	`"kube-dns\\|otel-collector"`
`allowServiceNameRegex`	Defines a Go-style regular expression that acts as an allowlist for `dropDataServiceNameRegex`. Matching services are kept, even if they also match the drop pattern.	`String`	`"allowed-otel-collector"`
`dropDataForEntity`	Specifies a list of application names (from the `NEW_RELIC_APP_NAME` environment variable) to be excluded from monitoring.	`String`	`["my-test-app", "temp-service"]`
`tableStoreDataLimitMB`	Defines the memory limit in Megabytes (MiB) for the agent's internal data store. This is the primary control for RAM usage.	`String`	`"500"`

This section allows you to enable monitoring for specific network protocols and configure how trace data (spans) is collected. You can enable or disable monitoring for protocols like HTTP, MySQL, and others, and set parameters for span collection based on latency or error rates. The following protocols are supported:

HTTP
MySQL
PostgreSQL
MongoDB
Apache Cassandra
Redis
Kafka
DNS

Parameter	Description	Data Type	Example
`protocols.<protocol-name>.enabled`	If `true`, enables monitoring for the specified protocol for example, `http`, `mysql`, and any others.	`Boolean`	`true`
`protocols.<protocol-name>.spans.enabled`	If `true`, exports trace spans for the enabled protocol.	`Boolean`	`true`
`protocols.<protocol-name>.spans.samplingLatency`	Defines the latency-based sampling threshold for exporting spans. Valid options: `p1`, `p10`, `p50`, `p90`, `p99`.	`String`	`"p90"`
`protocols.http.spans.samplingErrorRate`	For HTTP only. Exports spans from any route where the error rate exceeds the specified percentage (1-100).	`String`	`"5"`

These sections control the deployment settings for the solution's main components. An asterisk (*) denotes the component name.

Parameter	Description	Data Type	Example
`*.image.repository`	Specifies the container image repository for the component.	`String`	`"docker.io/newrelic/newrelic-ebpf-agent"`
`*.image.pullPolicy`	Defines the pull policy for the container image.	`String`	`"IfNotPresent"`
`*.image.tag`	Specifies the version tag of the container image to deploy.	`String`	`"agent-0.2.4"`
`*.resources.limits.memory`	Defines the maximum memory the container can use.	`String`	`"2Gi"`
`*.resources.limits.cpu`	Defines the maximum CPU the container can use.	`String`	`"1"`
`*.resources.requests.memory`	Defines the minimum memory requested for the container at startup.	`String`	`"250Mi"`
`*.resources.requests.cpu`	Defines the minimum CPU requested for the container at startup.	`String`	`"100m"`
`*.tolerations`	Defines pod tolerations to allow scheduling on nodes with specific taints.	`Objects`	`[{"key": "special", "operator": "Exists"}]`
`*.affinity`	Defines pod affinity and anti-affinity rules for scheduling.	`Object`	`{}`
`*.podAnnotations`	Specifies custom annotations to add to the component's pod.	`Object`	`{"iam.amazonaws.com/role": "my-role"}`

These parameters apply to all pods deployed by the Helm chart, unless overridden by a component-specific setting.

Parameter	Description	Data Type	Example
`podLabels`	Specifies additional labels to apply to all pods deployed by the chart.	`Object`	`{"team": "observability"}`
`priorityClassName`	Specifies the `PriorityClass` for all pods.	`String`	`"high-priority"`
`nodeSelector`	Constrains pods to only run on nodes with matching labels.	`Object`	`{"disktype": "ssd"}`

This section configures secure communication between the eBPF agent and client components.

Parameter	Description	Data Type	Example
`tls.enabled`	If `true`, enables TLS for internal communication between components.	`Boolean`	`true`
`tls.autoGenerateCert.enabled`	If `true`, directs Helm to automatically generate a self-signed certificate for TLS.	`Boolean`	`true`
`tls.autoGenerateCert.recreate`	If `true`, a new certificate is generated on every `helm upgrade`.	`Boolean`	`false`
`tls.autoGenerateCert.certPeriodDays`	Defines the validity period in days for the auto-generated certificate.	`Integer`	`730`
`tls.certFile`	Specifies the path to your custom PEM-encoded certificate file. `autoGenerateCert.enabled` must be `false`.	`String`	`"my-certs/tls.crt"`
`tls.keyFile`	Specifies the path to your custom PEM-encoded private key file.	`String`	`"my-certs/tls.key"`
`tls.caFile`	Specifies the path to your custom Certificate Authority (CA) certificate file.	`String`	`"my-certs/ca.crt"`

Uninstall the eBPF agent

To uninstall the eBPF agent from your Kubernetes cluster:

bash

$helm uninstall nr-ebpf-agent -n newrelic

Dica

This command will remove all eBPF agent components from your cluster. The namespace will remain unless you explicitly delete it.

eBPF Linux installation

Learn how to set up the New Relic eBPF agent for your Linux host.

Troubleshooting eBPF

Learn how to troubleshoot issues with the New Relic eBPF agent.

eBPF best practices

Learn about best practices for using the New Relic eBPF agent.

Install New Relic eBPF agent for Kubernetes