Infrastructure as code with Terraform and GitLab

原文:https://docs.gitlab.com/ee/user/infrastructure/index.html

Infrastructure as code with Terraform and GitLab

Motivation

GitLab 中的 Terraform 集成功能使您的 GitOps /基础设施即代码(IaC)工作流能够与 GitLab 的身份验证和授权结合在一起. 这些功能着重于降低团队采用 Terraform,在 GitLab 中有效协作以及支持 Terraform 最佳实践的准入门槛.

GitLab managed Terraform State

在 GitLab 13.0 中引入 .

Terraform 远程后端使您可以将状态文件存储在远程共享存储中. GitLab 使用Terraform HTTP 后端将状态文件安全地存储在本地存储(默认)或您选择的远程存储中 .

由 GitLab 管理的 Terraform 状态后端可以轻松安全地存储 Terraform 状态,并使您免于设置其他远程资源(如 Amazon S3 或 Google Cloud Storage). 其功能包括:

  • 在传输和静止时都支持状态文件的加密.
  • 锁定和解锁状态.
  • 远程 Terraform 计划并执行.

要开始使用 GitLab 管理的 Terraform State,有两种不同的选择:

Permissions for using Terraform

在 GitLab 版本 13.1 中,需要维护者访问权限才能使用 GitLab 管理的 Terraform 状态后端. 在 GitLab 版本 13.2 和更高版本中,需要维护者访问权限才能锁定,解锁和写入状态(使用terraform apply ),而需要开发人员访问权限来读取状态(使用terraform plan -lock=false ).

Get started using local development

如果您计划仅运行terraform plan并从本地计算机上执行terraform plan terraform apply命令,这是一种入门的简单方法:

  1. 在您的 GitLab 实例上创建项目.
  2. 导航 设置>常规,并记下您的项目名称项目 ID .
  3. Define the Terraform backend in your Terraform project to be:

    1. terraform {
    2. backend "http" {
    3. }
    4. }
  4. 使用api范围创建一个个人访问令牌 .

  5. 在本地计算机上,运行terraform init ,传入以下选项,并用相关值替换<YOUR-PROJECT-NAME><YOUR-PROJECT-ID><YOUR-USERNAME><YOUR-ACCESS-TOKEN> . 此命令将初始化 Terraform 状态,并将该状态存储在 GitLab 项目中. 这个例子使用gitlab.com

    1. terraform init \
    2. -backend-config="address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>" \
    3. -backend-config="lock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \
    4. -backend-config="unlock_address=https://gitlab.com/api/v4/projects/<YOUR-PROJECT-ID>/terraform/state/<YOUR-PROJECT-NAME>/lock" \
    5. -backend-config="username=<YOUR-USERNAME>" \
    6. -backend-config="password=<YOUR-ACCESS-TOKEN>" \
    7. -backend-config="lock_method=POST" \
    8. -backend-config="unlock_method=DELETE" \
    9. -backend-config="retry_wait_min=5"

Next, configure the backend.

Get started using GitLab CI

如果您不想开始本地开发,也可以使用 GitLab CI 来运行terraform planterraform apply命令.

Next, configure the backend.

Configure the backend

执行terraform init命令后,必须配置 Terraform 后端和 CI YAML 文件:

  1. 在 Terraform 项目中,通过在.tf文件(例如backend.tf )中添加以下代码块来定义远程后端,以定义HTTP后端:

    1. terraform {
    2. backend "http" {
    3. }
    4. }
  2. 在项目存储库的根目录中,配置.gitlab-ci.yaml文件. 本示例使用一个包含gitlab-terraform帮助器的预构建图像. 有关受支持的 Terraform 版本,请参见GitLab Terraform Images 项目 .

    1. 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目录.州名:

    1. variables:
    2. TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production
    3. TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME}
    4. cache:
    5. key: ${CI_PROJECT_NAME}
    6. paths:
    7. - ${TF_ROOT}/.terraform
  4. before_script ,更改为TF_ROOT

    1. before_script:
    2. - cd ${TF_ROOT}
    3. stages:
    4. - prepare
    5. - validate
    6. - build
    7. - deploy
    8. init:
    9. stage: prepare
    10. script:
    11. - gitlab-terraform init
    12. validate:
    13. stage: validate
    14. script:
    15. - gitlab-terraform validate
    16. plan:
    17. stage: build
    18. script:
    19. - gitlab-terraform plan
    20. - gitlab-terraform plan-json
    21. artifacts:
    22. name: plan
    23. paths:
    24. - ${TF_ROOT}/plan.cache
    25. reports:
    26. terraform: ${TF_ROOT}/plan.json
    27. apply:
    28. stage: deploy
    29. environment:
    30. name: production
    31. script:
    32. - gitlab-terraform apply
    33. dependencies:
    34. - plan
    35. when: manual
    36. only:
    37. - master
  5. 将项目推送到 GitLab,这将触发 CI 作业管道. 该管道运行gitlab-terraform initgitlab-terraform validategitlab-terraform plan命令.

以上terraform命令的输出应在作业日志中可见.

Example project

请参阅使用 GitLab 和 Terraform 在自定义 VPC 中部署基本 AWS EC2 的参考项目 .

Output Terraform Plan information into a merge request

使用GitLab Terraform Report 工件 ,您可以将terraform plan运行中的详细信息直接暴露到合并请求小部件中,使您能够查看有关 Terraform 将创建,修改或销毁的资源的统计信息.

让我们探索如何配置 GitLab Terraform Report 工件. 您可以使用包含上述gitlab-terraform帮助器的预构建映像,其中gitlab-terraform plan-json输出所需的工件,或者您可以按以下方式手动进行配置:

  1. 为简单起见,让我们定义一些可重用的变量,以允许我们多次引用这些文件:

    1. variables:
    2. PLAN: plan.cache
    3. PLAN_JSON: plan.json
  2. 安装jq ,这是一种轻巧灵活的命令行 JSON 处理器 .

  3. 为特定的jq命令创建一个别名,该别名解析出我们要从terraform plan输出中提取的信息:

    1. before_script:
    2. - apk --no-cache add jq
    3. - 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命令来明确激活别名扩展:

    1. before_script:
    2. - shopt -s expand_aliases
    3. - 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 planterraform showscript . 这些命令通过管道PLAN_JSON输出并将相关位转换为存储变量PLAN_JSON . 此 JSON 用于创建GitLab Terraform Report 工件 . Terraform 报告获取 Terraform tfplan.json文件. 收集的 Terraform 计划报告作为工件上传到 GitLab,并在合并请求中显示.

    1. plan:
    2. stage: build
    3. script:
    4. - terraform plan -out=$PLAN
    5. - terraform show --json $PLAN | convert_report > $PLAN_JSON
    6. artifacts:
    7. reports:
    8. terraform: $PLAN_JSON

    有关使用预构建图像的完整示例,请参见Example .gitlab-ci.yaml文件 .

    有关显示多个报告的示例,请参见.gitlab-ci.yaml多个报告文件 .

  5. 运行管道会在合并请求中显示小部件,如下所示:

    Merge Request Terraform widget

  6. Clicking the 查看完整日志 button in the widget takes you directly to the plan output present in the pipeline logs:

    Terraform plan logs

Example .gitlab-ci.yaml file

  1. image: registry.gitlab.com/gitlab-org/terraform-images/stable:latest
  2. variables:
  3. TF_ROOT: ${CI_PROJECT_DIR}/environments/cloudflare/production
  4. TF_ADDRESS: ${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/terraform/state/${CI_PROJECT_NAME}
  5. cache:
  6. key: ${CI_PROJECT_NAME}
  7. paths:
  8. - ${TF_ROOT}/.terraform
  9. before_script:
  10. - cd ${TF_ROOT}
  11. stages:
  12. - prepare
  13. - validate
  14. - build
  15. - deploy
  16. init:
  17. stage: prepare
  18. script:
  19. - gitlab-terraform init
  20. validate:
  21. stage: validate
  22. script:
  23. - gitlab-terraform validate
  24. plan:
  25. stage: build
  26. script:
  27. - gitlab-terraform plan
  28. - gitlab-terraform plan-json
  29. artifacts:
  30. name: plan
  31. paths:
  32. - ${TF_ROOT}/plan.cache
  33. reports:
  34. terraform: ${TF_ROOT}/plan.json
  35. apply:
  36. stage: deploy
  37. environment:
  38. name: production
  39. script:
  40. - gitlab-terraform apply
  41. dependencies:
  42. - plan
  43. when: manual
  44. only:
  45. - master

Multiple Terraform Plan reports

从 13.2 开始,您可以在”合并请求”页面上显示多个报告. 报告还将显示artifact: name: 有关建议的设置,请参见下面的示例.

  1. image:
  2. name: registry.gitlab.com/gitlab-org/gitlab-build-images:terraform
  3. entrypoint:
  4. - '/usr/bin/env'
  5. - 'PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin'
  6. cache:
  7. paths:
  8. - .terraform
  9. stages:
  10. - build
  11. .terraform-plan-generation:
  12. stage: build
  13. variables:
  14. PLAN: plan.tfplan
  15. JSON_PLAN_FILE: tfplan.json
  16. before_script:
  17. - cd ${TERRAFORM_DIRECTORY}
  18. - terraform --version
  19. - terraform init
  20. - apk --no-cache add jq
  21. script:
  22. - terraform validate
  23. - terraform plan -out=${PLAN}
  24. - 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}
  25. artifacts:
  26. reports:
  27. terraform: ${TERRAFORM_DIRECTORY}/${JSON_PLAN_FILE}
  28. review_plan:
  29. extends: .terraform-plan-generation
  30. variables:
  31. TERRAFORM_DIRECTORY: "review/"
  32. # Review will not include an artifact name
  33. staging_plan:
  34. extends: .terraform-plan-generation
  35. variables:
  36. TERRAFORM_DIRECTORY: "staging/"
  37. artifacts:
  38. name: Staging
  39. production_plan:
  40. extends: .terraform-plan-generation
  41. variables:
  42. TERRAFORM_DIRECTORY: "production/"
  43. artifacts:
  44. name: Production