Commit d8652e92 authored by Marcia Ramos's avatar Marcia Ramos

Merge branch 'docs-iac-review-part1' into 'master'

Docs: IaC review (overview)

See merge request gitlab-org/gitlab!80422
parents 8fe1ee4b 1472156f
...@@ -6,68 +6,98 @@ info: To determine the technical writer assigned to the Stage/Group associated w ...@@ -6,68 +6,98 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Infrastructure as Code with Terraform and GitLab **(FREE)** # Infrastructure as Code with Terraform and GitLab **(FREE)**
With Terraform in GitLab, you can use GitLab authentication and authorization with To manage your infrastructure with GitLab, you can use the integration with
your GitOps and Infrastructure-as-Code (IaC) workflows. Terraform to define resources that you can version, reuse, and share:
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.
- 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 ## Integrate your project with Terraform
> SAST test was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/6655) in GitLab 14.6. > 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 The integration with GitLab and Terraform happens through GitLab CI/CD.
to your `.gitlab-ci.yml` file: Use an `include` attribute to add the Terraform template to your project and
customize from there.
```yaml To get started, choose the template that best suits your needs:
include:
- template: Terraform.latest.gitlab-ci.yml
variables: - [Latest template](#latest-terraform-template)
# If you do not use the GitLab HTTP backend, remove this line and specify TF_HTTP_* variables - [Stable template and advanced template](#stable-and-advanced-terraform-templates)
TF_STATE_NAME: default
TF_CACHE_KEY: default
# If your terraform files are in a subdirectory, set TF_ROOT accordingly
# TF_ROOT: terraform/production
```
The `Terraform.latest.gitlab-ci.yml` template: All templates:
- Uses the latest [GitLab Terraform image](https://gitlab.com/gitlab-org/terraform-images). - Use 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. 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): - Trigger four pipeline stages: `test`, `validate`, `build`, and `deploy`.
`test`, `validate`, `build`, and `deploy`. These stages - Run Terraform commands: `test`, `validate`, `plan`, and `plan-json`. It also runs the `apply` only on the default branch.
[run the Terraform commands](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform/Base.latest.gitlab-ci.yml) - Run the [Terraform SAST scanner](../../application_security/iac_scanning/index.md#configure-iac-scanning-manually).
`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), ### Latest Terraform template
that you can disable by creating a `SAST_DISABLED` environment variable and setting it to `1`.
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.
You can safely use the latest Terraform template:
- If you use GitLab.com.
- If you use a self-managed instance updated with every new GitLab release.
### Stable and advanced Terraform templates
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:
You can override the values in the default template by updating your `.gitlab-ci.yml` file. 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 latest template might contain breaking changes between major GitLab releases. ```yaml
For a more stable template, we recommend: 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
```
- [A ready-to-use version](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Terraform.gitlab-ci.yml) 1. Add the variables as described below:
- [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: ```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
```
<div class="video-fallback"> 1. (Optional) Override in your `.gitlab-ci.yaml` file the attributes present
See the video: <a href="https://www.youtube.com/watch?v=iGXjUrkkzDI">Terraform with GitLab</a>. in the template you fetched to customize your configuration.
</div>
<figure class="video-container">
<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/language/settings/backends) [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 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) [Terraform HTTP backend](https://www.terraform.io/docs/language/settings/backends/http.html)
to securely store the state files in local storage (the default) or to securely store the state files in local storage (the default) or
[the remote store of your choice](../../../administration/terraform_state.md). [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 safely store your Terraform state. It spares you from setting up additional remote resources like
securely. It spares you from setting up additional remote resources like
Amazon S3 or Google Cloud Storage. Its features include: Amazon S3 or Google Cloud Storage. Its features include:
- Supporting encryption of the state file both in transit and at rest. - Supporting encryption of the state file both in transit and at rest.
...@@ -110,6 +140,7 @@ is available as part of the official Terraform provider documentation. ...@@ -110,6 +140,7 @@ is available as part of the official Terraform provider documentation.
- 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 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). - 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.
...@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings. ...@@ -23,7 +23,7 @@ recommend encrypting plan output or modifying the project visibility settings.
## Configure Terraform report artifacts ## Configure Terraform report artifacts
GitLab ships with a [pre-built CI template](index.md#integrate-your-project-with-terraform) that uses GitLab Managed Terraform state and integrates Terraform changes into merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup. GitLab [integrates with Terraform](index.md#integrate-your-project-with-terraform) through CI/CD templates that use GitLab-managed Terraform state and display Terraform changes on merge requests. We recommend customizing the pre-built image and relying on the `gitlab-terraform` helper provided within for a quick setup.
To manually configure a GitLab Terraform Report artifact: To manually configure a GitLab Terraform Report artifact:
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment