debian-mirror-gitlab/doc/user/infrastructure/iac/index.md

116 lines
5.5 KiB
Markdown
Raw Normal View History

2021-10-27 15:23:28 +05:30
---
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/engineering/ux/technical-writing/#assignments
---
# Infrastructure as Code with Terraform and GitLab **(FREE)**
2022-04-04 11:22:00 +05:30
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.
2021-10-27 15:23:28 +05:30
2022-04-04 11:22:00 +05:30
## Integrate your project with Terraform
2021-10-27 15:23:28 +05:30
2022-03-02 08:16:31 +05:30
> SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6.
2022-04-04 11:22:00 +05:30
In GitLab 14.0 and later, to integrate your project with Terraform, add the following
to your `.gitlab-ci.yml` file:
2021-10-27 15:23:28 +05:30
```yaml
include:
2022-03-02 08:16:31 +05:30
- template: Terraform.latest.gitlab-ci.yml
2021-10-27 15:23:28 +05:30
variables:
2022-04-04 11:22:00 +05:30
# If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables
2021-10-27 15:23:28 +05:30
TF_STATE_NAME: default
TF_CACHE_KEY: default
# If your terraform files are in a subdirectory, set TF_ROOT accordingly
# TF_ROOT: terraform/production
```
2022-04-04 11:22:00 +05:30
The `Terraform.latest.gitlab-ci.yml` template:
2021-10-27 15:23:28 +05:30
2022-03-02 08:16:31 +05:30
- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images).
2022-04-04 11:22:00 +05:30
- Uses the [GitLab-managed Terraform state](#gitlab-managed-terraform-state) as
2021-10-27 15:23:28 +05:30
the Terraform state storage backend.
2022-03-02 08:16:31 +05:30
- 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`.
2022-04-04 11:22:00 +05:30
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:
2022-03-02 08:16:31 +05:30
2022-04-04 11:22:00 +05:30
- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml)
2022-03-02 08:16:31 +05:30
- [A base template for customized setups](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.gitlab-ci.yml)
2021-10-27 15:23:28 +05:30
This video from January 2021 walks you through all the GitLab Terraform integration features:
<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>
2022-04-04 11:22:00 +05:30
## GitLab-managed Terraform state
2021-10-27 15:23:28 +05:30
2022-05-07 20:08:51 +05:30
[Terraform remote backends](https://www.terraform.io/language/settings/backends)
2021-10-27 15:23:28 +05:30
enable you to store the state file in a remote, shared store. GitLab uses the
2022-05-07 20:08:51 +05:30
[Terraform HTTP backend](https://www.terraform.io/language/settings/backends/http)
2021-10-27 15:23:28 +05:30
to securely store the state files in local storage (the default) or
[the remote store of your choice](../../../administration/terraform_state.md).
2022-04-04 11:22:00 +05:30
The GitLab-managed Terraform state backend can store your Terraform state easily and
2021-10-27 15:23:28 +05:30
securely. It spares you from setting up additional remote resources like
Amazon S3 or Google Cloud Storage. Its features include:
- Supporting encryption of the state file both in transit and at rest.
- Locking and unlocking state.
- Remote Terraform plan and apply execution.
2022-04-04 11:22:00 +05:30
Read more about setting up and [using GitLab-managed Terraform states](terraform_state.md).
2021-10-27 15:23:28 +05:30
## 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.
2022-04-04 11:22:00 +05:30
## Terraform integration in merge requests
2021-10-27 15:23:28 +05:30
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
2022-04-04 11:22:00 +05:30
effects using the merge request pages. This way users don't have to build custom
2021-10-27 15:23:28 +05:30
tools or rely on 3rd party solutions to streamline their IaC workflows.
2021-11-11 11:23:49 +05:30
Read more on setting up and [using the merge request integrations](mr_integration.md).
2021-10-27 15:23:28 +05:30
## The GitLab Terraform provider
WARNING:
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.
The [documentation of the provider](https://registry.terraform.io/providers/gitlabhq/gitlab/latest/docs)
2022-04-04 11:22:00 +05:30
is available as part of the official Terraform provider documentation.
2021-10-27 15:23:28 +05:30
2022-05-07 20:08:51 +05:30
## Create a new cluster through IaC
2021-10-27 15:23:28 +05:30
2022-05-07 20:08:51 +05:30
- 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).
2022-01-26 12:08:38 +05:30
2021-10-27 15:23:28 +05:30
## Troubleshooting
2022-04-04 11:22:00 +05:30
See the [troubleshooting](troubleshooting.md) documentation.