• /
  • EnglishEspañolFrançais日本語한국어Português
  • Log inStart now

Manage existing instrumentation with Agent Control

Important

Agent Control and New Relic Control are now generally available for Kubernetes! Support for Linux hosts is also in public preview program, pursuant to our pre-release policies.

Kubernetes migration

If your Kubernetes cluster is already instrumented with New Relic, you must migrate your agents to be managed by Agent Control to use its features. This process involves a "rip-and-replace" approach where you uninstall your existing agents and then install them through Agent Control.

Agent Control supports a unified configuration method for all agents, ensuring you can retain all features and settings from your original Helm chart installation.

Best practices

To ensure data continuity, use the same cluster name and point to the same New Relic account during your Agent Control installation. You can continue to keep any agents or components that are not yet supported by Agent Control on the cluster.

Step 1. Match and Retrieve Your Existing Configuration

First, identify which of your existing agents can be managed by Agent Control.

Agent Control can deploy and manage the following agents, supported by the Helm charts included in the nri-bundle chart:

  • newrelic-infrastructure, nri-kube-events, kube-state-metrics, and nri-kube-events (now managed through the New Relic Infrastructure agent type)
  • newrelic-prometheus-configurator (now managed through the New Relic Prometheus agent type)
  • newrelic-logging (now managed through the Fluent Bit agent type)
  • The nr-k8s-otel-collector chart (now managed through the New Relic OpenTelemetry Collector agent type)

If you installed agents using Helm, retrieve your installation config from the cluster by running the following command:

bash
$
$ helm get values <release-name> --namespace <namespace-name>

If you have the original configuration file saved from the installation, you can use that directly.

On the other hand, if you have instrumented the cluster via manifest, find the corresponding options in each agent chart.

TIP

You can continue to keep any agents or components within the cluster, especially those that are not yet supported by Agent Control. To ensure the best experience, make sure to maintain the same cluster name and point to the same account.

Step 2. Create a New Agent Control Configuration

Now, create a new Agent Control values.yaml file based on your existing configuration. This will tell Agent Control how to deploy and configure your agents after the migration.

  1. Start the Agent Control Installation via guided install and select all the agents you are interested in.
  2. Copy the values.yaml file to your local machine.
  3. Update the downloaded file to correspond with the configurations of your old agents.

Example: Migrating an nri-bundle Installation

This example shows how to convert a configuration from the nri-bundle chart to a new Agent Control configuration.

Existing nri-bundle configuration:

bash
$
global:
$
cluster: test-migration
$
licenseKey: ***
$
kube-state-metrics:
$
enabled: false
$
newrelic-prometheus-agent:
$
enabled: true
$
newrelic-infrastructure:
$
enabled: true
$
kubelet:
$
tolerations:
$
- operator: "Exists"
$
effect: "NoSchedule"
$
- operator: "Exists"
$
effect: "NoExecute"
$
- operator: "Exists"
$
key: "MyToleration"
$
ksm:
$
enabled: false
$
common:
$
config:
$
interval: 29s
$
newrelic-logging:
$
enabled: true
$
image:
$
tag: "latest"
$
resources:
$
limits:
$
cpu: 200m
$
requests:
$
cpu: 200m
$
nri-kube-events:
$
enabled: true
$
customAttributes:
$
test_tag_label: test_tag_value

New Agent Control configuration:

You will modify the subAgents section of your new configuration to match the old settings. The example below shows how the original settings map to the new format.

bash
$
global:
$
cluster: "test-migration"
$
licenseKey: "****"
$
agent-control-deployment:
$
identityClientId: "****"
$
identityClientSecret: "****"
$
config:
$
fleet_control:
$
fleet_id: "****"
$
auth:
$
organizationId: "****"
$
subAgents:
$
logs:
$
type: newrelic/io.fluentbit:0.1.0
$
content:
$
chart_version: "1.25.1"
$
chart_values:
$
newrelic-logging:
$
image:
$
tag: "latest"
$
resources:
$
limits:
$
cpu: 200m
$
requests:
$
cpu: 200m
$
infrastructure:
$
type: newrelic/com.newrelic.infrastructure:0.1.0
$
content:
$
chart_version: "5.0.109"
$
chart_values:
$
newrelic-infrastructure:
$
kubelet:
$
tolerations:
$
- operator: "Exists"
$
effect: "NoSchedule"
$
- operator: "Exists"
$
effect: "NoExecute"
$
- operator: "Exists"
$
key: "MyToleration"
$
ksm:
$
enabled: false
$
common:
$
config:
$
interval: 29s
$
nri-kube-events:
$
customAttributes:
$
test_tag_label: test_tag_value
$
prometheus:
$
type: newrelic/com.newrelic.prometheus:0.1.0
$
content:
$
chart_version: "1.15.4"

Step 3. Uninstall Your Old Agents

Before you can install Agent Control, you must remove the old agents from your cluster. Refer to the documentation for your existing agents for instructions on how to uninstall them.

For a Helm installation, you can use the helm uninstall command.

bash
$
$ helm uninstall <release-name> -n <namespace>

For the example above, you would run:

bash
$
$ helm uninstall nri-bundle -n newrelic

Step 4. Install Agent Control

Once your old instrumentation is uninstalled, you are ready to install Agent Control with your new configuration. Follow the remaining installation steps included in the guided install.

For a Helm installation, you would typically run:

bash
$
$ helm upgrade --install agent-control-bootstrap -n newrelic newrelic/agent-control-bootstrap --create-namespace --values my_migrated_values.yaml

Linux migration

When the newrelic-agent-control package is installed on the same host as the infrastructure agent, it will replace the existing newrelic-infra package and (optionally) migrate existing configurations to be compatible with Agent Control.

To upgrade your infrastructure agent to Agent Control:

  1. Complete the install steps to deploy the new agent. The agent will automatically replace the existing infrastructure agent package in your host.
  2. Determine the data source for host monitoring. You have two options: keep New Relic agents, or migrate to OpenTelemetry as the main data source for host metrics and logs.
  • Infrastructure agent: If you'd like to keep the infrastructure agent as the data source for host monitoring (CPU, Memory, Disk and Network telemetry), no change is required.
  • OpenTelemetry collector: To change to the OpenTelemetry collector as the data source, you'll need to set the following configurations to hostreceiver:
    1. Set the is_integrations_only: true value in the infrastructure agent configuration file to disable host monitoring metrics.
    2. Remove active logging configurations (*.yml files) from the /etc/newrelic-infra/logging.d folder.
    3. Ensure hostreceiver and filelogreceiver are properly configured in the OpenTelemetry collector configuration and included in the metrics pipeline.
    4. Restart the newrelic-agent-control service to load the new configurations.

No further changes are needed in order to keep backward compatibility with existing integrations configured in the host, and custom dashboards and alerts should not be impacted. All default paths remain unchanged for the infrastructure agent.

Copyright © 2025 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.