极狐 GitLab Logo

Terraform 状态管理

  • Tier: 基础版, 专业版, 旗舰版
  • Offering: 私有化部署

极狐GitLab 可以用作 Terraform 状态文件的后端。这些文件在存储之前会被加密。此功能默认启用。

这些文件的存储位置默认为：

  • 对于 Linux 软件包安装为 /var/opt/gitlab/gitlab-rails/shared/terraform_state。
  • 对于自编译安装为 /home/git/gitlab/shared/terraform_state。

可以使用下面描述的选项配置这些位置。

使用 外部对象存储 配置 极狐GitLab Helm chart 安装。

禁用 Terraform 状态#

您可以在整个实例中禁用 Terraform 状态。您可能希望禁用 Terraform 以减少磁盘空间，或者因为您的实例不使用 Terraform。

当 Terraform 状态管理被禁用时：

  • 在左侧边栏中，您无法选择 Operate > Terraform states。

  • 任何访问 Terraform 状态的 CI/CD 作业都会失败，并显示以下错误：

    shell
    Error refreshing state: HTTP remote state endpoint invalid auth

要根据您的安装禁用 Terraform 管理，请按照以下步骤操作。

先决条件：

  • 您必须是管理员。

对于 Linux 软件包安装：

  1. 编辑 /etc/gitlab/gitlab.rb 并添加以下行：

    ruby
    gitlab_rails['terraform_state_enabled'] = false

  2. 保存文件并 重新配置极狐GitLab 以使更改生效。

对于自编译安装：

  1. 编辑 /home/git/gitlab/config/gitlab.yml 并添加或修改以下行：

    yaml
    terraform_state:
  enabled: false

  2. 保存文件并 重启极狐GitLab 以使更改生效。

使用本地存储#

默认配置使用本地存储。要更改本地存储 Terraform 状态文件的位置，请按照以下步骤操作。

对于 Linux 软件包安装：

  1. 要更改存储路径，例如到 /mnt/storage/terraform_state，请编辑 /etc/gitlab/gitlab.rb 并添加以下行：

    ruby
    gitlab_rails['terraform_state_storage_path'] = "/mnt/storage/terraform_state"

  2. 保存文件并 重新配置极狐GitLab 以使更改生效。

对于自编译安装：

  1. 要更改存储路径，例如到 /mnt/storage/terraform_state，请编辑 /home/git/gitlab/config/gitlab.yml 并添加或修改以下行：

    yaml
    terraform_state:
  enabled: true
  storage_path: /mnt/storage/terraform_state

  2. 保存文件并 重启极狐GitLab 以使更改生效。

使用对象存储#

  • Tier: 基础版，专业版，旗舰版
  • Offering: 极狐GitLab 私有化部署

我们推荐使用 支持的对象存储选项之一 来替代在磁盘上存储 Terraform 状态文件。此配置依赖于已经配置好的有效凭据。

了解更多关于在极狐GitLab 中使用对象存储的信息。

对象存储设置#

以下设置是：

  • 在 Linux 软件包安装中以 terraform_state_object_store_ 为前缀。
  • 在自编译安装中嵌套在 terraform_state: 和 object_store: 下。
设置描述默认值
enabled启用/禁用对象存储false
remote_directory存储 Terraform 状态文件的桶名
connection下面描述的各种连接选项

迁移到对象存储#

无法将 Terraform 状态文件从对象存储迁移回本地存储，因此请谨慎操作。

要将 Terraform 状态文件迁移到对象存储：

  • 对于 Linux 软件包安装：

    shell
    gitlab-rake gitlab:terraform_states:migrate

  • 对于自编译安装：

    shell
    sudo -u git -H bundle exec rake gitlab:terraform_states:migrate RAILS_ENV=production

您可以选择跟踪进度并使用 PostgreSQL 控制台 验证所有 Terraform 状态文件是否成功迁移：

  • sudo gitlab-rails dbconsole --database main 适用于 Linux 软件包安装。
  • sudo -u git -H psql -d gitlabhq_production 适用于自编译安装。

验证下面 objectstg（其中 file_store=2）是否具有所有状态的计数：

shell
gitlabhq_production=# SELECT count(*) AS total, sum(case when file_store = '1' then 1 else 0 end) AS filesystem, sum(case when file_store = '2' then 1 else 0 end) AS objectstg FROM terraform_state_versions;

total | filesystem | objectstg
------+------------+-----------
   15 |          0 |      15

验证在 terraform_state 文件夹中没有磁盘上的文件：

shell
sudo find /var/opt/gitlab/gitlab-rails/shared/terraform_state -type f | grep -v tmp | wc -l

S3 兼容的连接设置#

您应该使用 统一的对象存储设置。本节描述了早期的配置格式。

参见 不同提供商的可用连接设置。

  1. 编辑 /etc/gitlab/gitlab.rb 并添加以下行；用您想要的值替换：

    ruby
    1gitlab_rails['terraform_state_object_store_enabled'] = true
2gitlab_rails['terraform_state_object_store_remote_directory'] = "terraform"
3gitlab_rails['terraform_state_object_store_connection'] = {
4  'provider' => 'AWS',
5  'region' => 'eu-central-1',
6  'aws_access_key_id' => 'AWS_ACCESS_KEY_ID',
7  'aws_secret_access_key' => 'AWS_SECRET_ACCESS_KEY'
8}
如果您使用 AWS IAM 配置文件，请确保省略 AWS 访问密钥和秘密访问密钥/值对。
ruby
gitlab_rails['terraform_state_object_store_connection'] = {
  'provider' => 'AWS',
  'region' => 'eu-central-1',
  'use_iam_profile' => true
}
  1. 保存文件并 重新配置极狐GitLab 以使更改生效。
  2. 迁移任何现有的本地状态到对象存储

查找 Terraform 状态文件路径#

Terraform 状态文件存储在相关项目的哈希目录路径中。

路径的格式为 /var/opt/gitlab/gitlab-rails/shared/terraform_state/<path>/<to>/<projectHashDirectory>/<UUID>/0.tfstate，其中 UUID 是随机定义的。

要查找状态文件路径：

  1. 将 get-terraform-path 添加到您的 shell：

    shell
    get-terraform-path() {
    PROJECT_HASH=$(echo -n $1 | openssl dgst -sha256 | sed 's/^.* //')
    echo "${PROJECT_HASH:0:2}/${PROJECT_HASH:2:2}/${PROJECT_HASH}"
}

  2. 运行 get-terraform-path <project_id>。

    shell
    $ get-terraform-path 650
20/99/2099a9b5f777e242d1f9e19d27e232cc71e2fa7964fc988a319fce5671ca7f73

相对路径显示出来。

从备份中恢复 Terraform 状态文件#

要从备份中恢复 Terraform 状态文件，您必须能够访问加密的状态文件和极狐GitLab 数据库。

数据库表#

以下数据库表有助于将 S3 路径追溯到特定项目：

  • terraform_states: 包含基本状态信息，包括每个状态的全局唯一 ID (UUID)。

文件结构和路径组成#

状态文件存储在一个特定的目录结构中，其中：

  • 路径的前三个段是从项目 ID 的 SHA-2 哈希值派生的。
  • 每个状态都有一个存储在 terraform_states 数据库表中的 UUID，形成路径的一部分。

例如，对于一个项目，其：

  • 项目 ID 是 12345
  • 状态 UUID 是 example-uuid

如果 12345 的 SHA-2 哈希值是 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5，那么文件夹结构将是：

plaintext
1terraform/                                                                 <- 配置的 Terraform 存储目录
2├─ 59/                                                                     <- 项目 ID 哈希的第一个和第二个字符
3|  ├─ 94/                                                                  <- 项目 ID 哈希的第三个和第四个字符
4|  |  ├─ 5994471abb01112afcc18159f6cc74b4f511b99806da59b3caf5a9c173cacfc5/ <- 完整的项目 ID 哈希
5|  |  |  ├─ example-uuid/                                                  <- 状态 UUID
6|  |  |  |  ├─ 1.tf                                                        <- 单个状态版本
7|  |  |  |  ├─ 2.tf
8|  |  |  |  ├─ 3.tf

解密过程#

状态文件使用 Lockbox 加密，需要以下信息进行解密：

加密密钥是从 db_key_base 和项目 ID 派生的。如果您无法访问 db_key_base，则无法解密。