# Infrastructure as code with Terraform and GitLab > 原文：[https://docs.gitlab.com/ee/user/infrastructure/index.html](https://docs.gitlab.com/ee/user/infrastructure/index.html) * [Motivation](#motivation) * [GitLab managed Terraform State](#gitlab-managed-terraform-state) * [Permissions for using Terraform](#permissions-for-using-terraform) * [Get started using local development](#get-started-using-local-development) * [Get started using GitLab CI](#get-started-using-gitlab-ci) * [Configure the backend](#configure-the-backend) * [Example project](#example-project) * [Output Terraform Plan information into a merge request](#output-terraform-plan-information-into-a-merge-request) * [Example `.gitlab-ci.yaml` file](#example-gitlab-ciyaml-file) * [Multiple Terraform Plan reports](#multiple-terraform-plan-reports) # Infrastructure as code with Terraform and GitLab[](#infrastructure-as-code-with-terraform-and-gitlab "Permalink") ## Motivation[](#motivation "Permalink") GitLab 中的 Terraform 集成功能使您的 GitOps /基础设施即代码（IaC）工作流能够与 GitLab 的身份验证和授权结合在一起. 这些功能着重于降低团队采用 Terraform，在 GitLab 中有效协作以及支持 Terraform 最佳实践的准入门槛. ## GitLab managed Terraform State[](#gitlab-managed-terraform-state "Permalink") 在 GitLab 13.0 中[引入](https://gitlab.com/groups/gitlab-org/-/epics/2673) . [Terraform 远程后端](https://www.terraform.io/docs/backends/index.html)使您可以将状态文件存储在远程共享存储中. GitLab 使用[Terraform HTTP 后端](https://www.terraform.io/docs/backends/types/http.html)将状态文件安全地存储在本地存储（默认）或[您选择的远程存储中](../../administration/terraform_state.html) . 由 GitLab 管理的 Terraform 状态后端可以轻松安全地存储 Terraform 状态，并使您免于设置其他远程资源（如 Amazon S3 或 Google Cloud Storage）. 其功能包括： * 在传输和静止时都支持状态文件的加密. * 锁定和解锁状态. * 远程 Terraform 计划并执行. 要开始使用 GitLab 管理的 Terraform State，有两种不同的选择： * [Use a local machine](#get-started-using-local-development). * [Use GitLab CI](#get-started-using-gitlab-ci). ## Permissions for using Terraform[](#permissions-for-using-terraform "Permalink") 在 GitLab 版本 13.1 中，需要[维护者访问权限](../permissions.html)才能使用 GitLab 管理的 Terraform 状态后端. 在 GitLab 版本 13.2 和更高版本中，需要[维护者访问权限](../permissions.html)才能锁定，解锁和写入状态（使用`terraform apply` ），而需要[开发人员访问权限](../permissions.html)来读取状态（使用`terraform plan -lock=false` ）. ## Get started using local development[](#get-started-using-local-development "Permalink") 如果您计划仅运行`terraform plan`并从本地计算机上执行`terraform plan` `terraform apply`命令，这是一种入门的简单方法： 1. 在您的 GitLab 实例上创建项目. 2. 导航 **设置>常规，**并记下您的**项目名称**和**项目 ID** . 3. Define the Terraform backend in your Terraform project to be: ``` terraform { backend "http" { } } ``` 4. 使用`api`范围创建一个[个人访问令牌](../profile/personal_access_tokens.html) . 5. 在本地计算机上，运行`terraform init` ，传入以下选项，并用相关值替换`<YOUR-PROJECT-NAME>` ， `<YOUR-PROJECT-ID>` ， `<YOUR-USERNAME>`和`<YOUR-ACCESS-TOKEN>` . 此命令将初始化 Terraform 状态，并将该状态存储在 GitLab 项目中. 这个例子使用`gitlab.com` ： ``` terraform init \ -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>" \ -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \ -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \ -backend-config="username=<YOUR-USERNAME>" \ -backend-config="password=<YOUR-ACCESS-TOKEN>" \ -backend-config="lock_method=POST" \ -backend-config="unlock_method=DELETE" \ -backend-config="retry_wait_min=5" ``` Next, [configure the backend](#configure-the-backend). ## Get started using GitLab CI[](#get-started-using-gitlab-ci "Permalink") 如果您不想开始本地开发，也可以使用 GitLab CI 来运行`terraform plan`和`terraform apply`命令. Next, [configure the backend](#configure-the-backend). ## Configure the backend[](#configure-the-backend "Permalink") 执行`terraform init`命令后，必须配置 Terraform 后端和 CI YAML 文件： 1. 在 Terraform 项目中，通过在`.tf`文件（例如`backend.tf` ）中添加以下代码块来定义远程后端，以定义[HTTP](https://www.terraform.io/docs/backends/types/http.html)后端： ``` terraform { backend "http" { } } ``` 2. 在项目存储库的根目录中，配置`.gitlab-ci.yaml`文件. 本示例使用一个包含`gitlab-terraform`帮助器的预构建图像. 有关受支持的 Terraform 版本，请参见[GitLab Terraform Images 项目](https://gitlab.com/gitlab-org/terraform-images) . ``` image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest ``` 3. 在`.gitlab-ci.yaml`文件中，定义一些环境变量以简化开发. 在此示例中， `TF_ROOT`是必须执行 Terraform 命令的目录， `TF_ADDRESS`是该管道在其上运行的 GitLab 实例上的状态的 URL，并且`TF_ADDRESS`的最后路径段是 Terraform 状态的名称. 项目可能具有多个状态，并且该名称是任意的，因此在此示例中，我们将其设置为项目的名称，并确保使用基于缓存的缓存键在管道中的作业之间缓存`.terraform`目录.州名： ``` variables: TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} cache: key: ${CI_PROJECT_NAME} paths: - ${TF_ROOT}/.terraform ``` 4. 在`before_script` ，更改为`TF_ROOT` ： ``` before_script: - cd ${TF_ROOT} stages: - prepare - validate - build - deploy init: stage: prepare script: - gitlab-terraform init validate: stage: validate script: - gitlab-terraform validate plan: stage: build script: - gitlab-terraform plan - gitlab-terraform plan-json artifacts: name: plan paths: - ${TF_ROOT}/plan.cache reports: terraform: ${TF_ROOT}/plan.json apply: stage: deploy environment: name: production script: - gitlab-terraform apply dependencies: - plan when: manual only: - master ``` 5. 将项目推送到 GitLab，这将触发 CI 作业管道. 该管道运行`gitlab-terraform init` ， `gitlab-terraform validate`和`gitlab-terraform plan`命令. 以上`terraform`命令的输出应在作业日志中可见. ## Example project[](#example-project "Permalink") 请参阅使用 GitLab 和 Terraform 在自定义 VPC 中部署基本 AWS EC2 的[参考项目](https://gitlab.com/nicholasklick/gitlab-terraform-aws) . ## Output Terraform Plan information into a merge request[](#output-terraform-plan-information-into-a-merge-request "Permalink") 使用[GitLab Terraform Report 工件](../../ci/pipelines/job_artifacts.html#artifactsreportsterraform) ，您可以将`terraform plan`运行中的详细信息直接暴露到合并请求小部件中，使您能够查看有关 Terraform 将创建，修改或销毁的资源的统计信息. 让我们探索如何配置 GitLab Terraform Report 工件. 您可以使用包含上述`gitlab-terraform`帮助器的预构建映像，其中`gitlab-terraform plan-json`输出所需的工件，或者您可以按以下方式手动进行配置： 1. 为简单起见，让我们定义一些可重用的变量，以允许我们多次引用这些文件： ``` variables: PLAN: plan.cache PLAN_JSON: plan.json ``` 2. 安装`jq` ，这是一种[轻巧灵活的命令行 JSON 处理器](https://stedolan.github.io/jq/) . 3. 为特定的`jq`命令创建一个别名，该别名解析出我们要从`terraform plan`输出中提取的信息： ``` before_script: - apk --no-cache add jq - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" ``` **注意：**在使用 Bash 的发行版（例如，Ubuntu）中， `alias`语句不会在非交互模式下扩展. 如果您的管道失败并显示错误`convert_report: command not found` ，则可以通过在脚本中添加`shopt`命令来明确激活别名扩展： ``` before_script: - shopt -s expand_aliases - alias convert_report="jq -r '([.resource_changes[]?.change.actions?]|flatten)|{\"create\":(map(select(.==\"create\"))|length),\"update\":(map(select(.==\"update\"))|length),\"delete\":(map(select(.==\"delete\"))|length)}'" ``` 4. 定义运行`terraform plan`和`terraform show`的`script` . 这些命令通过管道`PLAN_JSON`输出并将相关位转换为存储变量`PLAN_JSON` . 此 JSON 用于创建[GitLab Terraform Report 工件](../../ci/pipelines/job_artifacts.html#artifactsreportsterraform) . Terraform 报告获取 Terraform `tfplan.json`文件. 收集的 Terraform 计划报告作为工件上传到 GitLab，并在合并请求中显示. ``` plan: stage: build script: - terraform plan -out=$PLAN - terraform show --json $PLAN | convert_report > $PLAN_JSON artifacts: reports: terraform: $PLAN_JSON ``` 有关使用预构建图像的完整示例，请参见[Example `.gitlab-ci.yaml`文件](#example-gitlab-ciyaml-file) . 有关显示多个报告的示例，请参见[`.gitlab-ci.yaml`多个报告文件](#multiple-terraform-plan-reports) . 5. 运行管道会在合并请求中显示小部件，如下所示： [](img/terraform_plan_widget_v13_2.png) 6. Clicking the **查看完整日志** button in the widget takes you directly to the plan output present in the pipeline logs: [](img/terraform_plan_log_v13_0.png) ### Example `.gitlab-ci.yaml` file[](#example-gitlab-ciyaml-file "Permalink") ``` image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest variables: TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME} cache: key: ${CI_PROJECT_NAME} paths: - ${TF_ROOT}/.terraform before_script: - cd ${TF_ROOT} stages: - prepare - validate - build - deploy init: stage: prepare script: - gitlab-terraform init validate: stage: validate script: - gitlab-terraform validate plan: stage: build script: - gitlab-terraform plan - gitlab-terraform plan-json artifacts: name: plan paths: - ${TF_ROOT}/plan.cache reports: terraform: ${TF_ROOT}/plan.json apply: stage: deploy environment: name: production script: - gitlab-terraform apply dependencies: - plan when: manual only: - master ``` ### Multiple Terraform Plan reports[](#multiple-terraform-plan-reports "Permalink") 从 13.2 开始，您可以在"合并请求"页面上显示多个报告. 报告还将显示`artifact: name:` 有关建议的设置，请参见下面的示例. ``` image: name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform entrypoint: - '/usr/bin/env' - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin' cache: paths: - .terraform stages: - build .terraform-plan-generation: stage: build variables: PLAN: plan.tfplan JSON_PLAN_FILE: tfplan.json before_script: - cd ${TERRAFORM_DIRECTORY} - terraform --version - terraform init - apk --no-cache add jq script: - terraform validate - terraform plan -out=${PLAN} - terraform show --json ${PLAN} | jq -r '([.resource_changes[]?.change.actions?]|flatten)|{"create":(map(select(.=="create"))|length),"update":(map(select(.=="update"))|length),"delete":(map(select(.=="delete"))|length)}' > ${JSON_PLAN_FILE} artifacts: reports: terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE} review_plan: extends: .terraform-plan-generation variables: TERRAFORM_DIRECTORY: "review/" # Review will not include an artifact name staging_plan: extends: .terraform-plan-generation variables: TERRAFORM_DIRECTORY: "staging/" artifacts: name: Staging production_plan: extends: .terraform-plan-generation variables: TERRAFORM_DIRECTORY: "production/" artifacts: name: Production ```