diff options
Diffstat (limited to 'doc/user/infrastructure/iac/index.md')
| -rw-r--r-- | doc/user/infrastructure/iac/index.md | 149 |
1 files changed, 80 insertions, 69 deletions
diff --git a/doc/user/infrastructure/iac/index.md b/doc/user/infrastructure/iac/index.md index 3bc7495d4be..bc7a3c0d069 100644 --- a/doc/user/infrastructure/iac/index.md +++ b/doc/user/infrastructure/iac/index.md @@ -6,110 +6,121 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Infrastructure as Code with Terraform and GitLab **(FREE)** -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. +To manage your infrastructure with GitLab, you can use the integration with +Terraform to define resources that you can version, reuse, and share: + +- Manage low-level components like compute, storage, and networking resources. +- Manage high-level components like DNS entries and SaaS features. +- Incorporate GitOps deployments and Infrastructure-as-Code (IaC) workflows. +- Use GitLab as a Terraform state storage. +- Store and use Terraform modules to simplify common and complex infrastructure patterns. + +<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch [a video overview](https://www.youtube.com/watch?v=iGXjUrkkzDI) of the features GitLab provides with the integration with Terraform. ## Integrate your project with Terraform > SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. -In GitLab 14.0 and later, to integrate your project with Terraform, add the following -to your `.gitlab-ci.yml` file: +The integration with GitLab and Terraform happens through GitLab CI/CD. +Use an `include` attribute to add the Terraform template to your project and +customize from there. -```yaml -include: - - template: Terraform.latest.gitlab-ci.yml +To get started, choose the template that best suits your needs: -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 -``` +- [Latest template](#latest-terraform-template) +- [Stable template and advanced template](#stable-and-advanced-terraform-templates) -The `Terraform.latest.gitlab-ci.yml` template: +All templates: -- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). -- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as +- Use 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 - [run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - `test`, `validate`, `plan`, `plan-json`, and `apply`. The `apply` command only runs on the default branch. -- 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`. +- Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`. +- Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch. +- Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually). -You can override the values in the default template by updating your `.gitlab-ci.yml` file. +### Latest Terraform template -The latest template might contain breaking changes between major GitLab releases. -For a more stable template, we recommend: +The [latest template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.latest.gitlab-ci.yml) +is compatible with the most recent GitLab version. It provides the most recent +GitLab features, but can potentially include breaking changes. -- [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) +You can safely use the latest Terraform template: -This video from January 2021 walks you through all the GitLab Terraform integration features: +- If you use GitLab.com. +- If you use a self-managed instance updated with every new GitLab release. -<div class="video-fallback"> - See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. -</div> -<figure class="video-container"> - <iframe src="https://www.youtube.com/embed/iGXjUrkkzDI" frameborder="0" allowfullscreen="true"> </iframe> -</figure> +### Stable and advanced Terraform templates -## GitLab-managed Terraform state +If you use earlier versions of GitLab, you might face incompatibility errors +between the GitLab version and the template version. In this case, you can opt +to use one of these templates: + +- [The stable template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) with an skeleton that you can built on top of. +- [The advanced template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml) to fully customize your setup. + +### Use a Terraform template + +To use a Terraform template: -[Terraform remote backends](https://www.terraform.io/language/settings/backends) -enable you to store the state file in a remote, shared store. GitLab uses the -[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http) -to securely store the state files in local storage (the default) or -[the remote store of your choice](../../../administration/terraform_state.md). +1. On the top bar, select **Menu > Projects** and find the project you want to integrate with Terraform. +1. On the left sidebar, select **Repository > Files**. +1. Edit your `.gitlab-ci.yml` file, use the `include` attribute to fetch the Terraform template: -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: + ```yaml + include: + # To fetch the latest template, use: + - template: Terraform.latest.gitlab-ci.yml + # To fetch the stable template, use: + - template: Terraform/Base.gitlab-ci.yml + # To fetch the advanced template, use: + - template: Terraform/Base.latest.gitlab-ci.yml + ``` -- Supporting encryption of the state file both in transit and at rest. -- Locking and unlocking state. -- Remote Terraform plan and apply execution. +1. Add the variables as described below: -Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md). + ```yaml + variables: + TF_STATE_NAME: default + TF_CACHE_KEY: default + # If your terraform files are in a subdirectory, set TF_ROOT accordingly. For example: + # TF_ROOT: terraform/production + ``` + +1. (Optional) Override in your `.gitlab-ci.yaml` file the attributes present +in the template you fetched to customize your configuration. + +## GitLab-managed Terraform state + +Use the [GitLab-managed Terraform state](terraform_state.md) to store state +files in local storage or in a remote store of your choice. ## Terraform module registry -GitLab can be used as a [Terraform module registry](../../packages/terraform_module_registry/index.md) -to create and publish Terraform modules to a private registry specific to your -top-level namespace. +Use GitLab as a [Terraform module registry](../../packages/terraform_module_registry/index.md) +to create and publish Terraform modules to a private registry. ## 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 -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). +Use the [Terraform integration in merge requests](mr_integration.md) +to collaborate on Terraform code changes and Infrastructure-as-Code +workflows. ## The GitLab Terraform provider -WARNING: +NOTE: The GitLab Terraform provider is released separately from GitLab. -We are working on migrating the GitLab Terraform provider for GitLab.com. - -You can use the [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) -to manage various aspects of GitLab using Terraform. The provider is an open source project, -owned by GitLab, where everyone can contribute. +We are working on migrating the GitLab Terraform provider to GitLab.com. -The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs) -is available as part of the official Terraform provider documentation. +The [GitLab Terraform provider](https://github.com/gitlabhq/terraform-provider-gitlab) is a plugin for Terraform to facilitate +managing of GitLab resources such as users, groups, and projects. +Its documentation is available on [Terraform](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs). ## Create a new cluster through IaC - Learn how to [create a new cluster on Amazon Elastic Kubernetes Service (EKS)](../clusters/connect/new_eks_cluster.md). - Learn how to [create a new cluster on Google Kubernetes Engine (GKE)](../clusters/connect/new_gke_cluster.md). -## Troubleshooting +## Related topics -See the [troubleshooting](troubleshooting.md) documentation. +- [Terraform images](https://gitlab.com/gitlab-org/terraform-images). +- [Troubleshooting](troubleshooting.md) issues with GitLab and Terraform. |