diff options
Diffstat (limited to 'doc/user/infrastructure/iac/index.md')
| -rw-r--r-- | doc/user/infrastructure/iac/index.md | 102 |
1 files changed, 22 insertions, 80 deletions
diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index ceb6101688b..6fef1aa7879 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -6,36 +6,33 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure as Code with Terraform and GitLab **(FREE)** -## Motivation +With Terraform in GitLab, you can use GitLab authentication and authorization with +your GitOps and Infrastructure-as-Code (IaC) workflows. +Use these features if you want to collaborate on Terraform code within GitLab or would like to use GitLab as a Terraform state storage that incorporates best practices out of the box. -The Terraform integration features in GitLab enable your GitOps / Infrastructure-as-Code (IaC) -workflows to tie into GitLab authentication and authorization. These features focus on -lowering the barrier to entry for teams to adopt Terraform, collaborate effectively in -GitLab, and support Terraform best practices. - -## Quick Start +## Integrate your project with Terraform > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. -Use the following `.gitlab-ci.yml` to set up a basic Terraform project integration -for GitLab versions 14.0 and later: +In GitLab 14.0 and later, to integrate your project with Terraform, add the following +to your `.gitlab-ci.yml` file: ```yaml include: - template: Terraform.latest.gitlab-ci.yml variables: - # If not using GitLab's HTTP backend, remove this line and specify TF_HTTP_* variables + # If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables TF_STATE_NAME: default TF_CACHE_KEY: default # If your terraform files are in a subdirectory, set TF_ROOT accordingly # TF_ROOT: terraform/production ``` -This template includes the following parameters that you can override: +The `Terraform.latest.gitlab-ci.yml` template: - Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). -- Uses the [GitLab-managed Terraform State](#gitlab-managed-terraform-state) as +- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as the Terraform state storage backend. - Creates [four pipeline stages](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml): `test`, `validate`, `build`, and `deploy`. These stages @@ -44,10 +41,12 @@ This template includes the following parameters that you can override: - Runs the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually), that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`. -The latest template described above might contain breaking changes between major GitLab releases. For users requiring more stable setups, we -recommend using the stable templates: +You can override the values in the default template by updating your `.gitlab-ci.yml` file. + +The latest template might contain breaking changes between major GitLab releases. +For a more stable template, we recommend: -- [A ready to use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) +- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) - [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) This video from January 2021 walks you through all the GitLab Terraform integration features: @@ -59,7 +58,7 @@ This video from January 2021 walks you through all the GitLab Terraform integrat <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> </figure> -## GitLab Managed Terraform state +## GitLab-managed Terraform state [Terraform remote backends](https://www.terraform.io/docs/language/settings/backends/index.html) enable you to store the state file in a remote, shared store. GitLab uses the @@ -67,7 +66,7 @@ enable you to store the state file in a remote, shared store. GitLab uses the to securely store the state files in local storage (the default) or [the remote store of your choice](../../../administration/terraform_state.md). -The GitLab managed Terraform state backend can store your Terraform state easily and +The GitLab-managed Terraform state backend can store your Terraform state easily and securely. It spares you from setting up additional remote resources like Amazon S3 or Google Cloud Storage. Its features include: @@ -75,7 +74,7 @@ Amazon S3 or Google Cloud Storage. Its features include: - Locking and unlocking state. - Remote Terraform plan and apply execution. -Read more on setting up and [using GitLab Managed Terraform states](terraform_state.md). +Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md). ## Terraform module registry @@ -83,12 +82,12 @@ GitLab can be used as a [Terraform module registry](../../packages/terraform_mod to create and publish Terraform modules to a private registry specific to your top-level namespace. -## Terraform integration in Merge Requests +## Terraform integration in merge requests Collaborating around Infrastructure as Code (IaC) changes requires both code changes and expected infrastructure changes to be checked and approved. GitLab provides a solution to help collaboration around Terraform code changes and their expected -effects using the Merge Request pages. This way users don't have to build custom +effects using the merge request pages. This way users don't have to build custom tools or rely on 3rd party solutions to streamline their IaC workflows. Read more on setting up and [using the merge request integrations](mr_integration.md). @@ -104,7 +103,7 @@ to manage various aspects of GitLab using Terraform. The provider is an open sou owned by GitLab, where everyone can contribute. The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) -is available as part of the official Terraform provider documentations. +is available as part of the official Terraform provider documentation. ## Create a new cluster through IaC (DEPRECATED) @@ -114,66 +113,9 @@ NOTE: The linked tutorial connects the cluster to GitLab through cluster certificates, and this method was [deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5. You can still create a cluster through IaC and then connect it to GitLab -through the [Agent](../../clusters/agent/index.md), the default and fully supported +through the [agent](../../clusters/agent/index.md), the default and fully supported method to connect clusters to GitLab. ## Troubleshooting -### `gitlab_group_share_group` resources not detected when subgroup state is refreshed - -The GitLab Terraform provider can fail to detect existing `gitlab_group_share_group` resources -due to the issue ["User with permissions cannot retrieve `share_with_groups` from the API"](https://gitlab.com/gitlab-org/gitlab/-/issues/328428). -This results in an error when running `terraform apply` because Terraform attempts to recreate an -existing resource. - -For example, consider the following group/subgroup configuration: - -```plaintext -parent-group -├── subgroup-A -└── subgroup-B -``` - -Where: - -- User `user-1` creates `parent-group`, `subgroup-A`, and `subgroup-B`. -- `subgroup-A` is shared with `subgroup-B`. -- User `terraform-user` is member of `parent-group` with inherited `owner` access to both subgroups. - -When the Terraform state is refreshed, the API query `GET /groups/:subgroup-A_id` issued by the provider does not return the -details of `subgroup-B` in the `shared_with_groups` array. This leads to the error. - -To workaround this issue, make sure to apply one of the following conditions: - -1. The `terraform-user` creates all subgroup resources. -1. Grant Maintainer or Owner role to the `terraform-user` user on `subgroup-B`. -1. The `terraform-user` inherited access to `subgroup-B` and `subgroup-B` contains at least one project. - -### Invalid CI/CD syntax error when using the "latest" base template - -On GitLab 14.2 and later, you might get a CI/CD syntax error when using the -`latest` Base Terraform template: - -```yaml -include: - - template: Terraform/Base.latest.gitlab-ci.yml - -my-Terraform-job: - extends: .init -``` - -The base template's [jobs were renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/67719/) -with better Terraform-specific names. To resolve the syntax error, you can: - -- Use the stable `Terraform/Base.gitlab-ci.yml` template, which has not changed. -- Update your pipeline configuration to use the new job names in - `https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml`. - For example: - - ```yaml - include: - - template: Terraform/Base.latest.gitlab-ci.yml - - my-Terraform-job: - extends: .terraform:init # The updated name. - ``` +See the [troubleshooting](troubleshooting.md) documentation. |