Terraformモジュールレジストリ

Terraformモジュールレジストリを使用すると、次のことができます:

• GitLabプロジェクトをTerraformモジュールのプライベートレジストリとして使用する。
• GitLab CI/CDでモジュールを作成および公開し、他のプライベートプロジェクトから使用する。

Terraformモジュールレジストリに対して認証する

Terraformモジュールレジストリに対して認証するには、次のいずれかが必要です:

• 少なくともread_apiスコープを持つパーソナルアクセストークン。
• CI/CDジョブトークン。
• read_package_registryまたはwrite_package_registryスコープ、あるいはその両方を持つデプロイトークン。

APIを使用している場合:

• デプロイトークンで認証する場合は、write_package_registryスコープを適用してモジュールを公開する必要があります。モジュールをダウンロードするには、read_package_registryスコープを適用します。
• パーソナルアクセストークンで認証する場合は、少なくともread_apiスコープで設定する必要があります。

ここにドキュメント化されている方法以外の認証方法は使用しないでください。ドキュメント化されていない認証方法は、将来削除される可能性があります。

前提要件

Terraformモジュールを公開するには:

• デベロッパー以上のロールを持っている必要があります。

モジュールを削除するには:

• メンテナー以上のロールを持っている必要があります。

Terraformモジュールを公開する

Terraformモジュールを公開すると、モジュールが存在しない場合は作成されます。

Terraformモジュールを公開した後、Terraformモジュールレジストリページで表示できます。

APIの使用

TerraformモジュールレジストリAPIを使用して、Terraformモジュールを公開します。

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

リクエスト本文にファイルコンテンツを指定します。

リクエストは/fileで終わる必要があります。それ以外の文字列で終わるリクエストを送信すると、404 Not Foundエラーが発生します。

curl --fail-with-body --header "PRIVATE-TOKEN: <your_access_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

curl --fail-with-body --header "DEPLOY-TOKEN: <deploy_token>" \
     --upload-file path/to/file.tgz \
     --url "https://gitlab.example.com/api/v4/projects/<your_project_id>/packages/terraform/modules/<your_module>/<your_system>/0.0.1/file"

応答の例:

{
  "message":"201 Created"
}

CI/CDテンプレートの使用（推奨）

Terraform-Module.gitlab-ci.ymlまたは高度なTerraform/Module-Base.gitlab-ci.ymlCI/CDテンプレートを使用して、TerraformモジュールをGitLab Terraformモジュールレジストリに公開できます:

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

パイプラインには、次のジョブが含まれています:

• fmt: Terraformモジュールのフォーマットを検証します。
• kics-iac-sast: セキュリティ問題に関してTerraformモジュールをテストします。
• deploy: TerraformモジュールをTerraformモジュールレジストリにデプロイします（タグパイプラインのみ）。

パイプライン変数を使用する

次の変数を使用してパイプラインを設定します:

CI/CDを手動で構成する

GitLab CI/CDでTerraformモジュールを操作するには、コマンドで、パーソナルアクセストークンの代わりにCI_JOB_TOKENを使用します。

たとえば、このジョブは、localシステムプロバイダーの新しいモジュールをアップロードし、Gitコミットタグからモジュールバージョンを使用します:

stages:
  - deploy

upload:
  stage: deploy
  image: curlimages/curl:latest
  variables:
    TERRAFORM_MODULE_DIR: ${CI_PROJECT_DIR}    # The relative path to the root directory of the Terraform project.
    TERRAFORM_MODULE_NAME: ${CI_PROJECT_NAME}  # The name of your Terraform module, must not have any spaces or underscores (will be translated to hyphens).
    TERRAFORM_MODULE_SYSTEM: local             # The system or provider your Terraform module targets (ex. local, aws, google).
    TERRAFORM_MODULE_VERSION: ${CI_COMMIT_TAG} # The version - it's recommended to follow SemVer for Terraform Module Versioning.
  script:
    - TERRAFORM_MODULE_NAME=$(echo "${TERRAFORM_MODULE_NAME}" | tr " _" -) # module-name must not have spaces or underscores, so translate them to hyphens
    - tar -vczf /tmp/${TERRAFORM_MODULE_NAME}-${TERRAFORM_MODULE_SYSTEM}-${TERRAFORM_MODULE_VERSION}.tgz -C ${TERRAFORM_MODULE_DIR} --exclude=./.git .
    - 'curl --fail-with-body --location --header "JOB-TOKEN: ${CI_JOB_TOKEN}"
         --upload-file /tmp/${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タグをコミットに追加します。タグが、Terraformに必要なセマンティックバージョニングの仕様に従っていることを確認してください。rules:if: $CI_COMMIT_TAGを使用すると、リポジトリへのタグ付きコミットのみがモジュールのアップロードジョブをトリガーできます。

CI/CDパイプラインでジョブを制御するその他の方法については、CI/CD YAML構文リファレンスを参照してください。

モジュール解決のワークフロー

新しいモジュールをアップロードすると、GitLabはモジュールのパスを生成します。次に例を示します:

• https://gitlab.example.com/parent-group/my-infra-package

このパスは、Terraformモジュールレジストリプロトコルに準拠しています。パスの要素は次のとおりです:

• gitlab.example.comは、ホスト名です。
• parent-groupは、Terraformモジュールレジストリの一意のトップレベルネームスペースです。
• my-infra-packageは、モジュールの名前です。

重複が許可されていない場合、モジュール名とバージョンは、parent-groupの下にあるすべてのグループ、サブグループ、ロジェクトで一意である必要があります。そうでない場合は、次のエラーが返されます:

• {"message":"A module with the same name already exists in the namespace."}

重複が許可されている場合、モジュール解決は、最近公開されたモジュールに基づきます。

次に例を示します:

• プロジェクトがgitlab.example.com/parent-group/subgroup/my-projectである。
• Terraformモジュールがmy-infra-packageである。重複が許可されている場合、my-infra-packageは有効なモジュールです。重複が許可されていない場合、モジュール名は、parent-groupの下にあるすべてのグループ内のすべてのプロジェクトで一意である必要があります。

モジュールに名前を付けるときは、次の命名規則に留意してください:

• プロジェクト名とグループ名にドット（.）を含めることはできません。たとえば、source = "gitlab.example.com/my.group/project.name"は無効です。
• モジュールバージョンは、セマンティックバージョニングの仕様に従う必要があります。

Terraformモジュールの重複を許可する

デフォルトでは、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モジュールを表示する

プロジェクトまたはグループでTerraformモジュールを表示するには:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 左側のサイドバーで、操作 > Terraformモジュールを選択します。

このページでモジュールを検索、ソート、およびフィルタリングできます。

モジュールのREADMEファイルを表示するには:

1. Terraformモジュールレジストリページで、Terraformモジュールを選択します。
2. **README**を選択します。

Terraformモジュールを参照する

グループまたはプロジェクトからモジュールを参照します。

ネームスペースから

環境変数でterraformの認証トークン（ジョブトークン、パーソナルアクセストークン、またはデプロイトークン）を提供できます。

TF_TOKEN_プレフィックスを環境変数のドメイン名に追加し、ピリオドをアンダースコアとしてエンコードする必要があります。詳細については、環境変数の認証情報を参照してください。

たとえば、CLIがホスト名gitlab.comにサービスリクエストを行う場合、TF_TOKEN_gitlab_comという名前の変数の値はデプロイトークンとして使用されます:

export TF_TOKEN_gitlab_com='glpat-<deploy_token>'

この方法は、エンタープライズ向けの実装に適しています。ローカル環境または一時的な環境では、次のように~/.terraformrcファイルまたは%APPDATA%/terraform.rcファイルを作成することをお勧めします:

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

ここで、gitlab.comはGitLab Self-Managedインスタンスのホスト名に置き換えることができます。

その後、ダウンストリームのTerraformプロジェクトからTerraformモジュールを参照できます:

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

プロジェクトから

プロジェクトのソースを使用してTerraformモジュールを参照するには、Terraformで提供される、HTTP経由でアーカイブを取得するソースタイプを使用します。

次のようにterraformの認証トークン（ジョブトークン、パーソナルアクセストークン、またはデプロイトークン）を~/.netrcファイルで指定できます:

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

ここで、gitlab.comはGitLab Self-Managedインスタンスのホスト名に、<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>を省略可能です。とはいえ将来の問題を防ぐために、可能な場合は特定のバージョンを参照するようにしてください。

同じネームスペースに重複するモジュール名がある場合、ネームスペースレベルからモジュールを参照すると、最近公開されたモジュールがインストールされます。重複するモジュールの特定のバージョンを参照するには、プロジェクトレベルのソースタイプを使用します。

Terraformモジュールをダウンロードする

Terraformモジュールをダウンロードするには:

1. 左側のサイドバーで、操作 > Terraformモジュールを選択します。
2. ダウンロードするモジュールの名前を選択します。
3. アセットテーブルから、ダウンロードするモジュールを選択します。

Terraformモジュールを削除する

Terraformモジュールレジストリで公開した後、Terraformモジュールを編集することはできません。代わりに、削除して再作成する必要があります。

パッケージAPIまたはUIを使用してモジュールを削除できます。

UIでモジュールを削除するには、プロジェクトから次の手順を実行します:

1. 左側のサイドバーで、操作 > Terraformモジュールを選択します。
2. 削除するパッケージの名前を見つけます。
3. 削除を選択します。

パッケージは完全に削除されます。

Terraformモジュールレジストリを無効にする

Terraformモジュールレジストリは自動的に有効になります。

GitLab Self-Managedインスタンスの場合、GitLab管理者はパッケージとレジストリを無効にできます。これにより、このメニュー項目がサイドバーから削除されます。

次のように、特定のプロジェクトのTerraformモジュールレジストリを削除することもできます:

1. プロジェクトで、設定 > 一般に移動します。
2. 可視性、プロジェクトの機能、権限セクションを展開し、パッケージをオフに切り替えます。
3. 変更を保存を選択します。

プロジェクトの例

Terraformモジュールレジストリの例については、以下のプロジェクトを確認してください:

• _GitLabローカルファイル_プロジェクトは、最小限のTerraformモジュールを作成し、GitLab CI/CDを使用してTerraformモジュールレジストリにアップロードします。
• _Terraformモジュールテスト_プロジェクトは、前の例のモジュールを使用します。