Skip to content

update machine runner docs to use 3 instead of 3.0 #9317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions jekyll/_cci2/install-machine-runner-3-on-docker.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ contentTags:
- Cloud
- Server v4.4+
---
= Install machine runner 3.0 on Docker
= Install machine runner 3 on Docker
:page-layout: classic-docs
:page-description: Instructions on how to install CircleCI's self-hosted machine runner (3.0) on Docker.
:icons: font
:experimental:
:machine:
:docker:

This page describes how to install CircleCI's machine runner 3.0 with the Docker executor. If you are looking to set up self-hosted runners in a private Kubernetes cluster, visit the <<container-runner-installation#,Container runner>> page.
This page describes how to install CircleCI's machine runner 3 with the Docker executor. If you are looking to set up self-hosted runners in a private Kubernetes cluster, visit the <<container-runner-installation#,Container runner>> page.

[NOTE]
====
xref:container-runner#[Container runner] is the **recommended method** for self-hosted runner Docker installation. The instructions on this page are for a simple Docker setup using machine runner 3.0.
xref:container-runner#[Container runner] is the **recommended method** for self-hosted runner Docker installation. The instructions on this page are for a simple Docker setup using machine runner 3.

Container runner is the recommended approach for running containerized jobs on self-hosted runners. Container runner offers the ability to seamlessly define, publish, and use custom Docker images during job execution, as well as the ability to manage dependencies or libraries through custom Docker images instead of enumerating dependencies as part of `steps` in the `.circleci/config.yml` file.
====
Expand Down Expand Up @@ -46,7 +46,7 @@ include::../_includes/snippets/runner/terms.adoc[]

include::../_includes/snippets/runner/install-with-cli-steps.adoc[]

=== 2. Create a Dockerfile that extends the machine runner 3.0 image
=== 2. Create a Dockerfile that extends the machine runner 3 image

Create a `Dockerfile.runner.extended` file. In this example, Python 3 is installed on top of the base image.

Expand Down Expand Up @@ -106,16 +106,16 @@ docker stop <container-name>; docker rm <container-name>;
[#migrating-from-launch-agent]
=== Migrating from launch agent

NOTE: In machine runner 3.0, the environment variable name prefix has changed from `LAUNCH_AGENT_` to `CIRCLECI_RUNNER_`.
NOTE: In machine runner 3, the environment variable name prefix has changed from `LAUNCH_AGENT_` to `CIRCLECI_RUNNER_`.

To migrate from launch agent to machine runner 3.0 on Docker, stop and remove the launch agent containers and replace them with machine runner 3.0 containers, using the commands described above.
To migrate from launch agent to machine runner 3 on Docker, stop and remove the launch agent containers and replace them with machine runner 3 containers, using the commands described above.

include::../_includes/snippets/machine-runner-example.adoc[]

[#additional-resources]
== Additional resources

- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3.0 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3.0 macOS Homebrew installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3.0 Windows installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3 macOS Homebrew installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3 Windows installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
14 changes: 7 additions & 7 deletions jekyll/_cci2/install-machine-runner-3-on-linux.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ contentTags:
- Cloud
- Server v4.4+
---
= Install machine runner 3.0 on Linux
= Install machine runner 3 on Linux
:page-layout: classic-docs
:page-description: Instructions on how to install CircleCI's self-hosted machine runner (3.0) on Linux.
:icons: font
:experimental:
:machine:
:linux:

This page describes how to install CircleCI's machine runner 3.0 on Linux.
This page describes how to install CircleCI's machine runner 3 on Linux.

[#prerequisites]
== Prerequisites
Expand Down Expand Up @@ -78,8 +78,8 @@ Refer to the <<troubleshoot-self-hosted-runner#machine-runner,Troubleshoot Machi
[#additional-resources]
== Additional resources

- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3.0 macOS Homebrew installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3.0 Windows installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3.0 Docker installation]
- xref:machine-runner-3-manual-installation.adoc[Manual installation for machine runner 3.0]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3 macOS Homebrew installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3 Windows installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3 Docker installation]
- xref:machine-runner-3-manual-installation.adoc[Manual installation for machine runner 3]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
26 changes: 13 additions & 13 deletions jekyll/_cci2/install-machine-runner-3-on-macos.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ contentTags:
- Cloud
- Server v4.4+
---
= Install machine runner 3.0 on macOS
= Install machine runner 3 on macOS
:page-layout: classic-docs
:page-description: Instructions on how to install CircleCI's self-hosted machine runner (3.0) on macOS.
:icons: font
:experimental:
:machine:
:macOS:

This page describes how to install CircleCI's machine runner 3.0 on macOS.
This page describes how to install CircleCI's machine runner 3 on macOS.

[#prerequisites]
== Prerequisites
Expand Down Expand Up @@ -115,7 +115,7 @@ api:
mv /Library/Preferences/com.circleci.runner/launch-agent-config.yaml $HOME/Library/Preferences/com.circleci.runner/config.yaml
----

After copying the file, you may remove the logging block to send logs to the default location for machine runner 3.0 (specified below):
After copying the file, you may remove the logging block to send logs to the default location for machine runner 3 (specified below):

[,yaml]
----
Expand Down Expand Up @@ -154,9 +154,9 @@ sudo xattr -r -d com.apple.quarantine "$(brew --prefix)/bin/circleci-runner"
----

[#start-macos-machine-runner]
== 4. Start macOS machine runner 3.0
== 4. Start macOS machine runner 3

To start the macOS machine runner 3.0 for the first time, you will need to bootstrap the service. Depending on whether you are using a GUI or non-GUI session (for example, when remotely tunneling into the machine), the commands to bootstrap the service will differ:
To start the macOS machine runner 3 for the first time, you will need to bootstrap the service. Depending on whether you are using a GUI or non-GUI session (for example, when remotely tunneling into the machine), the commands to bootstrap the service will differ:

[.tab.startdomain.GUI_domain]
--
Expand Down Expand Up @@ -205,7 +205,7 @@ launchctl print user/$(id -u)/com.circleci.runner
include::../_includes/snippets/machine-runner-example.adoc[]

[#stop-macos-machine-runner]
== Stop macOS machine runner 3.0
== Stop macOS machine runner 3

To stop the machine runner service, run the following command to disable the machine runner service, depending on the service target used in the previous step:

Expand All @@ -227,8 +227,8 @@ launchctl disable user/$(id -u)/com.circleci.runner
--

[#uninstall-machine-runner-macos]
== Uninstall machine runner 3.0 on macOS
To uninstall machine runner 3.0 from your macOS device, follow these steps.
== Uninstall machine runner 3 on macOS
To uninstall machine runner 3 from your macOS device, follow these steps.

. Stop the machine runner service by using the following command to disable it, depending on the service target used during installation:
+
Expand Down Expand Up @@ -286,8 +286,8 @@ $HOME/Library/Logs/com.circleci.runner/runner.log
[#additional-resources]
== Additional resources

- xref:machine-runner-3-manual-installation.adoc[Manual installation for machine runner 3.0]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3.0 Linux package installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3.0 Windows installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3.0 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:machine-runner-3-manual-installation.adoc[Manual installation for machine runner 3]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3 Linux package installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3 Windows installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
16 changes: 8 additions & 8 deletions jekyll/_cci2/install-machine-runner-3-on-windows.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ contentTags:
- Cloud
- Server v4.4+
---
= Install machine runner 3.0 on Windows
= Install machine runner 3 on Windows
:page-layout: classic-docs
:page-description: Instructions on how to install CircleCI's machine runner 3.0 on Windows.
:page-description: Instructions on how to install CircleCI's machine runner 3 on Windows.
:icons: font
:experimental:
:machine:
:windows:

This page describes how to install CircleCI's machine runner 3.0 on Windows. This has been tested for Windows Server 2016, 2019, and 2022 in Datacenter Edition. Other Server SKUs with Desktop Experience and Remote Desktop Services (RDS) should also work.
This page describes how to install CircleCI's machine runner 3 on Windows. This has been tested for Windows Server 2016, 2019, and 2022 in Datacenter Edition. Other Server SKUs with Desktop Experience and Remote Desktop Services (RDS) should also work.

This page walks you through installing a machine runner and its dependencies (for example, Chocolatey, Git, and Gzip) on your Windows Server.

Expand Down Expand Up @@ -104,8 +104,8 @@ Refer to the <<troubleshoot-self-hosted-runner#machine-runner,Troubleshoot Machi
[#additional-resources]
== Additional resources

- xref:machine-runner-3-manual-installation-on-windows.adoc[Manual installation for machine runner 3.0 on Windows]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3.0 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3.0 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3.0 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:machine-runner-3-manual-installation-on-windows.adoc[Manual installation for machine runner 3 on Windows]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ contentTags:
- Cloud
- Server v4.4+
---
= Machine runner 3.0 configuration reference
= Machine runner 3 configuration reference
:page-layout: classic-docs
:page-liquid:
:icons: font
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,14 @@ contentTags:
- Cloud
- Server v4.4+
---
= Machine runner 3.0 manual installation for Windows
= Machine runner 3 manual installation for Windows
:page-layout: classic-docs
:page-description: Instructions on how to manually install CircleCI's self-hosted machine runner 3.0 on Windows.
:page-description: Instructions on how to manually install CircleCI's self-hosted machine runner 3 on Windows.
:icons: font
:machine:
:Windows:

This page describes how to manually install CircleCI's machine runner 3.0 on Windows Server.
This page describes how to manually install CircleCI's machine runner 3 on Windows Server.

[#prerequisites]
== Prerequisites
Expand Down Expand Up @@ -90,8 +90,8 @@ logging:
[#additional-resources]
== Additional resources

- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3.0 Windows installation]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3.0 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3.0 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3.0 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3 Windows installation]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3 Docker installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
20 changes: 10 additions & 10 deletions jekyll/_cci2/machine-runner-3-manual-installation.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,22 +4,22 @@ contentTags:
- Cloud
- Server v4.4+
---
= Machine runner 3.0 manual installation
= Machine runner 3 manual installation
:page-layout: classic-docs
:page-description: Instructions on how to manually start CircleCI's self-hosted machine runner 3.0 on macOS and Linux.
:page-description: Instructions on how to manually start CircleCI's self-hosted machine runner 3 on macOS and Linux.
:icons: font
:experimental:
:machine:
:macOS:
:linux:

This page describes how to manually start CircleCI's machine runner 3.0 on macOS and Linux.
This page describes how to manually start CircleCI's machine runner 3 on macOS and Linux.

CAUTION: We recommend installing and using CircleCI machine runner 3.0 with xref:install-machine-runner-3-on-macos.adoc[the Homebrew package] on macOS and xref:install-machine-runner-3-on-linux.adoc[the Linux packages] on Linux. The manual method described on this page is an optional alternative.
CAUTION: We recommend installing and using CircleCI machine runner 3 with xref:install-machine-runner-3-on-macos.adoc[the Homebrew package] on macOS and xref:install-machine-runner-3-on-linux.adoc[the Linux packages] on Linux. The manual method described on this page is an optional alternative.

CAUTION: Only a single machine runner per machine instance is supported by CircleCI

WARNING: If you follow this manual installation method, CircleCI machine runner 3.0 will not automatically update.
WARNING: If you follow this manual installation method, CircleCI machine runner 3 will not automatically update.

[#prerequisites]
== Prerequisites
Expand Down Expand Up @@ -136,8 +136,8 @@ $HOME/circleci-runner machine --config $HOME/circleci-runner-config.yaml
[#additional-resources]
== Additional resources

- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3.0 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3.0 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3.0 Docker installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3.0 Windows installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:install-machine-runner-3-on-linux.adoc[Machine runner 3 Linux package installation]
- xref:install-machine-runner-3-on-macos.adoc[Machine runner 3 macOS Homebrew installation]
- xref:install-machine-runner-3-on-docker.adoc[Machine runner 3 Docker installation]
- xref:install-machine-runner-3-on-windows.adoc[Machine runner 3 Windows installation]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,20 @@ contentTags:
- Cloud
- Server v4.4+
---
= Migrate from launch agent to machine runner 3.0 on Linux
= Migrate from launch agent to machine runner 3 on Linux
:page-layout: classic-docs
:page-liquid:
:page-description: Steps to migrate from using launch agent to machine runner 3.0
:page-description: Steps to migrate from using launch agent to machine runner 3
:icons: font
:toc: macro
:toc-title:
:experimental:
:machine:
: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.
This page describes how to migrate an existing launch agent installation to machine runner 3. Machine runner 3 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
Migrating from launch agent to machine runner 3 is a straightforward process. The prerequisites remain the same. First, uninstall and remove launch agent, then, install the machine runner 3 agent. The configuration file is 1:1 compatible between the agents so no modifications are needed during the migration

[#uninstall-launch-agent]
== 1. Uninstall launch agent
Expand Down Expand Up @@ -54,7 +54,7 @@ sudo semodule -r circleci_launch_agent

[#install-machine-agent]
== 2. Install the machine agent
. Follow the instructions provided in xref:install-machine-runner-3-on-linux#[Install machine runner 3.0 on Linux] to install machine runner 3.0 using the provided packages.
. Follow the instructions provided in xref:install-machine-runner-3-on-linux#[Install machine runner 3 on Linux] to install machine runner 3 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 the `apt` package to update the agent package, you will need to clear the configuration file modified prompt. This can be avoided using the `--force-confold` flag or by removing the modified configuration file before upgrading.
+
Expand All @@ -68,5 +68,5 @@ sudo systemctl start circleci-runner
[#additional-resources]
== Additional resources

- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3.0 configuration reference]
- xref:machine-runner-3-manual-installation.adoc[Machine runner 3.0 manual installation reference]
- xref:machine-runner-3-configuration-reference.adoc[Machine runner 3 configuration reference]
- xref:machine-runner-3-manual-installation.adoc[Machine runner 3 manual installation reference]
Loading