From bd504a126eafbbf7c85762c7b62a71517e4ee4eb Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Mon, 29 Sep 2025 13:53:36 -0400 Subject: [PATCH 1/2] [Fleet] Add docs for using Fleet to migrate multiple agents --- reference/fleet/migrate-elastic-agent.md | 28 +++++++++++++++++++----- 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/reference/fleet/migrate-elastic-agent.md b/reference/fleet/migrate-elastic-agent.md index 0af54ba1ec..ec0bff7f8d 100644 --- a/reference/fleet/migrate-elastic-agent.md +++ b/reference/fleet/migrate-elastic-agent.md @@ -179,7 +179,6 @@ After the restart, {{integrations-server}} will enroll a new {{agent}} for the { :::: - ### Confirm your policy settings [migrate-elastic-agent-confirm-policy] Now that the {{fleet}} settings are correctly set up, it pays to ensure that the {{agent}} policy is also correctly pointing to the correct entities. @@ -200,7 +199,6 @@ If you modified the {{fleet-server}} and the output in place these would have be :::: - ## Agent policies in the new target cluster [migrate-elastic-agent-migrated-policies] By creating the new target cluster from a snapshot, all of your policies should have been created along with all of the agents. These agents will be offline due to the fact that the actual agents are not checking in with the new, target cluster (yet) and are still communicating with the source cluster. @@ -210,7 +208,11 @@ The agents can now be re-enrolled into these policies and migrated over to the n ## Migrate {{agent}}s to the new target cluster [migrate-elastic-agent-migrated-agents] -In order to ensure that all required API keys are correctly created, the agents in your current cluster need to be re-enrolled into the new, target cluster. +::::{note} +Agents to be migrated cannot be tamper-protected or running as a {{fleet}} server. +:::: + +In order to ensure that all required API keys are correctly created, the agents in your current cluster need to be re-enrolled into the new target cluster. This is best performed one policy at a time. For a given policy, you need to capture the enrollment token and the URL for the agent to connect to. You can find these by running the in-product steps to add a new agent. @@ -224,13 +226,26 @@ This is best performed one policy at a time. For a given policy, you need to cap :screenshot: ::: +::::{tab-set} +:::{tab-item} 9.2.0 + +**For 9.2.0 and later, you can migrate remote agents directly from the {{fleet}} UI, eliminating the need to run commands on each individual host.** + +5. In the source cluster, select the agents you want to migrate. Click the three dots next to the agents, and select **Migrate agents**. +6. In the migration dialog, provide the URI and enrollment token you obtained from the target cluster. +7. Use replace_token (Optional): When you are migrating a single agent, you can use the `replace_token` field to preserve the agent's original ID from the source cluster. This step helps with event matching, but will cause the migration to fail if the target cluster already has an agent with the same ID. +::: + +:::{tab-item} 9.1.0 +**On 9.1.0 and earlier, you need to run commands on each individual host.** + 5. On the host machines where the current agents are installed, enroll the agents again using this copied URL and the enrollment token: ```shell sudo elastic-agent enroll --url= --enrollment-token= ``` - The command output should be like the following: + The command output should resemble this: :::{image} images/migrate-agent-install-command-output.png :alt: Install command output @@ -245,6 +260,7 @@ This is best performed one policy at a time. For a given policy, you need to cap ::: 7. Repeat this procedure for each {{agent}} policy. +::: +:::: -If all has gone well, you’ve successfully migrated your {{fleet}}-managed {{agent}}s to a new cluster. - +If all has gone well, you’ve successfully migrated your {{fleet}}-managed {{agent}}s to a new cluster. \ No newline at end of file From ebfcbfe759b2a53bfc9a7ea1954416092aa80f72 Mon Sep 17 00:00:00 2001 From: Karen Metts Date: Tue, 28 Oct 2025 19:58:21 -0400 Subject: [PATCH 2/2] Rework versioned content --- reference/fleet/migrate-elastic-agent.md | 57 +++++++++++++----------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/reference/fleet/migrate-elastic-agent.md b/reference/fleet/migrate-elastic-agent.md index ec0bff7f8d..84210893fc 100644 --- a/reference/fleet/migrate-elastic-agent.md +++ b/reference/fleet/migrate-elastic-agent.md @@ -226,41 +226,44 @@ This is best performed one policy at a time. For a given policy, you need to cap :screenshot: ::: -::::{tab-set} -:::{tab-item} 9.2.0 +5. Choose an approach: -**For 9.2.0 and later, you can migrate remote agents directly from the {{fleet}} UI, eliminating the need to run commands on each individual host.** + ::::{tab-set} + :::{tab-item} Fleet UI -5. In the source cluster, select the agents you want to migrate. Click the three dots next to the agents, and select **Migrate agents**. -6. In the migration dialog, provide the URI and enrollment token you obtained from the target cluster. -7. Use replace_token (Optional): When you are migrating a single agent, you can use the `replace_token` field to preserve the agent's original ID from the source cluster. This step helps with event matching, but will cause the migration to fail if the target cluster already has an agent with the same ID. -::: + {applies_to}`stack: ga 9.2` Migrate remote agents directly from the {{fleet}} UI: -:::{tab-item} 9.1.0 -**On 9.1.0 and earlier, you need to run commands on each individual host.** + 1. In the source cluster, select the agents you want to migrate. Click the three dots next to the agents, and select **Migrate agents**. + 2. In the migration dialog, provide the URI and enrollment token you obtained from the target cluster. + 3. Use replace_token (Optional): When you are migrating a single agent, you can use the `replace_token` field to preserve the agent's original ID from the source cluster. This step helps with event matching, but will cause the migration to fail if the target cluster already has an agent with the same ID. + ::: -5. On the host machines where the current agents are installed, enroll the agents again using this copied URL and the enrollment token: + :::{tab-item} Command line - ```shell - sudo elastic-agent enroll --url= --enrollment-token= - ``` + Run the `enroll` command on each individual host: - The command output should resemble this: + 1. On the host machines where the current agents are installed, enroll the agents again using this copied URL and the enrollment token: - :::{image} images/migrate-agent-install-command-output.png - :alt: Install command output - :screenshot: - ::: + ```shell + sudo elastic-agent enroll --url= --enrollment-token= + ``` -6. The agent on each host will now check into the new {{fleet-server}} and appear in the new target cluster. In the source cluster, the agents will go offline as they won’t be sending any check-ins. + The command output should resemble this: - :::{image} images/migrate-agent-newly-enrolled-agents.png - :alt: Newly enrolled agents in the target cluster - :screenshot: - ::: + :::{image} images/migrate-agent-install-command-output.png + :alt: Install command output + :screenshot: + ::: -7. Repeat this procedure for each {{agent}} policy. -::: -:::: + 2. The agent on each host will now check into the new {{fleet-server}} and appear in the new target cluster. In the source cluster, the agents will go offline as they won’t be sending any check-ins. + + :::{image} images/migrate-agent-newly-enrolled-agents.png + :alt: Newly enrolled agents in the target cluster + :screenshot: + ::: + + 3. Repeat this procedure for each {{agent}} policy. + ::: + :::: -If all has gone well, you’ve successfully migrated your {{fleet}}-managed {{agent}}s to a new cluster. \ No newline at end of file +If all has gone well, you’ve successfully migrated your {{fleet}}-managed {{agent}}s to a new cluster.