# 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 ```