Migrate from launch agent to machine runner 3.0 on Linux
This page describes how to migrate an existing launch agent installation to machine runner 3.0. Machine runner 3.0 includes improved network resiliency, and a simpler installation management strategy, utilizing operating system packages.
Migrating from launch agent to machine runner 3.0 is a straightforward process. The prerequisites remain the same. First, uninstall and remove launch agent, then, install the machine runner 3.0 agent. The configuration file is 1:1 compatible between the agents so no modifications are needed during the migration
1. Uninstall launch agent
The first step is to uninstall launch agent. The exact process depends on the platform, as described in the following sections.
-
If the agent has been installed as a
systemdservice, run the following commands to stop and uninstall the service unit, and delete the service file (the new agent will install a new service unit):sudo systemctl stop circleci.service sudo systemctl disable circleci.service sudo rm /usr/lib/systemd/system/circleci.service -
The launch agent binary can now be removed from the machine. The default install location is
/opt/circleci/circleci-launch-agent, but this may differ on your machine if the agent was installed somewhere else. The entire/opt/circlecisubdirectory can be removed at this point. -
Finally, move the agent configuration file. The default location for this is
/etc/opt/circleci/launch-agent-config.yaml. Move the file to/etc/circleci-runner/circleci-runner-config.yamlusing the following command:mv /etc/opt/circleci/launch-agent-config.yaml /etc/circleci-runner/circleci-runner-config.yamlAlternatively, you can let the machine agent install process create a config file template and copy the existing config into the newly created file.
RHEL/Rocky Linux
In addition to the steps listed above, the SELinux policy should be uninstalled using the following command:
sudo semodule -r circleci_launch_agent2. Install the machine agent
-
Follow the instructions provided in Install machine runner 3.0 on Linux to install machine runner 3.0 using the provided packages.
-
The packages create template configuration files at
/etc/circleci-runner/circleci-runner-config.yaml. This configuration is 1:1 compatible with the launch agent configuration, apart from the auto-update feature. Since auto-update has been removed from the new agent, you should use the appropriate package management update tools to get new versions of the package when they are released. When using theaptpackage to update the agent package, you will need to clear the configuration file modified prompt. This can be avoided using the--force-confoldflag or by removing the modified configuration file before upgrading.Once the configuration file has been populated, the following command will restart the agent so it can begin claiming:
sudo systemctl enable circleci-runner sudo systemctl start circleci-runner