--- title: Migration guide source: https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide --- This guide covers the most common questions and pitfalls when moving from a standalone agent installation to agents managed by Agent Control and Fleet Control. ## Before you start: the monitoring gap ### On Host > #### ⚠️ CAUTION > > **Installing Agent Control removes the standalone Infrastructure Agent.** > > The OS package that installs Agent Control removes or stops the previously installed Infrastructure Agent. From that moment, the host has no running agent until Agent Control connects to Fleet Control, receives the deployment configuration, and successfully starts the Infrastructure Agent as a managed sub-agent. **Do not install Agent Control on a host until all of the following are true:** 1. Fleet Control has a deployment with an Infrastructure Agent targeting that host whose config has similar settings to your existing `newrelic-infra.yml` and `integrations.d/` files. Refer to [Configuration migration](#configuration-migration) for how to translate each piece. 2. You have validated the deployment config on at least one non-production host first. 3. Agent Control can reach the Fleet Control endpoint and the OCI registry from the target host. Check firewall rules and proxy settings in advance. 4. You have the rollback steps ready in case the deployment does not come up. Refer to [Rollback](#rollback). The gap between Agent Control installation and the first successful managed agent start is typically a few seconds when everything is configured correctly. ### Kubernetes > #### ⚠️ CAUTION > > **Migration requires uninstalling existing agents before installing Agent Control.** > > Unlike hosts where the Agent Control installer replaces the existing agent, on Kubernetes you manually uninstall the old agents first. There is a gap in monitoring from the moment you run `helm uninstall` until Agent Control connects to Fleet Control and applies your remote configuration. **Do not uninstall your existing agents until all of the following are true:** 1. You have saved your existing Helm values: `helm get values RELEASE_NAME --namespace NAMESPACE`. These are your rollback point. 2. Fleet Control has remote configurations ready for each agent type you are migrating. Refer to [Configuration migration](#configuration-migration) for how to map Helm values to Fleet Control configs. 3. Agent Control can reach the Fleet Control endpoint and the OCI registry from your cluster nodes. Check network policies and egress rules in advance. 4. You have the rollback steps ready in case the deployment does not come up. Refer to [Rollback](#rollback). ## Migrate a previously instrumented system > #### ⚠️ IMPORTANT > > Agent Control does not support automatic migration of existing agents. Migration is always a manual process: uninstall the existing agent, install Agent Control, then recreate your configuration as a Fleet Control remote configuration. > #### ⚠️ MONITORING GAP ON LINUX AND WINDOWS HOSTS > > Installing Agent Control on a host **removes the standalone Infrastructure Agent**. Expect a temporary loss of telemetry from the moment the old agent stops until Agent Control connects to Fleet Control and starts the managed agent. Prepare and validate your Fleet Control deployment config on a non-production host before migrating production. For full details including rollback steps, refer to the [host migration guide](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide). ### General migration process Regardless of platform, the migration follows these four steps: 1. **Note your existing configuration.** Save a copy of all agent config files and integration configs before uninstalling anything. You will recreate them as Fleet Control remote configurations. 2. **Uninstall the existing agent.** Agent Control cannot coexist with a standalone agent installation of the same type. 3. **Install Agent Control and connect to a fleet.** Follow the platform-specific installation guide and select an existing fleet or create a new one. 4. **Recreate your configuration in Fleet Control.** Create a remote configuration for your fleet with your previous settings. Agent Control will apply it automatically. > #### ⚠️ REMOTE CONFIGURATION ALWAYS WINS > > Fleet Control is the authoritative source for agent configuration. Any agent settings, versions, chart values, and resource limits, must be defined in the Fleet Control remote configuration, not in the local installation file. If both exist, the remote configuration takes precedence and will override any local values. > #### 💡 BEST PRACTICES > > To ensure data continuity, use the same entity name (cluster name or hostname) and the same New Relic account during Agent Control installation. Entity GUIDs are tied to these attributes, not to how the agent is managed. Refer to [entity continuity and dashboards](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide#entity-continuity-and-dashboards) for details. You can leave any agents or components not yet supported by Agent Control in place until support is available. ### Kubernetes If your Kubernetes cluster is already instrumented with New Relic, you can transition your agents to be managed by Agent Control. The migration process removes existing agent installs and replaces them with Agent Control-managed installs, configured centrally through Fleet Control. Agent Control can deploy and manage the following agents from the `nri-bundle` Helm chart: - `newrelic-infrastructure`, `nri-kube-events`, and `kube-state-metrics`: managed as the **Infrastructure agent** type - `newrelic-prometheus-configurator`: managed as the **Prometheus** agent type - `newrelic-logging`: managed as the **Fluent Bit** agent type - `nr-k8s-otel-collector`: managed as the **OpenTelemetry Collector** agent type 1. **Retrieve your existing configuration.** If you installed agents using Helm, retrieve your installation config from the cluster: ```sh # Find releases in the namespace helm list --namespace # Get the values for a specific release helm get values --namespace ``` If you have the original configuration file saved from the installation, use that directly. If you instrumented the cluster via Kubernetes manifests (kubectl or Kustomize), note the options set for each agent — you will recreate them as Fleet Control remote configurations. 2. **Uninstall your old agents.** Before installing Agent Control, remove the old agents from your cluster. For a Helm installation: ```shell helm uninstall -n ``` For example, to uninstall the `nri-bundle`: ```shell helm uninstall nri-bundle -n newrelic ``` 3. **Install Agent Control.** Start the [Agent Control guided installation](https://docs.newrelic.com/docs/new-relic-control/agent-control/setup/) and download the generated `values.yaml`. This file contains only the Agent Control supervisor configuration (credentials, fleet ID, and which agent types to manage) — **do not add agent-specific chart values here**. Those belong in the Fleet Control remote configuration. ```shell helm upgrade --install agent-control-bootstrap -n newrelic newrelic/agent-control-bootstrap --create-namespace --values my_values.yaml ``` 4. **Recreate your agent configuration in Fleet Control.** After Agent Control connects to Fleet Control, [create the configurations](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-3-create-an-agent-configuration) for each of your old agents with your previous settings. 5. **Create a new deployment** adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your cluster. Follow these steps in [create and run your first deployment](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-4-create-and-run-your-first-deployment). 6. **Verify data is flowing.** Navigate to **Infrastructure > Kubernetes** in the New Relic UI. Your cluster should appear within 1–2 minutes of the remote configuration being applied. If it does not appear, refer to [Agent Control troubleshooting](https://docs.newrelic.com/docs/new-relic-control/agent-control/troubleshooting). ### Linux > #### ⚠️ IMPORTANT > > Agent Control does not support automatic migration of existing agents on Linux. If you have the New Relic Infrastructure Agent already installed on your Linux host, you must uninstall it manually before installing Agent Control. Agent Control distributes agents via OCI-compliant packages through Fleet Control — it does not replace or inherit the existing `newrelic-infra` package installation. 1. **Note your existing configuration** Before uninstalling, save a copy of: - Your agent configuration: `/etc/newrelic-infra/newrelic-infra.yml` - Any on-host integration configs: `/etc/newrelic-infra/integrations.d/` You will recreate these as Fleet Control remote configurations in Step 4. For how each config file and setting maps to the Fleet Control format, refer to [Configuration migration](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide#configuration-migration). 2. **Uninstall the existing Infrastructure Agent** #### Debian, Ubuntu ````bash sudo apt-get remove newrelic-infra -y ``` ```` #### SLES ````bash sudo zypper -n remove newrelic-infra ``` ```` #### Amazon Linux, CentOS, RHEL ````bash sudo yum remove newrelic-infra -y ``` ```` 3. **Install Agent Control.** Follow the [Linux installation guide](https://docs.newrelic.com/docs/new-relic-control/agent-control/setup/). Ensure you select or create a fleet of type **Host - Linux**. 4. **Recreate your agent configuration in Fleet Control.** After Agent Control connects to Fleet Control, [create the configurations](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-3-create-an-agent-configuration) for each of your old agents with your previous settings. Use your saved config files from Step 1 as a reference. Refer to [Configuration migration](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide#configuration-migration) for how each setting maps to the Fleet Control format. 5. **Create a new deployment** adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your host, download and install the OCI packages for each of the agents. Follow these steps in [create and run your first deployment](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-4-create-and-run-your-first-deployment). 6. **Verify data is flowing.** Navigate to **Infrastructure > Hosts** in the New Relic UI. Your host should appear within 1–2 minutes. If it does not appear, refer to [Agent Control troubleshooting](https://docs.newrelic.com/docs/new-relic-control/agent-control/troubleshooting). Custom dashboards and alerts referencing data from the Infrastructure Agent will continue to work as long as you use the same account and host name. Entity GUIDs are derived from hostname and account, not from how the agent is managed. For a detailed explanation and rollback steps, refer to the [host migration guide](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide). ### Windows > #### ⚠️ IMPORTANT > > Agent Control does not support automatic migration of existing agents on Windows. If you have the New Relic Infrastructure Agent already installed on your Windows host, you must uninstall it manually before installing Agent Control. APM agents are not managed by Agent Control and can remain installed. 1. **Note your existing configuration** Before uninstalling, save a copy of: - Your agent configuration: `C:\Program Files\New Relic\newrelic-infra\newrelic-infra.yml` - Any on-host integration configs: `C:\Program Files\New Relic\newrelic-infra\integrations.d\` You will recreate these as Fleet Control remote configurations in Step 4. For how each config file and setting maps to the Fleet Control format, refer to [Configuration migration](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide#configuration-migration). 2. **Uninstall the existing Infrastructure Agent** Open **Add or Remove Programs** and uninstall the New Relic Infrastructure Agent. Alternatively, use the MSI uninstaller from PowerShell: ```powershell # Replace {PRODUCT_CODE} with the GUID from Add/Remove Programs msiexec /x {PRODUCT_CODE} /quiet ``` 3. **Install Agent Control.** Follow the [Windows installation guide](https://docs.newrelic.com/docs/new-relic-control/agent-control/setup/). Ensure you select or create a fleet of type **Host - Windows**. 4. **Recreate your agent configuration in Fleet Control.** After Agent Control connects to Fleet Control, [create the configurations](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-3-create-an-agent-configuration) for each of your old agents with your previous settings. Use your saved config files from Step 1 as a reference. Refer to [Configuration migration](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide#configuration-migration) for how each setting maps to the Fleet Control format. 5. **Create a new deployment** adding the just-created remote configurations to your fleet. Agent Control will automatically apply the new configuration to your host, download and install the OCI packages for each of the agents. Follow these steps in [create and run your first deployment](https://docs.newrelic.com/docs/new-relic-control/fleet-control/setup/#step-4-create-and-run-your-first-deployment). 6. **Verify data is flowing.** Navigate to **Infrastructure > Hosts** in the New Relic UI. Your host should appear within 1–2 minutes. If it does not appear, refer to [Agent Control troubleshooting](https://docs.newrelic.com/docs/new-relic-control/agent-control/troubleshooting). Custom dashboards and alerts referencing data from the Infrastructure Agent will continue to work as long as you use the same account and host name. Entity GUIDs are derived from hostname and account, not from how the agent is managed. For a detailed explanation and rollback steps, refer to the [host migration guide](https://docs.newrelic.com/docs/new-relic-control/agent-control/migration-guide). ## Entity continuity and dashboards **Your existing dashboards, alerts, and workloads keep working without any changes.** ### On Host New Relic entity GUIDs are derived from stable attributes (primarily the hostname, CloudInstanceId, the account ID, and the integration identity) not from how the agent was installed or what is supervising its process. When Agent Control starts the Infrastructure Agent on the same host with the same configuration, the agent reports the same attributes it always did. New Relic resolves those attributes to the same entity GUIDs as before, so: - The host entity in the Infrastructure UI is the same entity. - On-host integration entities (MySQL, NGINX, and so on) keep their GUIDs. - Any dashboard widget, alert condition, or workload that queries or filters by those entities continues to work. - Golden signal history is preserved. There is no gap or duplication in the entity's metric timeline, provided the migration is done without a prolonged overlap or gap in agent execution. ### Kubernetes New Relic entity GUIDs for Kubernetes are derived from the cluster name and account ID, not from how agents are installed or managed. When Agent Control deploys the Infrastructure Agent on the same cluster using the same cluster name, the cluster entity and all workload entities resolve to the same GUIDs as before, so: - The cluster entity in the Kubernetes UI is the same entity. - Workload and namespace entities keep their GUIDs. - Any dashboard widget, alert condition, or workload that queries or filters by those entities continues to work. - Golden signal history is preserved, provided the gap between uninstalling old agents and Agent Control starting managed agents is kept short. ## Configuration migration Do not store secrets such as license keys, API keys, or passwords as plain text in Fleet Control configurations. Instead, reference them as environment variables using the `nr-env:` prefix: ```yaml license_key: ${nr-env:NEW_RELIC_LICENSE_KEY} ``` Agent Control automatically exposes `NEW_RELIC_LICENSE_KEY` to sub-agents, so you do not need to set `license_key` explicitly; the example above is shown for reference. Use the same pattern for any other secrets. Refer to the [variable interpolation docs](https://github.com/newrelic/newrelic-agent-control/blob/main/docs/VARIABLE_INTERPOLATION.md#nr-env--environment-variables) for the full syntax and other supported sources. ### On Host **Infrastructure Agent main config** The Infrastructure Agent main config (`newrelic-infra.yml`) maps directly to the `content` block of the Infrastructure Agent sub-agent configuration in Fleet Control. Any key accepted by `newrelic-infra.yml` is accepted there. Fields like `display_name`, `custom_attributes`, and `log` all carry over unchanged. When Agent Control manages the Infrastructure Agent, it writes the effective configuration to disk on every remote config update. The agent reads from that path. The old `newrelic-infra.yml` config remains on disk after the migration, but it's not going to be used. > #### 💡 TIP > > Do not delete `newrelic-infra.yml` or the `integrations.d/` files until you have confirmed that managed agents are reporting data correctly. Keeping the originals on disk is what makes the [rollback procedure](#rollback) possible. **On-host integrations** Each integration configuration also needs to be created in Fleet Control selecting the correct agent type. ### Kubernetes **Agent types and Helm chart mapping** Agent Control manages agents from the `nri-bundle` Helm chart as distinct agent types in Fleet Control. Each agent type has its own remote configuration: | nri-bundle component | Fleet Control agent type | | ------------------------------------------------------------------ | ------------------------ | | `newrelic-infrastructure`, `nri-kube-events`, `kube-state-metrics` | Infrastructure agent | | `newrelic-prometheus-configurator` | Prometheus | | `newrelic-logging` | Fluent Bit | | `nr-k8s-otel-collector` | OpenTelemetry Collector | **Translating Helm values to Fleet Control config** The Helm values you retrieved with `helm get values` become the body of the Fleet Control remote configuration for each agent type. For example, a `values.yaml` section for the Infrastructure agent: ````yaml newrelic-infrastructure: customAttributes: environment: production resources: limits: memory: 300Mi ``` becomes a Fleet Control remote config for the **Infrastructure agent** type with those same keys under the agent's configuration block. Refer to each agent's documentation for the accepted keys. **Secrets and license key** Do not store secrets as plain text in Fleet Control configurations. The license key is automatically propagated by Agent Control to all managed sub-agents; you do not need to set it in the remote configuration. For other secrets (API keys, passwords), use environment variable references via the `nr-env:` prefix. Refer to the [variable interpolation docs](https://github.com/newrelic/newrelic-agent-control/blob/main/docs/VARIABLE_INTERPOLATION.md#nr-env--environment-variables) for details. ```` ## Rollback If Agent Control is not working as expected after installation, you can safely return to the standalone agents at any time. ### Linux 1. Uninstall Agent Control: ```bash sudo sh /usr/lib/newrelic-agent-control/uninstall.sh ``` The script stops the service, detects the package manager, and purges all Agent Control files. 2. Reinstall the Infrastructure Agent package if it was removed. Your `newrelic-infra.yml` and `integrations.d/` files are preserved on the host as long as you did not delete them before the migration. ### Windows 1. Open PowerShell with Administrator privileges and uninstall Agent Control: ```powershell PowerShell.exe -ExecutionPolicy Bypass -File "C:\Program Files\New Relic\newrelic-agent-control\uninstall.ps1" ``` The script stops the service, removes the service registration, and deletes Agent Control files. 2. Reinstall the Infrastructure Agent using the MSI installer if it was removed. Your `newrelic-infra.yml` and `integrations.d\` files are preserved on the host as long as you did not delete them before the migration. ### Kubernetes 1. Uninstall Agent Control: ```shell helm uninstall agent-control-bootstrap -n newrelic ``` 2. Reinstall your previous agents using the Helm values you saved before the migration: ```shell helm upgrade --install nri-bundle newrelic/nri-bundle -n newrelic --values saved-values.yaml ``` **Entity continuity is preserved on rollback.** Because entity GUIDs are derived from hostname or cluster name and account (not from how the agent is managed) the host or cluster entity and all integration entities are the same ones that were reporting before. Dashboards, alerts, and workloads resume working immediately with no gaps or duplicated history visible in the UI.