本文へスキップ

モジュールソース

moduleブロック内のsource引数は、OpenTofuに目的のチャイルドモジュールのソースコードの場所を指示します。

OpenTofuは、tofu initのモジュールインストールステップ中にこの情報を使用して、ソースコードをローカルディスクのディレクトリにダウンロードし、他のOpenTofuコマンドで使用できるようにします。

モジュールインストーラは、様々なソースタイプからのインストールをサポートしています。

これらそれぞれについては、以下のセクションで説明します。モジュールソースアドレスは、URLのような構文を使用しますが、ソースの明確な選択と追加機能をサポートするために拡張されています。

主に繰り返しコード要素を抽出する目的で使用される密接に関連するモジュールにはローカルファイルパスを使用し、複数の呼び出し構成で共有することを目的としたモジュールにはネイティブOpenTofuモジュールレジストリを使用することをお勧めします。既存のインフラストラクチャを使用してOpenTofuモジュールを内部的に配布できるように、他のソースもサポートしています。

多くのソースタイプは、環境変数やホームディレクトリの資格情報ファイルなど、OpenTofuの実行時に利用可能な「環境」資格情報を使用します。これについては、以下の各セクションで詳しく説明します。

再利用可能なモジュールはそれぞれ、独自のレポジトリまたはアーカイブファイルのルートに配置することをお勧めしますが、サブディレクトリからモジュールを参照することも可能です。

ローカルパス​

ローカルパス参照により、単一のソースリポジトリ内で構成の一部を抽出できます。

コードブロック
module "consul" {
  source = "./consul"
}

ローカルパスは、モジュールレジストリアドレスと区別するために、ローカルパスであることを示す./または../で始まる必要があります。

ローカルパスは、他のソースと同様に「インストール」されないという点で特殊です。ファイルは既にローカルディスク上に存在する（親モジュールのインストールの結果である可能性があります）ため、直接使用できます。親モジュールがアップグレードされると、そのソースコードは自動的に更新されます。

OpenTofuは、（スラッシュ、ドライブ文字などで始まる）絶対ファイルシステムパスをローカルパスとは見なしません。代わりに、OpenTofuはそれをリモートモジュールと同様に扱い、ローカルモジュールキャッシュにコピーします。絶対パスは、パッケージサブディレクトリ内のモジュールで説明されている意味での「パッケージ」です。絶対ファイルシステムパスを使用してモジュールを参照することはお勧めしません。これは、特定のコンピュータのファイルシステムレイアウトに構成を結び付ける傾向があるためです。

モジュールレジストリ​

モジュールレジストリは、モジュールのバージョン管理を完全にサポートするOpenTofu固有のプロトコルを使用して、複数の構成間でモジュールを配布するネイティブな方法です。

公開OpenTofuレジストリは、このプロトコルを使用して公開で共有されているモジュールのインデックスです。この公開レジストリは、OpenTofuを始めることと、コミュニティで他の人が作成したモジュールを見つけるための最も簡単な方法です。

プライベートレジストリも、TACOS（TF Automation and Collaboration Software）経由、またはモジュールレジストリプロトコルを実装するカスタムサービスを実行することで使用できます。

公開レジストリ上のモジュールは、<NAMESPACE>/<NAME>/<PROVIDER>形式のレジストリソースアドレスを使用して参照できます。レジストリサイト上の各モジュールの情報ページには、使用する正確なアドレスが含まれています。

コードブロック
module "consul" {
  source = "hashicorp/consul/aws"
  version = "0.1.0"
}

上記の例では、公開レジストリからAWSのConsulモジュールを使用します。

他のレジストリにホストされているモジュールについては、プライベートレジストリのホスト名を指定する追加の<HOSTNAME>/部分をソースアドレスの前に追加します。

コードブロック
module "consul" {
  source = "app.terraform.io/example-corp/k8s-cluster/azurerm"
  version = "1.1.0"
}

レジストリモジュールはバージョン管理をサポートしています。上記の例に示すように特定のバージョンを指定することも、柔軟なバージョン制約を使用することもできます。

モジュールレジストリドキュメントでレジストリについて詳しく学ぶことができます。

プライベートレジストリからモジュールにアクセスするには、CLI設定でアクセストークンを設定する必要がある場合があります。モジュールソース文字列で使用されているものと同じホスト名を使用します。TACOS（TF Automation and Collaboration Software）内のプライベートレジストリの場合は、APIまたはコマンドラインクライアントで使用したものと同じ認証トークンを使用します。

GitHub​

OpenTofuは、プレフィックスのないgithub.com URLを認識し、自動的にGitリポジトリソースとして解釈します。

コードブロック
module "consul" {
  source = "github.com/hashicorp/example"
}

上記のアドレススキームはHTTPS経由でクローンされます。SSH経由でクローンするには、次の形式を使用します。

コードブロック
module "consul" {
  source = "[email protected]:hashicorp/example.git"
}

これらのGitHubスキームは、一般的なGitリポジトリアドレススキームの便利なエイリアスとして扱われるため、同じ方法で資格情報を取得し、特定のリビジョンを選択するためのref引数をサポートします。プライベートリポジトリにアクセスするには、特に資格情報を設定する必要があります。

Bitbucket​

OpenTofuは、プレフィックスのないbitbucket.org URLを認識し、自動的にBitBucketリポジトリとして解釈します。

コードブロック
module "consul" {
  source = "bitbucket.org/example-corp/tofu-consul-aws"
}

この省略形は、OpenTofuが指定されたリポジトリがGitかMercurialを使用するかどうかを調べるためにBitBucket APIにアクセスする必要があるため、公開リポジトリでのみ機能します。

OpenTofuは、リポジトリの種類に応じて、その結果をGitソースまたはMercurialソースとして扱います。プライベートリポジトリの資格情報を設定する方法と、インストールする特定のリビジョンを指定する方法については、各バージョン管理タイプのセクションを参照してください。

汎用Gitリポジトリ​

特別なgit::プレフィックスをアドレスの前に付けることで、任意のGitリポジトリを使用できます。このプレフィックスの後には、有効なGit URLを指定して、Gitでサポートされているプロトコルのいずれかを選択できます。

例えば、HTTPSまたはSSHを使用する場合

コードブロック
module "vpc" {
  source = "git::https://example.com/vpc.git"
}

module "storage" {
  source = "git::ssh://[email protected]/storage.git"
}

OpenTofuは、git cloneを実行することでGitリポジトリからモジュールをインストールするため、資格情報を含むシステムに設定されているローカルのGit設定を尊重します。非公開のGitリポジトリにアクセスするには、そのリポジトリに適した資格情報をGitに設定してください。

SSHプロトコルを使用する場合は、設定済みのSSHキーが自動的に使用されます。これは、インタラクティブなプロンプトなしにプライベートリポジトリへのアクセスを許可するため、自動化されたシステムから非公開のGitリポジトリにアクセスする最も一般的な方法です。

HTTP/HTTPSプロトコル、またはユーザー名/パスワード資格情報を使用するその他のプロトコルを使用する場合は、Git資格情報ストレージ を設定して、環境に適した資格情報のソースを選択してください。

リビジョンの選択​

デフォルトでは、OpenTofuは選択されたリポジトリのデフォルトブランチ（HEADによって参照される）をクローンして使用します。これは、ref引数を使用してオーバーライドできます。ref引数の値は、ブランチ、SHA-1ハッシュ（短縮版または完全版）、タグ名など、git checkoutコマンドで受け入れられる任意の参照にすることができます。可能な値の完全なリストについては、Gitツール - リビジョンの選択（Gitブック内）を参照してください。

コードブロック
# select a specific tag
module "vpc" {
  source = "git::https://example.com/vpc.git?ref=v1.2.0"
}

# directly select a commit using its SHA-1 hash
module "storage" {
  source = "git::https://example.com/storage.git?ref=51d462976d84fdea54b47d80dcabbf680badcdb8"
}

浅いクローン​

大規模なリポジトリでは、リモートリポジトリの取得にかかる時間を短縮するために、浅いクローンを作成することをお勧めします。

depth URL引数は、git cloneへの--depth引数に対応しており、Gitに履歴を指定されたコミット数だけ切り詰めた浅いクローンを作成するように指示します。

ただし、浅いクローンは異なるGitプロトコル動作を必要とするため、depth引数を設定すると、OpenTofuは（もしあれば）ref引数をgit cloneへの--branch引数に渡します。つまり、リモートリポジトリに既知の名前付きブランチまたはタグを指定する必要があり、生のコミットIDは受け入れられません。

OpenTofuは、指定されたモジュールのソースコードを見つけるために最新の選択されたコミットのみを使用するため、depthを1以外の値に設定することは通常は役に立ちません。

"scpライク"なアドレス構文​

SSH経由でGitを使用する場合は、他のすべてのURLのようなGitアドレス形式との整合性のために、ssh://プレフィックス付きのURL形式を使用することをお勧めします。代わりに、代替の「scpライク」構文を使用することもできますが、その場合はssh://スキーム部分を省略し、git::部分のみを含める必要があります。例：

コードブロック
module "storage" {
  source = "git::[email protected]:storage.git"
}

ssh:// URLスキームを使用する場合は、OpenTofuはコロンがパスの開始ではなくポート番号の開始を示すと仮定します。これは、OpenTofu固有のgit::セレクタープレフィックスを除いて、Git自体がこれらの異なる形式を解釈する方法と一致します。

汎用Mercurialリポジトリ​

特別なhg::プレフィックスをアドレスの前に付けることで、任意のMercurialリポジトリを使用できます。このプレフィックスの後には、Mercurialによってサポートされているプロトコルのいずれかを選択するために、有効なMercurial URLを指定できます。

コードブロック
module "vpc" {
  source = "hg::http://example.com/vpc.hg"
}

OpenTofuは、hg cloneを実行することでMercurialリポジトリからモジュールをインストールするため、資格情報を含むシステムに設定されているローカルのMercurial設定を尊重します。非公開のリポジトリにアクセスするには、そのリポジトリに適した資格情報をMercurialに設定してください。

SSHプロトコルを使用する場合は、設定済みのSSHキーが自動的に使用されます。これは、インタラクティブなプロンプトなしにプライベートリポジトリへのアクセスを許可するため、自動化されたシステムから非公開のMercurialリポジトリにアクセスする最も一般的な方法です。

リビジョンの選択​

オプションのref引数を使用して、デフォルト以外のブランチまたはタグを選択できます。

コードブロック
module "vpc" {
  source = "hg::http://example.com/vpc.hg?ref=v1.2.0"
}

HTTP URL​

HTTPまたはHTTPS URLを使用する場合、OpenTofuは指定されたURLにGETリクエストを送信します。これにより、別のソースアドレスが返される可能性があります。この間接的な方法により、より複雑なモジュールソースアドレスに対する一種の「バニティリダイレクト」としてHTTP URLを使用できます。

OpenTofuは、GETリクエストを送信する前に、指定されたURLに追加のクエリ文字列引数tofu-get=1を追加します。これにより、サーバーはOpenTofuがリクエストしている場合に、オプションで異なる結果を返すことができます。

応答が成功した場合（200範囲のステータスコード）、OpenTofuは次の場所を順番に調べて、アクセスする次のアドレスを探します。

  • X-Terraform-Getという名前の応答ヘッダーフィールドの値。

  • 応答がHTMLページの場合、名前がtofu-getのmeta要素。

    コードブロック
    <meta name="tofu-get" content="github.com/hashicorp/example" />

いずれの場合も、結果は、このページの他の場所で説明されている形式のいずれかを使用して、別のモジュールソースアドレスとして解釈されます。

HTTP/HTTPS URLで認証資格情報が必要な場合は、.netrcファイルを使用して資格情報を設定します。デフォルトでは、OpenTofuはHOMEディレクトリ内の.netrcファイルを探します。ただし、NETRC環境変数を設定することで、デフォルトのファイルシステムの場所をオーバーライドできます。.netrc形式の詳細については、curlでの使用方法に関するドキュメントを参照してください。

HTTP経由でのアーカイブの取得​

特別なケースとして、OpenTofuがURLにアーカイブファイル形式に関連付けられた一般的なファイル拡張子が付いていることを検出した場合、上記で説明した特別なtofu-get=1リダイレクトをバイパスし、代わりに参照されたアーカイブの内容をモジュールソースコードとして使用します。

コードブロック
module "vpc" {
  source = "https://example.com/vpc-module.zip"
}

OpenTofuがこの特別な動作を認識する拡張子は次のとおりです。

  • zip
  • tar.bz2およびtbz2
  • tar.gzおよびtgz
  • tar.xzおよびtxz

URLにこれらの拡張子のいずれも付いていないが、アーカイブを参照している場合は、archive引数を使用してこの解釈を強制します。

コードブロック
module "vpc" {
  source = "https://example.com/vpc-module?archive=zip"
}

S3バケット​

特別なs3::プレフィックスと、S3バケットオブジェクトURLを使用して、S3に保存されているアーカイブをモジュールソースとして使用できます。

コードブロック
module "consul" {
  source = "s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/vpc.zip"
}

s3::プレフィックスにより、OpenTofuは指定されたURLにアクセスする際にAWSスタイルの認証を使用します。その結果、このスキームは、AWSと同じ方法で認証を処理する限り、S3 APIを模倣する他のサービスでも機能する可能性があります。

結果のオブジェクトは、標準HTTP経由のアーカイブと同じファイル拡張子のいずれかのアーカイブである必要があります。OpenTofuはアーカイブを展開してモジュールソースツリーを取得します。

モジュールインストーラーは、次の場所にあるAWS資格情報を検索し、複数の資格情報がある場合はリストの先頭のものを優先します。

  • AWS_ACCESS_KEY_IDおよびAWS_SECRET_ACCESS_KEY環境変数。
  • ホームディレクトリの.aws/credentialsファイル内のデフォルトプロファイル。
  • EC2インスタンスで実行している場合、インスタンスのIAMインスタンスプロファイルに関連付けられた一時的な資格情報。

GCSバケット​

特別なgcs::プレフィックスとGCSバケットオブジェクトURLを使用して、Google Cloud Storageに保存されているアーカイブをモジュールソースとして使用できます。

例：

  • gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE
  • gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip
コードブロック
module "consul" {
  source = "gcs::https://www.googleapis.com/storage/v1/modules/foomodule.zip"
}

モジュールインストーラーは、Google Cloud SDKを使用してGCSとの認証を行います。Google Cloud Platformの資格情報を設定するには、次のいずれかの方法を使用できます。

  • GOOGLE_OAUTH_ACCESS_TOKEN環境変数を、生のGoogle Cloud Platform OAuthアクセストークンに設定します。
  • サービスアカウントキーファイルのパスをGOOGLE_APPLICATION_CREDENTIALS環境変数に入力します。
  • GCEインスタンスからOpenTofuを実行している場合、デフォルトの資格情報が自動的に利用可能です。詳細については、「インスタンスのサービスアカウントの作成と有効化」を参照してください。インスタンスのサービスアカウントの作成と有効化
  • コンピューターでは、gcloud auth application-default loginを実行することで、Googleアイデンティティを利用可能にできます。

パッケージのサブディレクトリ内のモジュール​

モジュールのソースがバージョン管理リポジトリまたはアーカイブファイル（一般的に「パッケージ」）の場合、モジュール自体はパッケージのルートを基準としたサブディレクトリ内にある可能性があります。

特別なダブルスラッシュ構文はOpenTofuによって解釈され、その後のパスがパッケージ内のサブディレクトリであることを示します。例：

  • hashicorp/consul/aws//modules/consul-cluster
  • git::https://example.com/network.git//modules/vpc
  • https://example.com/network-module.zip//modules/vpc
  • s3::https://s3-eu-west-1.amazonaws.com/examplecorp-tofu-modules/network.zip//modules/vpc

ソースアドレスに引数がある場合（バージョン管理ソースでサポートされているref引数など）、サブディレクトリ部分はこれらの引数の前に置く必要があります。

  • git::https://example.com/network.git//modules/vpc?ref=v1.2.0
  • github.com/hashicorp/example//modules/vpc?ref=v1.2.0

OpenTofuはパッケージ全体をローカルディスクに展開しますが、サブディレクトリからモジュールを読み取ります。その結果、パッケージのサブディレクトリにあるモジュールが、同じパッケージ内にある別のモジュールにローカルパスを使用しても安全です。

変数とローカルの評価のサポート​

プロジェクトの複雑さと要件が増加するにつれて、モジュールのソースとバージョンフィールドでローカルと変数を使用することを検討することが賢明です。

多くの組織は、モジュールにモノレポパターンを使用しています。

コードブロック
locals {
	modules_repo = "github.com/myorg/tofu-modules/"
	modules_version = "?ref=v1.20.4"
}

module "storage" {
  source = "${local.modules_repo}/storage${local.modules_version}"
}

module "compute" {
  source = "${local.modules_repo}/compute${local.modules_version}"
}

パッチリリースのバージョンを更新したり、リポジトリのフォークに切り替えたりするのは非常に簡単です。