如何使用極狐GitLab 軟件包倉庫功能托管 terraform？

極狐GitLab 是 GitLab 在中國的發行版，關于中文參考文檔和資料有：

極狐GitLab 中文文檔
極狐GitLab 中文論壇
極狐GitLab 官網

Terraform 模塊庫 (BASIC ALL)

基礎設施倉庫和 Terraform 模塊倉庫合并到單個 Terraform 模塊倉庫功能引入于極狐GitLab 15.11。
對于群組的支持引入于極狐GitLab 16.9。

借助 Terraform 模塊庫，您可以將極狐GitLab 項目用作 Terraform 模塊私有庫。您可以使用極狐GitLab CI/CD 創建和發布模塊，然后可以從其他私有項目中使用這些模塊。

查看 Terraform 模塊

對于 Readme 文件的支持引入于極狐GitLab 17.2。

查看項目中的 Terraform 模塊：

1.進入項目。
2.在左側邊欄中，選擇 軟件包和鏡像庫 > Terraform 模塊。

您可以在此頁面上搜索、排序和過濾模塊。
有關如何創建和上傳軟件包的信息，請查看適用于您的軟件包類型的極狐GitLab 文檔：

Terraform 模塊庫身份驗證

要對 Terraform 模塊庫進行身份驗證，您需要：

至少具有 read_api 權限的個人訪問令牌。
CI/CD 作業令牌。
一個具有 read_package_registry 或/和 write_package_registry 范圍的部署令牌。

不要使用此處記錄的方法以外的身份驗證方法。將來可能會刪除未記錄的身份驗證方法。

發布 Terraform 模塊

當您發布 Terraform 模塊時，如果它不存在，則會創建它。
先決條件：

頂級命名空間中必須不存在具有相同名稱和版本的包。
您的項目和組名稱不得包含點 (.)。例如，source = "gitlab.example.com/my.group/project.name"。
您必須使用 API 進行身份驗證。如果使用部署令牌進行身份驗證，則必須使用 write_package_registry 范圍進行配置。
除非允許重復的 Terraform 模塊，否則模塊名稱必須在其群組的范圍內是唯一的，否則會發生錯誤。

PUT /projects/:id/packages/terraform/modules/:module-name/:module-system/:module-version/file

屬性	類型	是否必需	描述
`id`	integer/string	yes	ID 或項目的 URL 編碼路徑。
`module-name`	string	yes	模塊名稱。支持的語法：1 到 64 個 ASCII 字符，包括小寫字母 (a-z)、數字 (0-9) 和連字符 (`-`)。
`module-system`	string	yes	模塊系統。支持的語法：1 到 64 個 ASCII 字符，包括小寫字母 (a-z)、數字 (0-9) 和連字符 (`-`)。查看更多信息：Terraform Module Registry Protocol documentation。
`module-version`	string	yes	模塊版本。根據語義版本規范，它必須是有效的。

在請求正文中提供文件內容。

請注意，在以下示例中，請求必須以 /file 結尾。
如果您發送以其他內容結尾的請求，則會導致 404 錯誤 {"error":"404 Not Found"}。

使用個人訪問令牌的示例請求：

curl --header "PRIVATE-TOKEN: <your_access_token>" \--upload-file path/to/file.tgz \"https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

使用部署令牌的示例請求：

curl --header "DEPLOY-TOKEN: <deploy_token>" \--upload-file path/to/file.tgz \"https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/my-module/my-system/0.0.1/file"

示例響應：

{"message":"201 Created"
}

使用 CI/CD 模板（推薦）

引入于 15.9 版本。

您可以使用 Terraform-Module.gitlab-ci.yml 或高級 Terraform/Module-Base.gitlab-ci.yml CI/CD 模板，將 Terraform 模塊發布到極狐GitLab terraform 庫：

include:template: Terraform-Module.gitlab-ci.yml

流水線包含以下作業：

fmt - 驗證 Terraform 模塊的格式。
kics-iac-sast - 測試 Terraform 模塊的安全問題。
deploy - 僅適用于標簽流水線。將 Terraform 模塊部署到 Terraform 模塊庫。

流水線變量

您可以使用以下變量配置流水線：

變量	默認值	描述
`TERRAFORM_MODULE_DIR`	`${CI_PROJECT_DIR}`	Terraform 項目根目錄的相對路徑。
`TERRAFORM_MODULE_NAME`	`${CI_PROJECT_NAME}`	Terraform 模塊的名稱。不得包含任何空格或下劃線。
`TERRAFORM_MODULE_SYSTEM`	`local`	Terraform 模塊目標的系統或提供者。例如，`local`、`aws`、`google`。
`TERRAFORM_MODULE_VERSION`	`${CI_COMMIT_TAG}`	Terraform 模塊版本。您應該遵循語義版本控制規范。

手動使用 CI/CD

要在極狐GitLab CI/CD 中使用 Terraform 模塊，您可以使用 CI_JOB_TOKEN 代替命令中的個人訪問令牌。
例如：

stages:- uploadupload:stage: uploadimage: curlimages/curl:latestvariables:TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR} # The path to your Terraform moduleTERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME} # The name of your Terraform moduleTERRAFORM_MODULE_SYSTEM: local # The system or provider your Terraform module targets (ex. local, aws, google)TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # Tag commits with SemVer for the version of your Terraform module to be publishedscript:- TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens- tar -vczf ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git .- 'curl --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}"--upload-file ${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/terraform/modules/${TERRAFORM_MODULE_NAME}/${TERRAFORM_MODULE_SYSTEM}/${TERRAFORM_MODULE_VERSION}/file'rules:- if: $CI_COMMIT_TAG

要觸發此上傳作業，請將 Git 標簽添加到您的提交中。rules:if: $CI_COMMIT_TAG 定義這一點，因此不是每次提交到您的倉庫都會觸發上傳。有關在 CI/CD 流水線中控制作業的其他方法，請參閱 .gitlab-ci.yml 關鍵字參考。

允許重復的 terraform 模塊

引入于極狐GitLab 16.8。
在極狐GitLab 17.0 中，需要的角色從維護者更改為所有者。

默認情況下，Terraform 模塊倉庫強制對同一命名空間中的模塊名稱進行唯一性檢查。

要允許發布重復的模塊名稱：

1.在左側邊欄中，選擇 搜索或轉到 并找到您的群組。
2.選擇 設置 > 軟件包和鏡像庫。
3.在 Terraform 模塊 的 重復的軟件包 表中，關閉 允許重復 開關。
4.可選的。在異常文本框中，輸入匹配允許重復的包的名稱的正則表達式。

您的更改將自動保存。

您還可以通過在 GraphQL API 中啟用 terraform_module_duplicates_allowed 來允許發布重復的模塊名稱。

要允重復的特定名稱：

1.確保 terraform_module_duplicates_allowed 未啟用。
2.使用 terraform_module_duplicate_exception_regex 來定義允許重復的模塊名稱的正則表達式。

頂級命名空間設置優先于子命名空間設置。比如，如果您為群組啟用了 terraform_module_duplicates_allowed，并在子群組中禁用它，則在群組和子群組中的所有項目允許模塊名稱重復。

引用 Terraform 模塊

先決條件：

您需要使用 API 進行身份驗證。如果使用個人訪問令牌進行身份驗證，則必須使用 read_api 范圍進行配置。

從命名空間中

您可以在環境變量中為 terrafrom 提供認證令牌（作業令牌、個人訪問令牌或部署令牌）。

您應該為環境變量的域名名稱添加前綴 TF_TOKEN_，將點號編碼為下劃線。

比如，當 CLI 向 jihulab.com 發送服務請求時，使用名為 TF_TOKEN_jihulab_com 的變量的值作為部署令牌。

export TF_TOKEN_gitlab_com='glpat-<deploy_token>'

此方法首選于企業實現。對于本地或臨時環境，您可能希望創建 .terraformrc 或 %APPDATA%/terraform.rc 文件：

credentials "jihulab.com" {token = "<TOKEN>"
}

將其中的 jihulab.com 替換為您私有化部署實例的主機名。

隨后，您可以從下游 Terraform 項目中引用您的 Terraform 模塊:

module "<module>" {source = "jihulab.com/<namespace>/<module-name>/<module-system>"
}

其中，<namespace> 是 Terraform 模塊注冊倉庫的命名空間。

從項目中

要引用一個使用項目級別資源的 Terraform 模塊，您可以使用 Terraform 提供的通過 HTTP 獲取歸檔源類型。

您可以在 ~/.netrc 文件中為 terraform 提供認證令牌（作業令牌、個人訪問令牌或部署令牌）：

machine jihulab.com
login <USERNAME>
password <TOKEN>

其中，jihulab.com 可以替換為私有化部署實例的主機名，<USERNAME> 是您的令牌用戶名。

您可以從下游 Terraform 項目中引用您的 Terraform 模塊:

module "<module>" {source = "https://gitlab.com/api/v4/projects/<project-id>/packages/terraform/modules/<module-name>/<module-system>/<module-version>"
}

如果您需要引用最新版本的模塊，您可以從源 URL 中省略 <module-version>。為了防止未來出現問題，您應盡量引用特定版本。

如果在相同的命名空間中存在重復的模塊名稱，從命名空間級別引用模塊會安裝最近發布的模塊。要引用特定版本的重復模塊，請使用 項目級別 源類型。