Manage existing instrumentation with Agent Control

Kubernetes migration

If your Kubernetes cluster is already instrumented with New Relic, you can transition your agents to be managed by Agent Control to use its management features. The migration process is a guided replacement of existing agent installs with Agent Control managed installs, done in a controlled sequence to maintain continuity.

Agent Control uses a unified configuration model for supported agents, ensuring you can retain the features and settings from your current Helm chart installation.

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 from the nri-bundle Helm chart, mapped to Agent Control agent types:

• newrelic-infrastructure, nri-kube-events, kube-state-metrics, and nri-kube-events: Managed as the New Relic Infrastructure agent type
• newrelic-prometheus-configurator: Managed as the New Relic Prometheus agent type
• newrelic-logging: Managed as the Fluent Bit agent type
• nr-k8s-otel-collector: Managed as 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:

$
# Find releases in a namespace (adjust as needed)
$
helm list --namespace <namespace-name>
$

$
# Get the values for a specific release
$
$ 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 Kubernetes manifests (kubectl or Kustomize), map the corresponding options in each agent chart.

Step 2. Create a New Agent Control Configuration

Create a new values.yaml file for Agent Control based on your existing configuration. This file tells Agent Control what to deploy and how to configure your agents after the migration.

1. Start the Agent Control guided installation and select the agents you need (Infrastructure, Prometheus, Logging, OpenTelemetry Collector).
2. Download the values.yaml file to your local machine.
3. Update the downloaded file to correspond with the configurations of your old agents.
4. Keep this file handy - you'll use it to deploy with Agent Control.

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:

$
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.

$
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.

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

For example, to uninstall the nri-bundle, you would run:

$
$ 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 installation.

For a Helm installation, you would typically run:

$
$ 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 Agent Control package. The Agent Control package will automatically replace the existing infrastructure agent on 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.