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 all commits
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
22 changes: 11 additions & 11 deletions jekyll/_cci2/install-machine-runner-3-on-docker.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,21 +4,21 @@ 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.
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. Container runner also h 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.
====

[#machine-approach-with-docker]
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. The commands described above can be used to accomplish this.

include::../_includes/snippets/runner/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/runner/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]
22 changes: 11 additions & 11 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 @@ -54,7 +54,7 @@ include::../_includes/snippets/runner/install-with-cli-steps.adoc[]
[#installation-steps]
== 2. Machine runner installation on Windows

. Download the https://github.com/CircleCI-Public/runner-installation-files/tree/main/windows-install/circleci-runner[`Install-CircleCIRunner.ps1` script] from GitHub to an easily accessible location.
. Download the https://github.com/CircleCI-Public/runner-installation-files/tree/main/windows-install/circleci-runner[`Install-CircleCIRunner.ps1` script] from GitHub to an accessible location.

. Open PowerShell as an administrator and navigate to the directory where you placed the script file.

Expand All @@ -79,7 +79,7 @@ include::../_includes/snippets/runner/machine-runner-example.adoc[]

Uninstalling machine runners will prepare the system for installation again.

. Download the https://github.com/CircleCI-Public/runner-installation-files/tree/main/windows-install/circleci-runner[`Uninstall-CircleCIRunner.ps1` script] from GitHub to an easily accessible location.
. Download the https://github.com/CircleCI-Public/runner-installation-files/tree/main/windows-install/circleci-runner[`Uninstall-CircleCIRunner.ps1` script] from GitHub to an accessible location.
. Open PowerShell as an administrator and navigate to the directory where you placed the script file.

. Run the following in your PowerShell:
Expand All @@ -92,7 +92,7 @@ Uninstalling machine runners will prepare the system for installation again.
[#continuous-mode-vs.-single-task-mode-for-windows-self-hosted-runners]
== Continuous mode vs. single task mode for Windows self-hosted runners

By default, Windows machine runners run in xref:machine-runner-3-configuration-reference.adoc#runner-mode[single-task mode] in order to ensure high reliability of the underlying technology that the self-hosted runner uses to execute jobs. This is the **recommended mode** for Windows machine runners.
By default, Windows machine runners run in xref:machine-runner-3-configuration-reference.adoc#runner-mode[single-task mode] in order to ensure high reliability of the underlying technology that the self-hosted runner uses to execute jobs. Single-task mode is the **recommended mode** for Windows machine runners.

A Windows machine runner *can* be run in `continuous` mode. However, doing so eliminates the guarantee of a clean job environment. This may translate into jobs not executing as expected, and job failure.

Expand All @@ -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]
6 changes: 3 additions & 3 deletions jekyll/_cci2/machine-runner-3-configuration-reference.adoc
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 Expand Up @@ -51,7 +51,7 @@ The URL will be pointing to `https://runner.circleci.com` by default. It should

`$CIRCLECI_RUNNER_NAME`

`RUNNER_NAME` is a unique name of your choosing assigned to this particular machine runner. CircleCI recommends using the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the UI on the CircleCI web app. The only special characters accepted in `RUNNER_NAME` are `. () - _`.
`RUNNER_NAME` is a unique name of your choosing assigned to this particular machine runner. CircleCI recommends using the hostname of the machine so that it can be used to identify the agent when viewing statuses and job results in the CircleCI web app. The only special characters accepted in `RUNNER_NAME` are `. () - _`.


[#logging-level]
Expand Down Expand Up @@ -284,7 +284,7 @@ runner:
[#customizing-job-timeouts-and-drain-timeouts]
==== Customizing job timeouts and drain timeouts

If you would like to customize the job timeout setting, you can “drain” the job by sending the machine runner a termination (TERM) signal, which then causes the machine runner to attempt to gracefully shutdown. When this TERM signal is received, the machine runner enters _draining_ mode, preventing the machine runner from accepting any new jobs, but still allowing any current active job to be completed. At the end of _draining_, the machine runner then signals the task-agent to cancel any active job (by sending it a TERM signal).
If you would like to customize the job timeout setting, you can “drain” the job by sending the machine runner a termination (TERM) signal. This causes the machine runner to attempt to gracefully shutdown. When this TERM signal is received, the machine runner enters _draining_ mode. This prevents the machine runner from accepting any new jobs, but still allows any current active job to be completed. At the end of _draining_, the machine runner then signals the task-agent to cancel any active job (by sending it a TERM signal).

NOTE: If the task-agent does not exit a brief period after the TERM, the machine runner will manually kill it by sending it a KILL signal.

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]
Loading