diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-15 09:10:42 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-01-15 09:10:42 +0300 |
commit | d35857c09311de5482f1a888f2d30a0cddd376ef (patch) | |
tree | b2ecf9be13f49971be3e0f348839f2b53443039c /doc | |
parent | c9bdf919932b7285ef9920bdac955459340da8fe (diff) |
Add latest changes from gitlab-org/gitlab@master
Diffstat (limited to 'doc')
-rw-r--r-- | doc/administration/repository_storage_paths.md | 6 | ||||
-rw-r--r-- | doc/ci/README.md | 8 | ||||
-rw-r--r-- | doc/ci/variables/deprecated_variables.md | 36 | ||||
-rw-r--r-- | doc/ci/variables/predefined_variables.md | 3 | ||||
-rw-r--r-- | doc/user/infrastructure/terraform_state.md | 65 | ||||
-rw-r--r-- | doc/user/project/merge_requests/code_quality.md | 99 | ||||
-rw-r--r-- | doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png | bin | 0 -> 12345 bytes |
7 files changed, 142 insertions, 75 deletions
diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index 090f95eca12..c71d1a5714c 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -122,3 +122,9 @@ weights are used to determine the storage location the repository is created on. Beginning with GitLab 8.13.4, multiple paths can be chosen. New repositories are randomly placed on one of the selected paths. + +## Move a repository to a different repository path + +To move a repository to a different repository path, use the +[Project repository storage moves](../api/project_repository_storage_moves.md) API. Use +the same process as [migrating existing repositories to Gitaly Cluster](gitaly/praefect.md#migrate-existing-repositories-to-gitaly-cluster). diff --git a/doc/ci/README.md b/doc/ci/README.md index 6b33c3ef966..740be7d1dbd 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -221,11 +221,3 @@ been necessary. These are: #### 10.0 - No breaking changes. - -#### 9.0 - -- [CI variables renaming for GitLab 9.0](variables/deprecated_variables.md#gitlab-90-renamed-variables). Read about the - deprecated CI variables and what you should use for GitLab 9.0+. -- [New CI job permissions model](../user/project/new_ci_build_permissions_model.md). - See what changed in GitLab 8.12 and how that affects your jobs. - There's a new way to access your Git submodules and LFS objects in jobs. diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md index 755e34fa5ca..8d23ec1fd97 100644 --- a/doc/ci/variables/deprecated_variables.md +++ b/doc/ci/variables/deprecated_variables.md @@ -1,36 +1,8 @@ --- -stage: Verify -group: Continuous Integration -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments -type: reference +redirect_to: 'README.md' --- -# Deprecated GitLab CI/CD variables +This documentation page was removed. For information about variables, see [GitLab CI/CD environment variables](README.md) -Read through this document to learn what predefined variables -were deprecated and their new references. - -## GitLab 9.0 renamed variables - -To follow conventions of naming across GitLab, and to further move away from the -`build` term and toward `job`, some [CI/CD environment variables](README.md#predefined-environment-variables) were renamed for GitLab 9.0 -release. - -Starting with GitLab 9.0, we have deprecated the `$CI_BUILD_*` variables. **You are -strongly advised to use the new variables as we might remove the old ones in -future GitLab releases.** - -| 8.x name | 9.0+ name | -| --------------------- |------------------------ | -| `CI_BUILD_BEFORE_SHA` | `CI_COMMIT_BEFORE_SHA` | -| `CI_BUILD_ID` | `CI_JOB_ID` | -| `CI_BUILD_MANUAL` | `CI_JOB_MANUAL` | -| `CI_BUILD_NAME` | `CI_JOB_NAME` | -| `CI_BUILD_REF` | `CI_COMMIT_SHA` | -| `CI_BUILD_REF_NAME` | `CI_COMMIT_REF_NAME` | -| `CI_BUILD_REF_SLUG` | `CI_COMMIT_REF_SLUG` | -| `CI_BUILD_REPO` | `CI_REPOSITORY_URL` | -| `CI_BUILD_STAGE` | `CI_JOB_STAGE` | -| `CI_BUILD_TAG` | `CI_COMMIT_TAG` | -| `CI_BUILD_TOKEN` | `CI_JOB_TOKEN` | -| `CI_BUILD_TRIGGERED` | `CI_PIPELINE_TRIGGERED` | +<!-- This redirect file can be deleted after 2021-04-14. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 779b0c4732c..701fe33b53f 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -14,9 +14,6 @@ Some of the predefined environment variables are available only if a minimum version of [GitLab Runner](https://docs.gitlab.com/runner/) is used. Consult the table below to find the version of GitLab Runner that's required. -In GitLab 9.0, some [variable were deprecated](deprecated_variables.md#gitlab-90-renamed-variables). -You should ensure you are using the latest variables. - You can add a command to your `.gitlab-ci.yml` file to [output the values of all variables available for a job](README.md#list-all-environment-variables). diff --git a/doc/user/infrastructure/terraform_state.md b/doc/user/infrastructure/terraform_state.md index 94b90457ae4..30838b1cabd 100644 --- a/doc/user/infrastructure/terraform_state.md +++ b/doc/user/infrastructure/terraform_state.md @@ -62,7 +62,7 @@ local machine, this is a simple way to get started: 1. On your local machine, run `terraform init`, passing in the following options, replacing `<YOUR-STATE-NAME>`, `<YOUR-PROJECT-ID>`, `<YOUR-USERNAME>` and `<YOUR-ACCESS-TOKEN>` with the relevant values. This command initializes your - Terraform state, and stores that state within your GitLab project. The name of + Terraform state, and stores that state in your GitLab project. The name of your state can contain only uppercase and lowercase letters, decimal digits, hyphens, and underscores. This example uses `gitlab.com`: @@ -194,7 +194,7 @@ recommends encrypting plan output or modifying the project visibility settings. ### Example project -See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 within a custom VPC. +See [this reference project](https://gitlab.com/gitlab-org/configure/examples/gitlab-terraform-aws) using GitLab and Terraform to deploy a basic AWS EC2 in a custom VPC. ## Using a GitLab managed Terraform state backend as a remote data source @@ -234,7 +234,7 @@ An example setup is shown below: } ``` -Outputs from the data source can now be referenced within your Terraform resources +Outputs from the data source can now be referenced in your Terraform resources using `data.terraform_remote_state.example.outputs.<OUTPUT-NAME>`. You need at least [developer access](../permissions.md) to the target project @@ -340,40 +340,53 @@ commands will detect it and remind you to do so if necessary. ``` If you type `yes`, it copies your state from the old location to the new -location. You can then go back to running it from within GitLab CI. +location. You can then go back to running it in GitLab CI/CD. ## Managing state files -NOTE: -We are currently working on [providing a graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/273592) in GitLab 13.8. + +Users with Developer and greater [permissions](../permissions.md) can view the +state files attached to a project at **Operations > Terraform**. Users with +Maintainer permissions can perform commands on the state files. The user interface +contains these fields: ![Terraform state list](img/terraform_list_view_v13_8.png) -To list the state files attached to a project go to **Operations > Terraform**. +- **Name**: The name of the environment, with a locked (**{lock}**) icon if the + state file is locked. +- **Pipeline**: A link to the most recent pipeline and its status. +- **Details**: Information about when the state file was created or changed. +- **Actions**: Actions you can take on the state file, including downloading, + locking, unlocking, or [removing](#remove-a-state-file) the state file and versions: -![Terraform state list](img/terraform_list_view_actions_v13_8.png) + ![Terraform state list](img/terraform_list_view_actions_v13_8.png) -The list also includes an **Actions** column where you can download, lock or unlock, or remove each state file. +NOTE: +Additional improvements to the +[graphical interface for managing state files](https://gitlab.com/groups/gitlab-org/-/epics/4563) +are planned. ## Remove a state file -You can use the following options to remove a state file: +Users with Maintainer and greater [permissions](../permissions.md) can use the +following options to remove a state file: -1. GitLab REST API -1. GitLab GraphQL API -1. GitLab UI +- **GitLab UI**: Go to **Operations > Terraform**. In the **Actions** column, + click the vertical ellipsis (**{ellipsis_v}**) button and select + **Remove state file and versions**. +- **GitLab REST API**: You can remove a state file by making a request to the + REST API. For example: -### Remove a state file with the GitLab REST API + ```shell + curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" + ``` -You can remove a state file by making a request to the REST API, for example: - -```shell -curl --header "Private-Token: <your_access_token>" --request DELETE "https://gitlab.example.com/api/v4/projects/<your_project_id>/terraform/state/<your_state_name>" -``` +- [GitLab GraphQL API](#remove-a-state-file-with-the-gitlab-graphql-api). ### Remove a state file with the GitLab GraphQL API -You can remove a state file by making a GraphQL API request, for example: +You can remove a state file by making a GraphQL API request. For example: ```shell mutation deleteState { @@ -383,7 +396,7 @@ mutation deleteState { } ``` -You can obtain the `<global_id_for_the_state>` by querying the list of states. For example: +You can obtain the `<global_id_for_the_state>` by querying the list of states: ```shell query ProjectTerraformStates { @@ -398,11 +411,5 @@ query ProjectTerraformStates { } ``` -For those new to the GitLab GraphQL API, see [Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md). - -### Remove a state file with the GitLab UI - -To delete a state file: - -- From your project, go to **Operations > Terraform**. -- In the **Actions** column, click on the vertical ellipsis (**{ellipsis_v}**) button and select **Remove state file and versions**. +For those new to the GitLab GraphQL API, read +[Getting started with GitLab GraphQL API](../../api/graphql/getting_started.md). diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 426973d9fd7..ca15ec154fc 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -72,10 +72,10 @@ It requires GitLab 11.11 or later, and GitLab Runner 11.5 or later. If you are u GitLab 11.4 or earlier, you can view the deprecated job definitions in the [documentation archive](https://docs.gitlab.com/12.10/ee/user/project/merge_requests/code_quality.html#previous-job-definitions). -First, you need GitLab Runner configured: +- Using shared runners, the job should be configured For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). +- Using private runners, there is an [alternative configuration](#set-up-a-private-runner-for-code-quality-without-docker-in-docker) recommended for running CodeQuality analysis more efficiently. -- For the [Docker-in-Docker workflow](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker). -- With enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. +In either configuration, the runner mmust have enough disk space to handle generated Code Quality files. For example on the [GitLab project](https://gitlab.com/gitlab-org/gitlab) the files are approximately 7 GB. Once you set up GitLab Runner, include the Code Quality template in your CI configuration: @@ -140,6 +140,99 @@ definition they could execute privileged Docker commands on the runner host. Having proper access control policies mitigates this attack vector by allowing access only to trusted actors. +### Set up a private runner for code quality without Docker-in-Docker + +It's possible to configure your own runners and avoid Docker-in-Docker. You can use a +configuration that may greatly speed up job execution without requiring your runners +to operate in privileged mode. + +This alternative configuration uses socket binding to share the Runner's Docker daemon +with the job environment. Be aware that this configuration [has significant considerations](../../../ci/docker/using_docker_build.md#use-docker-socket-binding) +to be consider, but may be preferable depending on your use case. + +1. Register a new runner: + + ```shell + $ gitlab-runner register --executor "docker" \ + --docker-image="docker:stable" \ + --url "https://gitlab.com/" \ + --description "cq-sans-dind" \ + --tag-list "cq-sans-dind" \ + --locked="false" \ + --access-level="not_protected" \ + --docker-volumes "/cache"\ + --docker-volumes "/var/run/docker.sock:/var/run/docker.sock" \ + --registration-token="<project_token>" \ + --non-interactive + ``` + +1. **Optional, but recommended:** Set the builds directory to `/tmp/builds`, + so job artifacts are periodically purged from the runner host. If you skip + this step, you must clean up the default builds directory (`/builds`) yourself. + You can do this by adding the following two flags to `gitlab-runner register` + in the previous step. + + ```shell + --builds-dir /tmp/builds + --docker-volumes /tmp/builds:/tmp/builds + ``` + + The resulting configuration: + + ```toml + [[runners]] + name = "cq-sans-dind" + url = "https://gitlab.com/" + token = "<project_token>" + executor = "docker" + builds_dir = "/tmp/builds" + [runners.docker] + tls_verify = false + image = "docker:stable" + privileged = false + disable_entrypoint_overwrite = false + oom_kill_disable = false + disable_cache = false + volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock", "/tmp/builds:/tmp/builds"] + shm_size = 0 + [runners.cache] + [runners.cache.s3] + [runners.cache.gcs] + ``` + +1. Apply two overrides to the `code_quality` job created by the template: + + ```yaml + include: + - template: Code-Quality.gitlab-ci.yml + + code_quality: + services: # Shut off Docker-in-Docker + tags: + - cq-sans-dind # Set this job to only run on our new specialized runner + ``` + +The end result is that: + +- Privileged mode is not used. +- Docker-in-Docker is not used. +- Docker images, including all CodeClimate images, are cached, and not re-fetched for subsequent jobs. + +With this configuration, the run time for a second pipeline is much shorter. For example +this [small change](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/diffs?commit_id=1e705607aef7236c1b20bb6f637965f3f3e53a46) +to an [open merge request](https://gitlab.com/drewcimino/test-code-quality-template/-/merge_requests/4/pipelines) +running Code Quality analysis ran significantly faster the second time: + +![Code Quality sequential runs without DinD](img/code_quality_host_bound_sequential.png) + +This configuration is not possible on `gitlab.com` shared runners. Shared runners +are configured with `privileged=true`, and they do not expose `docker.sock` into +the job container. As a result, socket binding cannot be used to make `docker` available +in the context of the job script. + +[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) +was chosen as an operational decision by the runner team, instead of exposing `docker.sock`. + ### Disabling the code quality job The `code_quality` job doesn't run if the `$CODE_QUALITY_DISABLED` environment diff --git a/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png Binary files differnew file mode 100644 index 00000000000..2b31f3b42ee --- /dev/null +++ b/doc/user/project/merge_requests/img/code_quality_host_bound_sequential.png |