diff options
Diffstat (limited to 'doc/ci/runners')
| -rw-r--r-- | doc/ci/runners/configure_runners.md | 27 | ||||
| -rw-r--r-- | doc/ci/runners/img/build_isolation.png | bin | 0 -> 35301 bytes | |||
| -rw-r--r-- | doc/ci/runners/index.md | 24 | ||||
| -rw-r--r-- | doc/ci/runners/runners_scope.md | 67 | ||||
| -rw-r--r-- | doc/ci/runners/saas/linux_saas_runner.md | 2 | ||||
| -rw-r--r-- | doc/ci/runners/saas/windows_saas_runner.md | 3 |
6 files changed, 80 insertions, 43 deletions
diff --git a/doc/ci/runners/configure_runners.md b/doc/ci/runners/configure_runners.md index efd78fac2c6..3efa697bf2f 100644 --- a/doc/ci/runners/configure_runners.md +++ b/doc/ci/runners/configure_runners.md @@ -722,11 +722,14 @@ variables: > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/28940) in GitLab Runner 15.1. +NOTE: +Zip archives are the only supported artifact type. Follow [the issue for details](https://gitlab.com/gitlab-org/gitlab/-/issues/367203). + GitLab Runner can generate and produce attestation metadata for all build artifacts. To enable this feature, you must set the `RUNNER_GENERATE_ARTIFACTS_METADATA` environment variable to `true`. This variable can either be set globally or it can be set for individual jobs. The metadata is in rendered in a plain text `.json` file that's stored with the artifact. The file name is as follows: `{JOB_ID}-artifacts-metadata.json`. ### Attestation format -The attestation metadata is generated in the [in-toto attestation format](https://github.com/in-toto/attestation) for spec version [v0.1](https://in-toto.io/Statement/v0.1). The following fields are populated by default: +The attestation metadata is generated in the [in-toto attestation format](https://github.com/in-toto/attestation) for spec version [v0.1](https://github.com/in-toto/attestation/tree/v0.1.0/spec). The following fields are populated by default: | Field | Value | | ------ | ------ | @@ -863,7 +866,7 @@ Group runners are those that were created at the group level. ### View stale runner cleanup logs -You can check the [Sidekiq logs](../../administration/logs.md#sidekiq-logs) to see the cleanup result. In Kibana you can use the following query: +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 { @@ -889,3 +892,23 @@ Filter entries where stale runners were removed: } } ``` + +## 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, on the top bar, select **Menu > Groups** and on the left sidebar, select **CI/CD > Runners**. + - For the instance, select **Menu > Admin** and on the left sidebar, select **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. diff --git a/doc/ci/runners/img/build_isolation.png b/doc/ci/runners/img/build_isolation.png Binary files differnew file mode 100644 index 00000000000..a363ef4709b --- /dev/null +++ b/doc/ci/runners/img/build_isolation.png diff --git a/doc/ci/runners/index.md b/doc/ci/runners/index.md index 038bda4ab09..f69d1f0f730 100644 --- a/doc/ci/runners/index.md +++ b/doc/ci/runners/index.md @@ -18,5 +18,25 @@ The number of minutes you can use on these runners depends on the [maximum number of CI/CD minutes](../pipelines/cicd_minutes.md) in your [subscription plan](https://about.gitlab.com/pricing/). -If you use self-managed GitLab or you use GitLab.com but want to use your own runners, you can -[install and configure your own runners](https://docs.gitlab.com/runner/install/). +## Security for GitLab SaaS runners + +GitLab SaaS runners on Linux and Windows run on Google Compute Platform. The [Google Infrastructure Security Design Overview whitepaper](https://cloud.google.com/docs/security/infrastructure/design/resources/google_infrastructure_whitepaper_fa.pdf) provides an overview of how Google designs security into its technical infrastructure. The GitLab [Trust Center](https://about.gitlab.com/security/) and [GitLab Security Compliance Controls](https://about.staging.gitlab.com/handbook/engineering/security/security-assurance/security-compliance/sec-controls.html) pages provide an overview of the Security and Compliance controls that govern the GitLab SaaS runners. + +The runner that serves as a Runner Manager automatically initiates the creation and deletion of the virtual machines (VMs) used for CI jobs. When the Runner Manager picks up a GitLab SaaS CI job, it automatically executes that job on a new VM. There is no human or manual intervention in this process. The following section provides an overview of the additional built-in layers that harden the security of the GitLab Runner SaaS CI build environment. + +### Security of CI job execution on GitLab Runner SaaS (Linux, Windows) + +A dedicated temporary runner VM hosts and runs each CI job. On GitLab SaaS, two CI jobs never run on the same VM. + + + +In this example, there are three jobs in the project's pipeline. Therefore, there are three temporary VMs used to run that pipeline, or one VM per job. + +GitLab sends the command to remove the temporary runner VM to the Google Compute API immediately after the CI job completes. The [Google Compute Engine hypervisor](https://cloud.google.com/blog/products/gcp/7-ways-we-harden-our-kvm-hypervisor-at-google-cloud-security-in-plaintext) takes over the task of securely deleting the virtual machine and associated data. + +### Network security of CI job virtual machines on GitLab Runner SaaS (Linux, Windows) + +- Firewall rules only allow outbound communication from the temporary VM to the public internet. +- Inbound communication from the public internet to the temporary VM is not allowed. +- Firewall rules do not permit communication between VMs. +- The only internal communication allowed to the temporary VMs is from the Runner Manager. diff --git a/doc/ci/runners/runners_scope.md b/doc/ci/runners/runners_scope.md index 8b2753d26f1..9bd0b52f423 100644 --- a/doc/ci/runners/runners_scope.md +++ b/doc/ci/runners/runners_scope.md @@ -25,11 +25,11 @@ 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 the **Runners** section, - and clicking **Show runner installation instructions**. + 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). -- The administrator can also configure a maximum number of shared runner [CI/CD minutes for - each group](../pipelines/cicd_minutes.md#set-the-quota-of-cicd-minutes-for-a-specific-namespace). +- The administrator can also configure a maximum number of shared runner + [CI/CD minutes for each group](../pipelines/cicd_minutes.md#set-the-quota-of-cicd-minutes-for-a-specific-namespace). If you are using GitLab.com: @@ -51,15 +51,19 @@ For existing projects, an administrator must To enable shared runners for a project: -1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. Select **Enable shared runners for this project**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. +1. Turn on the **Enable shared runners for this project** toggle. ### Enable shared runners for a group To enable shared runners for a group: -1. Go to the group's **Settings > CI/CD** and expand the **Runners** section. -1. Select **Enable shared runners for this group**. +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. +1. Turn on the **Enable shared runners for this group** toggle. ### Disable shared runners for a project @@ -69,8 +73,10 @@ or group. To disable shared runners for a project: -1. Go to the project's **Settings > CI/CD** and expand the **Runners** section. -1. In the **Shared runners** area, select **Enable shared runners for this project** so the toggle is grayed-out. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. +1. In the **Shared runners** area, turn off the **Enable shared runners for this project** toggle. Shared runners are automatically disabled for a project: @@ -81,9 +87,11 @@ Shared runners are automatically disabled for a project: To disable shared runners for a group: -1. Go to the group's **Settings > CI/CD** and expand the **Runners** section. -1. In the **Shared runners** area, turn off the **Enable shared runners for this group** toggle. -1. Optionally, to allow shared runners to be enabled for individual projects or subgroups, +1. On the top bar, select **Menu > Groups** and find your group. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. +1. Turn off the **Enable shared runners for this group** toggle. +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: @@ -147,7 +155,7 @@ The fair usage algorithm assigns jobs in this order: ## Group runners -Use *Group runners* when you want all projects in a group +Use _group runners_ when you want all projects in a group 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. @@ -162,7 +170,7 @@ You must have the Owner role for the group. To create a group runner: 1. [Install GitLab Runner](https://docs.gitlab.com/runner/install/). -1. Go to the group you want to make the runner work for. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **CI/CD > Runners**. 1. Note the URL and token. 1. [Register the runner](https://docs.gitlab.com/runner/register/). @@ -175,21 +183,8 @@ You can view and manage all runners for a group, its subgroups, and projects. You can do this for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group. -1. Go to the group where you want to view the runners. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **CI/CD > Runners**. -1. The following fields are displayed. - - | Attribute | Description | - | ------------ | ----------- | - | Type | Displays the runner type: `group` or `specific`, and the optional state `paused` | - | Runner token | Token used to identify the runner, and that the runner uses to communicate with the GitLab instance | - | Description | Description given to the runner when it was created | - | Version | GitLab Runner version | - | IP address | IP address of the host on which the runner is registered | - | Projects | The count of projects to which the runner is assigned | - | Jobs | Total of jobs run by the runner | - | Tags | Tags associated with the runner | - | Last contact | Timestamp indicating when the GitLab instance last contacted the runner | From this page, you can edit, pause, and remove runners from the group, its subgroups, and projects. @@ -198,7 +193,7 @@ From this page, you can edit, pause, and remove runners from the group, its subg You can pause or remove a group runner for your self-managed GitLab instance or for GitLab.com. You must have the Owner role for the group. -1. Go to the group you want to remove or pause the runner for. +1. On the top bar, select **Menu > Groups** and find your group. 1. On the left sidebar, select **CI/CD > Runners**. 1. Select **Pause** or **Remove runner**. - If you pause a group runner that is used by multiple projects, the runner pauses for all projects. @@ -208,7 +203,7 @@ You must have the Owner role for the group. ## Specific runners -Use *Specific runners* when you want to use runners for specific projects. For example, +Use _specific runners_ when you want to use runners for specific projects. For example, when you have: - Jobs with specific requirements, like a deploy job that requires credentials. @@ -257,9 +252,8 @@ To enable a specific runner for a project: 1. On the top bar, select **Menu > Projects** and find the project where you want to enable the runner. 1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **General pipelines**. 1. Expand **Runners**. -1. By the runner you want, select **Enable for this project**. +1. In the **Specific runners** area, by the runner you want, select **Enable for this project**. You can edit a specific runner from any of the projects it's enabled for. The modifications, which include unlocking and editing tags and the description, @@ -275,9 +269,10 @@ but can also be changed later. To lock or unlock a specific runner: -1. Go to the project's **Settings > CI/CD**. -1. Expand the **Runners** section. +1. On the top bar, select **Menu > Projects** and find the project where you want to enable the runner. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Runners**. 1. Find the specific runner you want to lock or unlock. Make sure it's enabled. You cannot lock shared or group runners. 1. Select **Edit** (**{pencil}**). -1. Check the **Lock to current projects** option. +1. Select the **Lock to current projects** checkbox. 1. Select **Save changes**. diff --git a/doc/ci/runners/saas/linux_saas_runner.md b/doc/ci/runners/saas/linux_saas_runner.md index f1e28f7e74d..e96e89b47e5 100644 --- a/doc/ci/runners/saas/linux_saas_runner.md +++ b/doc/ci/runners/saas/linux_saas_runner.md @@ -24,7 +24,7 @@ The `gitlab-shared-runners-manager-X.gitlab.com` fleet of runners are dedicated Jobs handled by shared runners on GitLab.com (`shared-runners-manager-X.gitlab.com`) **time out after 3 hours**, regardless of the timeout configured in a -project. Check issue [#4010](https://gitlab.com/gitlab-com/infrastructure/-/issues/4010) and [#4070](https://gitlab.com/gitlab-com/infrastructure/-/issues/4070) for the reference. +project. Check issue [#4010](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4010) and [#4070](https://gitlab.com/gitlab-com/gl-infra/reliability/-/issues/4070) for the reference. Jobs handled by shared runners on Windows and macOS on GitLab.com **time out after 1 hour** while this service is in the [Beta](../../../policy/alpha-beta-support.md#beta-features) stage. diff --git a/doc/ci/runners/saas/windows_saas_runner.md b/doc/ci/runners/saas/windows_saas_runner.md index dddb3afee7c..f9fe6290220 100644 --- a/doc/ci/runners/saas/windows_saas_runner.md +++ b/doc/ci/runners/saas/windows_saas_runner.md @@ -126,8 +126,7 @@ test: ## Limitations and known issues -- All the limitations mentioned in our [beta - definition](../../../policy/alpha-beta-support.md#beta-features). +- All the limitations mentioned in our [beta definition](../../../policy/alpha-beta-support.md#beta-features). - The average provisioning time for a new Windows VM is 5 minutes. This means that you may notice slower build start times on the Windows runner fleet during the beta. In a future |
