diff options
Diffstat (limited to 'doc/ci/runners/runners_scope.md')
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 274 |
1 files changed, 256 insertions, 18 deletions
diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index e7b764025c9..840eb7fe93b 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -5,9 +5,9 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: reference --- -# The scope of runners **(FREE)** +# Manage runners -Runners are available based on who you want to have access: +GitLab Runner has the following types of runners, which are available based on who you want to have access: - [Shared runners](#shared-runners) are available to all groups and projects in a GitLab instance. - [Group runners](#group-runners) are available to all projects and subgroups in a group. @@ -24,26 +24,71 @@ multiple projects. If you are using a self-managed instance of GitLab: -- Your administrator can install and register shared runners by - going to your project's **Settings > CI/CD**, expanding **Runners**, - and selecting **Show runner installation instructions**. - These instructions are also available [in the documentation](https://docs.gitlab.com/runner/install/index.html). +- Your administrator can [install GitLab Runner](https://docs.gitlab.com/runner/install/index.html) and register a shared runner. - The administrator can also configure a maximum number of shared runner - [units of compute for each group](../pipelines/cicd_minutes.md#set-the-compute-quota-for-a-specific-namespace). + [compute minutes for each group](../pipelines/cicd_minutes.md#set-the-compute-quota-for-a-specific-namespace). If you are using GitLab.com: - You can select from a list of [shared runners that GitLab maintains](index.md). -- The shared runners consume the [units of compute](../pipelines/cicd_minutes.md) +- The shared runners consume the [compute minutes](../pipelines/cicd_minutes.md) included with your account. +### Create a shared runner with an authentication token + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383139) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_admin` [flag](../../administration/feature_flags.md) +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/389269) in GitLab 16.0. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. + +Prerequisites: + +- You must be an administrator. + +When you create a runner, it is assigned an authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. + +To create a shared runner: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **CI/CD > Runners**. +1. Select **New instance runner**. +1. Select a platform. +1. Optional. Enter configurations for the runner. +1. Select **Submit**. +1. Follow the on-screen instructions to register the runner from the command line. + +You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. + +NOTE: +The authentication token displays in the UI for only a short period of time during registration. + +### Create a shared runner with a registration token (deprecated) + +WARNING: +The ability to pass a runner registration token, and support for certain configuration arguments was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens +should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). + +Prerequisites: + +- You must be an administrator. + +To create a shared runner: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. Select **CI/CD > Runners**. +1. Select **Register an instance runner**. +1. Copy the registration token. +1. [Register the runner](https://docs.gitlab.com/runner/register/). + ### Enable shared runners for a project On GitLab.com, [shared runners](index.md) are enabled in all projects by default. On self-managed instances of GitLab, an administrator can -[enable them for all new projects](../../user/admin_area/settings/continuous_integration.md#enable-shared-runners-for-new-projects). +[enable them for all new projects](../../administration/settings/continuous_integration.md#enable-shared-runners-for-new-projects). For existing projects, an administrator must [install](https://docs.gitlab.com/runner/install/index.html) and @@ -94,10 +139,6 @@ To disable shared runners for a group: 1. Optional. To allow shared runners to be enabled for individual projects or subgroups, select **Allow projects and subgroups to override the group setting**. -NOTE: -If you re-enable the shared runners for a group after you disable them, a user with the -Owner or Maintainer role must manually change this setting for each project subgroup or project. - ### How shared runners pick jobs Shared runners process jobs by using a fair usage queue. This queue prevents @@ -143,11 +184,43 @@ to have access to a set of runners. Group runners process jobs by using a first in, first out ([FIFO](https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics))) queue. -### Create a group runner +### Create a group runner with an authentication token -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19819) in GitLab 14.10, path changed from **Settings > CI/CD > Runners**. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. + +Prerequisites: + +- You must have the Owner role for the group. You can create a group runner for your self-managed GitLab instance or for GitLab.com. +When you create a runner, it is assigned an authentication token that you use to register it. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. + +To create a group runner: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Build > Runners**. +1. Select **New group runner**. +1. Select a platform. +1. Optional. Enter configurations for the runner. +1. Select **Submit**. +1. Follow the on-screen instructions to register the runner from the command line. + +You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. + +NOTE: +The authentication token displays in the UI for only a short period of time during registration. + +### Create a group runner with a registration token (deprecated) + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/19819) in GitLab 14.10, path changed from **Settings > CI/CD > Runners**. + +WARNING: +The ability to pass a runner registration token, and support for certain configuration arguments was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens +should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). + You must have the Owner role for the group. To create a group runner: @@ -224,6 +297,48 @@ You must have the Owner role for the group. You must remove it from each project first. 1. On the confirmation dialog, select **OK**. +### Clean up stale group runners **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363012) in GitLab 15.1. + +You can clean up group runners that have been inactive for more than three months. + +Group runners are those that were created at the group level. + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. +1. Select **Settings > CI/CD**. +1. Expand **Runners**. +1. Turn on the **Enable stale runner cleanup** toggle. + +#### View stale runner cleanup logs + +You can check the [Sidekiq logs](../../administration/logs/index.md#sidekiq-logs) to see the cleanup result. In Kibana you can use the following query: + +```json +{ + "query": { + "match_phrase": { + "json.class.keyword": "Ci::Runners::StaleGroupRunnersPruneCronWorker" + } + } +} +``` + +Filter entries where stale runners were removed: + +```json +{ + "query": { + "range": { + "json.extra.ci_runners_stale_group_runners_prune_cron_worker.total_pruned": { + "gte": 1, + "lt": null + } + } + } +} +``` + ## Project runners Use _project runners_ when you want to use runners for specific projects. For example, @@ -241,9 +356,40 @@ NOTE: Project runners do not get shared with forked projects automatically. A fork *does* copy the CI/CD settings of the cloned repository. -### Create a project runner +### Create a project runner with an authentication token + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/383143) in GitLab 15.10. Deployed behind the `create_runner_workflow_for_namespace` [flag](../../administration/feature_flags.md). Disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/393919) in GitLab 16.0. +> - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/415447) in GitLab 16.2. Feature flag `create_runner_workflow_for_admin` removed. + +Prerequisites: + +- You must have the Maintainer role for the project. + +You can create a project runner for your self-managed GitLab instance or for GitLab.com. When you create a runner, it is assigned an authentication token that you use to register to the runner. The runner uses the token to authenticate with GitLab when picking up jobs from the job queue. -You can create a project runner for your self-managed GitLab instance or for GitLab.com. +To create a project runner: + +1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your project. +1. Select **Settings > CI/CD**. +1. Expand the **Runners** section. +1. Select **New project runner**. +1. Select a platform. +1. Optional. Enter configurations for the runner. +1. Select **Submit**. +1. Follow the on-screen instructions to register the runner from the command line. + +You can also [create a runner](../../api/users.md#create-a-runner) with the API to generate an authentication token. + +NOTE: +The authentication token displays in the UI for only a short period of time during registration. + +### Create a project runner with a registration token (deprecated) + +WARNING: +The ability to pass a runner registration token, and support for certain configuration arguments was +[deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/380872) in GitLab 15.6 and will be removed in GitLab 17.0. Authentication tokens +should be used instead. For more information, see [Migrating to the new runner registration workflow](new_creation_workflow.md). Prerequisite: @@ -284,7 +430,7 @@ You can edit a project runner from any of the projects it's enabled for. The modifications, which include unlocking and editing tags and the description, affect all projects that use the runner. -An administrator can [enable the runner for multiple projects](../../user/admin_area/settings/continuous_integration.md#enable-a-project-runner-for-multiple-projects). +An administrator can [enable the runner for multiple projects](../../administration/settings/continuous_integration.md#enable-a-project-runner-for-multiple-projects). ### Prevent a project runner from being enabled for other projects @@ -302,3 +448,95 @@ To lock or unlock a project runner: 1. Select **Edit** (**{pencil}**). 1. Select the **Lock to current projects** checkbox. 1. Select **Save changes**. + +## Runner statuses + +A runner can have one of the following statuses. + +| Status | Description | +|---------|-------------| +| `online` | The runner has contacted GitLab within the last 2 hours and is available to run jobs. | +| `offline` | The runner has not contacted GitLab in more than 2 hours and is not available to run jobs. Check the runner to see if you can bring it online. | +| `stale` | The runner has not contacted GitLab in more than 3 months. If the runner was created more than 3 months ago, but it never contacted the instance, it is also considered **stale**. | +| `never_contacted` | The runner has never contacted GitLab. To make the runner contact GitLab, run `gitlab-runner run`. | + +## View statistics for runner performance **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/377963) in GitLab 15.8. + +As an administrator, you can view runner statistics to learn about the performance of your runner fleet. + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **CI/CD > Runners**. +1. Select **View metrics**. + +The **Median job queued time** value is calculated by sampling the queue duration of the +most recent 100 jobs that were run by Instance runners. Jobs from only the latest 5000 +runners are considered. + +The median is a value that falls into the 50th percentile: half of the jobs +queued for longer than the median value, and half of the jobs queued for less than the +median value. + +## Determine which runners need to be upgraded **(ULTIMATE)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/365078) in GitLab 15.3. + +The version of GitLab Runner used by your runners should be +[kept up-to-date](https://docs.gitlab.com/runner/index.html#gitlab-runner-versions). + +To determine which runners need to be upgraded: + +1. View the list of runners: + - For a group: + 1. On the left sidebar, at the top, select **Search GitLab** (**{search}**) to find your group. + 1. Select **Build > Runners**. + - For the instance: + 1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). + 1. Select **Admin Area**. + 1. Select **CI/CD > Runners**. + +1. Above the list of runners, view the status: + - **Outdated - recommended**: The runner does not have the latest `PATCH` version, which may make it vulnerable + to security or high severity bugs. Or, the runner is one or more `MAJOR` versions behind your GitLab instance, so some features may not be available or work properly. + - **Outdated - available**: Newer versions are available but upgrading is not critical. + +1. Filter the list by status to view which individual runners need to be upgraded. + +## Determine the IP address of a runner + +It may be useful to know the IP address of a runner so you can troubleshoot +issues with that runner. GitLab stores and displays the IP address by viewing +the source of the HTTP requests it makes to GitLab when polling for jobs. The +IP address is always kept up to date so if the runner IP changes it +automatically updates in GitLab. + +The IP address for shared runners and project runners can be found in +different places. + +### Determine the IP address of a shared runner + +Prerequisite: + +- You must have administrator access to the instance. + +To determine the IP address of a shared runner: + +1. On the left sidebar, expand the top-most chevron (**{chevron-down}**). +1. Select **Admin Area**. +1. On the left sidebar, select **CI/CD > Runners**. +1. Find the runner in the table and view the **IP Address** column. + + + +### Determine the IP address of a project runner + +To can find the IP address of a runner for a project project, +you must have the Owner role for the +project. + +1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. +1. On the details page you should see a row for **IP Address**. + + |