How do I repoint a Cribl Edge node to a different Cribl leader?

Objective

Switch an existing Cribl Edge node from one Cribl leader (for example, an AMER Cribl.Cloud instance) to a different Cribl leader (for example, an EMEA or APAC Cribl.Cloud instance) without reinstalling the agent, in a way that can be scripted for many nodes.

Environment

• Cribl Edge nodes deployed as managed Edge (mode-managed-edge)
• One or more Cribl leaders (for example, regional Cribl.Cloud instances such as <amer-org>.cribl.cloud, <emea-org>.cribl.cloud, <apac-org>.cribl.cloud)
• Access to each Edge node host to run CLI commands and/or edit the node's instance.yml configuration and restart the Cribl Edge service

Procedure

You can repoint an existing Cribl Edge node to a different leader using either the leader-provided CLI script (recommended) or a manual instance.yml update.

Use the leader-provided CLI script (recommended)

1. Generate the CLI script from the target leader

   1. In the target leader (where you want the Edge node to connect), go to the Edge nodes view and choose Add/Update Edge Node.

   2. Select the correct platform (for example, Linux, Windows, Kubernetes, Docker) and the fleet you want the node to join.

   3. Copy the generated CLI script or command, which includes the leader hostname, port, fleet or group name, authentication token, and the appropriate mode-managed-edge flags for that platform.

2. Run the script on the existing Edge node

   1. Log in to the Edge node host with an account that can run the script as root or an administrator.

   2. Paste and run the script you copied from the leader UI.

   3. Allow the script to complete so it updates the node's leader URL, fleet or group, and token, and restarts the Cribl Edge service so the node checks in with the new leader.

3. Verify the node has moved to the new leader

   1. In the target leader UI, open the Edge nodes view for the selected fleet.

   2. Confirm that the node appears, shows a healthy or connected status, and is sending metrics or logs as expected.

   3. In the original leader, ensure the node is no longer active and clean up any stale entries if needed.

4. Automate this procedure for multiple nodes

   • Use your configuration management or orchestration tooling (for example, Ansible, SCCM, shell scripts, PowerShell) to distribute and run the leader-provided script across many hosts.

   • Parameterize parts of the command (such as fleet and token) via variables or templates as needed.

Update instance.yml directly (alternative)

1. Collect the target leader's settings

   1. In the target leader, generate an Edge bootstrap command for the appropriate fleet.

   2. From that command, record the leader hostname, port, fleet name, and authentication token.

2. Back up the existing node configuration

   1. On the Edge node host, go to the Cribl Edge installation directory.

   2. Locate the node's instance.yml file (commonly under a local configuration directory such as local/instance.yml).

   3. Create a backup copy so that you can revert if needed (for example, cp instance.yml instance.yml.bak on Linux).

3. Stop the Cribl Edge service

   • On Linux, stop the service using your service manager (for example, sudo systemctl stop cribl-edge or sudo systemctl stop cribl).

   • On Windows, stop the Cribl Edge service from the Services UI or with the appropriate PowerShell command (for example, Stop-Service -Name Cribl).

4. Edit instance.yml to point to the new leader

   1. Open instance.yml with a text editor using appropriate privileges.

   2. Find the distributed settings for the leader connection (leader URL, port, fleet or group, and token).

   3. Update these values to the new leader information, for example:

      • Leader URL / host: tls://<new-leader-hostname>:<port>

      • Fleet or group: <fleet-name>

      • Auth token: <auth-token>

   4. Save the updated instance.yml.

5. Restart the Cribl Edge service

   • On Linux, start the service again using your service manager (for example, sudo systemctl start cribl-edge or sudo systemctl start cribl).

   • On Windows, start the Cribl Edge service from the Services UI or with the appropriate PowerShell command (for example, Start-Service -Name Cribl).

6. Confirm the node has joined the new leader

   1. In the target leader UI, open the Edge nodes view for the fleet you used.

   2. Verify the node appears, shows as connected and healthy, and is sending metrics or logs as expected.

   3. In the original leader, confirm the node is no longer active.

7. Automate this procedure for multiple nodes

   • Create a template instance.yml per target leader and fleet.

   • Use automation tools to stop the Cribl Edge service, deploy the appropriate template to each node, and restart the service.

   • Validate node membership and health in the target leader.

Additional Information

• If Edge nodes were originally configured using CRIBL_DIST_* environment variables (for example, a master URL variable) instead of instance.yml, ensure those environment variables and any related service configuration files are cleared or updated so that the CLI script or instance.yml changes are authoritative.
• The leader-provided CLI script is generally the safest and most maintainable option, because it uses a supported command shape for your exact version and platform, automatically applies the correct leader URL, port, fleet, and auth token, and reduces the chance of mis-editing instance.yml across many nodes.