diff options
Diffstat (limited to 'doc/user/infrastructure')
7 files changed, 235 insertions, 26 deletions
diff --git a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md index 6b8e2003b8d..7e6a0495d90 100644 --- a/doc/user/infrastructure/clusters/connect/new_gke_cluster.md +++ b/doc/user/infrastructure/clusters/connect/new_gke_cluster.md @@ -94,7 +94,7 @@ Use CI/CD environment variables to configure your project. 1. On the left sidebar, select **Settings > CI/CD**. 1. Expand **Variables**. 1. Set the variable `BASE64_GOOGLE_CREDENTIALS` to the `base64` encoded JSON file you just created. -1. Set the variable `TF_VAR_gcp_project` to your GCP's `project` name. +1. Set the variable `TF_VAR_gcp_project` to your GCP `project` name. 1. Set the variable `TF_VAR_agent_token` to the agent token displayed in the previous task. 1. Set the variable `TF_VAR_kas_address` to the agent server address displayed in the previous task. diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md b/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md deleted file mode 100644 index 64d325dedc6..00000000000 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/prometheus.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../../../operations/metrics/index.md' -remove_date: '2022-11-03' ---- - -This document was moved to [another location](../../../../../operations/metrics/index.md). - -<!-- This redirect file can be deleted after <2022-11-03>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md b/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md deleted file mode 100644 index f42e9c83120..00000000000 --- a/doc/user/infrastructure/clusters/manage/management_project_applications/sentry.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -redirect_to: '../../../../../operations/error_tracking.md' -remove_date: '2022-11-03' ---- - -This document was moved to [another location](../../../../../operations/error_tracking.md). - -<!-- This redirect file can be deleted after <2022-11-03>. --> -<!-- Redirects that point to other docs in the same project expire in three months. --> -<!-- Redirects that point to docs in a different project or site (link is not relative and starts with `https:`) expire in one year. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 866b16652fa..f9891934067 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -72,10 +72,12 @@ To use a Terraform template: include: # To fetch the latest template, use: - template: Terraform.latest.gitlab-ci.yml + # To fetch the advanced latest template, use: + - template: Terraform/Base.latest.gitlab-ci.yml # To fetch the stable template, use: + - template: Terraform.gitlab-ci.yml + # To fetch the advanced stable template, use: - template: Terraform/Base.gitlab-ci.yml - # To fetch the advanced template, use: - - template: Terraform/Base.latest.gitlab-ci.yml ``` 1. Add the variables as described below: @@ -91,6 +93,10 @@ To use a Terraform template: 1. Optional. Override in your `.gitlab-ci.yml` file the attributes present in the template you fetched to customize your configuration. +### Terraform template recipes + +For GitLab-curated template recipes, see [Terraform template recipes](terraform_template_recipes.md). + ## Related topics - View [the images that contain the `gitlab-terraform` shell script](https://gitlab.com/gitlab-org/terraform-images). diff --git a/doc/user/infrastructure/iac/terraform_state.md b/doc/user/infrastructure/iac/terraform_state.md index a690cc78121..fc86210ed56 100644 --- a/doc/user/infrastructure/iac/terraform_state.md +++ b/doc/user/infrastructure/iac/terraform_state.md @@ -6,7 +6,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w # GitLab-managed Terraform state **(FREE)** -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. +> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2673) in GitLab 13.0. +> - Support for state names that contain periods introduced in GitLab 15.7 [with a flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. Disabled by default. [Enabled on GitLab.com](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106861) in GitLab 15.7. + +FLAG: +On self-managed GitLab, by default support for state names that contain periods is not available. To make it available, ask an administrator to [enable the feature flag](../../../administration/feature_flags.md) named `allow_dots_on_tf_state_names`. On GitLab.com, support for state names that contain periods is available. Requests for state files might generate HTTP 404 errors after enabling this feature. For more information, see [Troubleshooting the Terraform integration with GitLab](troubleshooting.md#state-not-found-if-the-state-name-contains-a-period). Terraform uses state files to store details about your infrastructure configuration. With Terraform remote [backends](https://www.terraform.io/language/settings/backends/configuration), diff --git a/doc/user/infrastructure/iac/terraform_template_recipes.md b/doc/user/infrastructure/iac/terraform_template_recipes.md new file mode 100644 index 00000000000..ab2c8c1c48a --- /dev/null +++ b/doc/user/infrastructure/iac/terraform_template_recipes.md @@ -0,0 +1,183 @@ +--- +stage: Configure +group: Configure +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments +--- + +# Terraform template recipes **(FREE)** + +You can customize your Terraform integration by adding the recipes on +this page to your pipeline. + +If you'd like to share your own Terraform configuration, consider +[contributing a recipe](https://gitlab.com/gitlab-org/gitlab/-/blob/master/doc/user/infrastructure/iac/terraform_template_recipes.md) +to this page. + +## Enable a `terraform destroy` job + +Add the following snippet to your `.gitlab-ci.yml`: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +destroy: + extends: .terraform:destroy +``` + +The `destroy` job is part of the `cleanup` stage. Like the `deploy` +job, the `destroy` job is always `manual` and is not tied to the +default branch. + +## Run a custom `terraform` command in a job + +To define a job that runs a custom `terraform` command, the +`gitlab-terraform` wrapper can be used in any job: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +state-list: + stage: validate # you can use any stage, just make sure to define it + script: gitlab-terraform state list +``` + +The `gitlab-terraform` command sets up a `terraform` command and runs +it with the given arguments. + +To run this job in the Terraform state-specific [resource group](../../../ci/resource_groups/index.md), +assign the job with `resource_group`: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +state-list: + stage: validate # you can use any stage, just make sure to define it + resource_group: ${TF_STATE_NAME} + script: gitlab-terraform state list +``` + +## Add custom debug tools to jobs + +The default image used by Terraform template jobs contains only minimal tooling. +However, you might want to add additional tools for debugging. + +To add an additional tool: + +1. Install the tool in the `before_script` of a job or pipeline. +1. Use the tool in the `script` or `after_script` block. + - If you use the `script` block, be sure to re-add the template job commands. + +For example, the following snippet installs `bash` and `jq` in the `before_script` for all +jobs in the pipeline: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +default: + before_script: apk add --update bash jq +``` + +To add it to only the `build` and `deploy` jobs, add it to those jobs directly: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +build: + before_script: apk add --update bash jq + +deploy: + before_script: apk add --update bash jq +``` + +## Add custom container images + +For debug tools and simple installations, you should +[add a custom debug tool to your job](#add-custom-debug-tools-to-jobs). +If your tool is complex or benefits from caching, +you can create a custom container image based on the +[`gitlab-terraform`](https://gitlab.com/gitlab-org/terraform-images) images. +You can use your custom image in subsequent Terraform jobs. + +To define a custom container image: + +1. Define a new `Dockerfile` with custom tooling. For example, install `bash` and `jq` in `.gitlab/ci/Dockerfile`: + + ```dockerfile + FROM registry.gitlab.com/gitlab-org/terraform-images/stable:latest + + RUN apk add --update bash jq + ``` + +1. In a new job, define a `prepare` stage that builds the image whenever the `Dockerfile` changes. + - The built image is pushed to the [GitLab Container Registry](../../packages/container_registry). A tag is applied to indicate whether the image was built from a merge request or from the default branch. +1. Use your image in your Terraform jobs, such as `build` and `deploy`. + - You can combine your image with specialized `before_script` configurations to perform setup commands, like to generate inputs for Terraform. + +For example, a fully functioning pipeline configuration might look like: + +```yaml +include: + - template: Terraform.latest.gitlab-ci.yml + +variables: + IMAGE_TAG: latest + +workflow: + rules: + - if: $CI_MERGE_REQUEST_IID + changes: + - .gitlab/ci/Dockerfile + variables: + IMAGE_TAG: ${CI_COMMIT_REF_SLUG} + - when: always + +stages: + - prepare + - validate + - test + - build + - deploy + - cleanup + +prepare:image: + needs: [] + stage: prepare + image: + name: gcr.io/kaniko-project/executor:v1.9.0-debug + entrypoint: [""] + rules: + # Tag with the commit SHA if we're in an MR + - if: $CI_MERGE_REQUEST_IID + changes: + - .gitlab/ci/Dockerfile + variables: + DOCKER_TAG: $CI_COMMIT_REF_SLUG + # If we're on our main branch, tag with "latest" + - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH + changes: + - .gitlab/ci/Dockerfile + variables: + DOCKER_TAG: latest + before_script: + # Authenticate to the docker registry and dependency proxy + - echo "{\"auths\":{\"$CI_REGISTRY\":{\"auth\":\"$(printf "%s:%s" "${CI_REGISTRY_USER}" "${CI_REGISTRY_PASSWORD}" | base64 | tr -d '\n')\"}}}" > /kaniko/.docker/config.json + script: + - /kaniko/executor + --context "${CI_PROJECT_DIR}/.gitlab/ci" + --cache=true + --dockerfile "${CI_PROJECT_DIR}/.gitlab/ci/Dockerfile" + --destination "${CI_REGISTRY_IMAGE}:${DOCKER_TAG}" + +build: + image: ${CI_REGISTRY_IMAGE}:${IMAGE_TAG} + +deploy: + image: ${CI_REGISTRY_IMAGE}:${IMAGE_TAG} +``` + +For an example repository, see the [GitLab Terraform template usage project](https://gitlab.com/gitlab-org/configure/examples/terraform-template-usage). diff --git a/doc/user/infrastructure/iac/troubleshooting.md b/doc/user/infrastructure/iac/troubleshooting.md index 3921c6a7dc8..ad1821fbe10 100644 --- a/doc/user/infrastructure/iac/troubleshooting.md +++ b/doc/user/infrastructure/iac/troubleshooting.md @@ -131,3 +131,41 @@ To permit a user with the Developer role to run destructive commands, you need a 1. Set the value of `TF_USERNAME` to the username of your project access token. 1. Set the value of `TF_PASSWORD` to the password of your project access token. 1. Optional. Protect the variables to make them only available in pipelines that run on protected branches or protected tags. + +### State not found if the state name contains a period + +GitLab 15.6 and earlier returned 404 errors if the state name contained a period and Terraform attempted +a state lock. + +You could work around this limitation by adding `-lock=false` to your Terraform commands. The GitLab backend +accepted the request, but internally stripped the period and any characters that followed from the state name. +For example, a state named `foo.bar` would be stored as `foo`. However, this workaround wasn't recommended, +and could even cause state name collisions. + +In GitLab 15.7 and later, [state names with periods are supported](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106861). If you use the `-lock=false` workaround and upgrade to GitLab 15.7 or later, +your jobs might fail. The failure is caused by the GitLab backend storing a new state with the full state name, which diverges from the existing state name. + +To fix the failing jobs, rename your state names to exclude the period and any characters that follow it. For example, +if you use the Terraform template: + +```yaml +include: + - template: Terraform.gitlab-ci.yml + +variables: + TF_STATE_NAME: foo +``` + +If your `TF_HTTP_ADDRESS`, `TF_HTTP_LOCK_ADDRESS` and `TF_HTTP_UNLOCK_ADDRESS` are set, be sure +to update the state names there. + +Alternatively, you can [migrate your terraform state](terraform_state.md#migrate-to-a-gitlab-managed-terraform-state). + +#### Self-managed GitLab instances + +By default, support for state names with periods is not enabled on self-managed GitLab. +You can enable it from the Rails console: + +```ruby +Feature.enable(:allow_dots_on_tf_state_names) +``` |