メインコンテンツにスキップ

プロバイダー要件

OpenTofuは、「プロバイダー」と呼ばれるプラグインを使用してリモートシステムと対話します。 OpenTofuの設定では、必要なプロバイダーを宣言する必要があります。そうすることで、OpenTofuはそれらをインストールして使用できます。このページでは、OpenTofuがインストールできるようにプロバイダーを宣言する方法について説明します。

さらに、一部のプロバイダーは、使用前に設定（エンドポイントURLやクラウドリージョンなど）が必要です。プロバイダー設定ページでは、プロバイダーの設定方法について説明します。

プロバイダーの要求​

各モジュールは、必要なプロバイダーを宣言する必要があります。そうすることで、OpenTofuはそれらをインストールして使用できます。プロバイダーの要件は、required_providersブロックで宣言されます。

プロバイダー要件は、ローカル名、ソースの場所、およびバージョン制約で構成されます。

コードブロック
terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}

required_providersブロックは、トップレベルのterraformブロック（他の設定も含むことができます）内にネストする必要があります。

required_providersブロックの各引数は、1つのプロバイダーを有効にします。キーはプロバイダーのローカル名（このモジュール内での一意の識別子）を決定し、値は次の要素を持つオブジェクトです。

  • source - 使用するプロバイダーのグローバルソースアドレス（例：hashicorp/aws）。

  • version - モジュールが互換性のある使用可能なプロバイダーバージョンのサブセットを指定するバージョン制約。

名前とアドレス​

各プロバイダーには2つの識別子があります。

  • プロバイダーを要求する場合にのみ使用される一意の*ソースアドレス*。
  • モジュール内の他の場所で使用される*ローカル名*。

ローカル名​

ローカル名はモジュール固有であり、プロバイダーを要求するときに割り当てられます。ローカル名はモジュールごとに一意である必要があります。

required_providersブロックの外側では、OpenTofuの設定は常にローカル名でプロバイダーを参照します。たとえば、次の設定では、mycorp/mycloudのローカル名としてmycloudを宣言し、プロバイダーを設定するときにそのローカル名を使用します。

コードブロック
terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}

provider "mycloud" {
  # ...
}

プロバイダーのユーザーは、任意のローカル名を選択できます。ただし、ほぼすべてのプロバイダーには、すべてのリソースタイプのプレフィックスとして使用する*優先ローカル名*があります。（たとえば、hashicorp/awsのリソースはすべて、aws_instanceやaws_security_groupのようにawsで始まります。）

可能な限り、プロバイダーの優先ローカル名を使用する必要があります。これにより、設定が理解しやすくなり、ほとんどのリソースからproviderメタ引数を省略できます。（リソースが使用するプロバイダー設定を指定していない場合、OpenTofuはリソースタイプの最初の単語をローカルプロバイダー名として解釈します。）

ソースアドレス​

プロバイダーのソースアドレスは、そのグローバル識別子です。また、OpenTofuがダウンロードできる主要な場所も指定します。

ソースアドレスは、スラッシュ（/）で区切られた次の3つの部分で構成されます。

[<ホスト名>/]<名前空間>/<タイプ>

  • **ホスト名**（オプション）：プロバイダーを配布するレジストリのホスト名。省略した場合、デフォルトはregistry.opentofu.orgです。

  • **名前空間**：指定されたレジストリ内の組織の名前空間。ほとんどの場合、これはプロバイダーを公開する組織を表します。このフィールドは、他のレジストリホストでは別の意味を持つ場合があります。

  • **タイプ**：プロバイダーが管理するプラットフォームまたはシステムの短い名前。特定のレジストリホストの特定の名前空間内で一意である必要があります。

    タイプは通常、プロバイダーの優先ローカル名です。（例外があります。たとえば、hashicorp/google-betaはhashicorp/googleの代替リリースチャネルであるため、優先ローカル名はgoogleです。疑問がある場合は、プロバイダーのドキュメントを確認してください。）

たとえば、公式HTTPプロバイダーは、registry.opentofu.orgのhashicorp名前空間に属しているため、ソースアドレスはregistry.opentofu.org/hashicorp/http、またはより一般的にはhashicorp/httpです。

3つのコンポーネントすべてが明示的に指定されたソースアドレスは、プロバイダーの*完全修飾アドレス*と呼ばれます。完全修飾アドレスは、エラーメッセージなどのさまざまな出力に表示されますが、ほとんどの場合、簡略化された表示バージョンが使用されます。この表示バージョンは、ソースホストがパブリックレジストリの場合に省略されるため、"registry.opentofu.org/hashicorp/random"の代わりに短縮バージョン"hashicorp/random"が表示される場合があります。

ローカル名の競合の処理​

可能な限り、プロバイダーの優先ローカル名（通常はソースアドレスの「タイプ」部分と同じ）を使用することをお勧めします。

ただし、同じモジュールで同じ優先ローカル名を持つ2つのプロバイダーを使用する必要がある場合があります。これは通常、プロバイダーに汎用インフラストラクチャタイプの名前が付けられている場合です。 OpenTofuでは、モジュール内の各プロバイダーに一意のローカル名が必要なため、少なくとも一方に優先ではない名前を使用する必要があります。

この場合、各プロバイダーの名前空間とタイプ名を組み合わせて、ダッシュで複合ローカル名を作成することをお勧めします。

コードブロック
terraform {
  required_providers {
    # In the rare situation of using two providers that
    # have the same type name -- "http" in this example --
    # use a compound local name to distinguish them.
    hashicorp-http = {
      source  = "hashicorp/http"
      version = "~> 2.0"
    }
    mycorp-http = {
      source  = "mycorp/http"
      version = "~> 1.0"
    }
  }
}

# References to these providers elsewhere in the
# module will use these compound local names.
provider "mycorp-http" {
  # ...
}

data "http" "example" {
  provider = hashicorp-http
  #...
}

OpenTofu はリソースタイプからプロバイダー名を推測できないため、影響を受けるすべてのリソースに provider メタ引数を指定する必要があります。ただし、モジュールの読者と保守担当者は何が起こっているかを簡単に理解できるため、混乱を避けることはタイピングを避けることよりもはるかに重要です。

バージョン制約​

各プロバイダープラグインには、独自の利用可能なバージョンセットがあり、プロバイダーの機能が時間とともに進化することを可能にします。宣言する各プロバイダーの依存関係には、version 引数にバージョン制約を指定する必要があります。これにより、OpenTofu は、すべてのモジュールと互換性のあるプロバイダーごとに単一のバージョンを選択できます。

version 引数はオプションです。省略した場合、OpenTofu はプロバイダーの任意のバージョンを互換性があると見なします。ただし、モジュールが依存するすべてのプロバイダーにバージョン制約を指定することを強くお勧めします。

OpenTofu が特定の構成に対して常に同じプロバイダーバージョンをインストールするようにするには、OpenTofu CLI を使用して依存関係ロックファイルを作成し、構成とともにバージョン管理にコミットします。ロックファイルが存在する場合、OpenTofu CLI と TACOS（TF Automation and Collaboration Software）はすべて、プロバイダーのインストール時にそれを遵守します。

プロバイダーバージョンのベストプラクティス​

各モジュールは、少なくとも動作することがわかっている最小プロバイダーバージョンを、>= バージョン制約構文を使用して宣言する必要があります。

コードブロック
terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = ">= 1.0"
    }
  }
}

構成のルートとして使用することを意図したモジュール、つまり tofu apply を実行するディレクトリは、互換性のない新しいバージョンへの偶発的なアップグレードを避けるために、動作することを意図した*最大*プロバイダーバージョンも指定する必要があります。 ~> 演算子は、バージョンの最右端のコンポーネントの増分を許可するための便利な省略形です。次の例では、演算子を使用して、特定のマイナーリリース内でパッチリリースのみを許可しています。

コードブロック
terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = "~> 1.0.4"
    }
  }
}

モジュールが特定の新しいバージョンと互換性がないことがわかっている場合でも、多くの構成で再利用することを意図したモジュールには、~>（またはその他の最大バージョン制約）を使用しないでください。これを行うと、エラーを防ぐことができる場合もありますが、多くの場合、モジュールのユーザーは、ルーチンのアップグレードを実行するときに、多くのモジュールを同時に更新する必要があります。最小バージョンを指定し、既知の非互換性を文書化し、ルートモジュールに最大バージョンを管理させます。

組み込みプロバイダー​

ほとんどのプロバイダーはプラグインとして個別に配布されますが、OpenTofu自体に組み込まれているプロバイダーが1つあります。このプロバイダーは、terraform_remote_state データソースを有効にします。

このプロバイダーは OpenTofu に組み込まれているため、その機能を使用するために required_providers ブロックで宣言する必要はありません。ただし、一貫性のために、特別なプロバイダーソースアドレス terraform.io/builtin/terraform があります。このアドレスは、タイプ名が「tofu」である仮説的なサードパーティプロバイダーではなく、組み込みプロバイダーを明確に参照するために、OpenTofu のエラーメッセージやその他の出力に表示される場合があります。

ソースアドレスが hashicorp/terraform である既存のプロバイダーもあります。これは、現在組み込みのプロバイダーの古いバージョンです。 hashicorp/terraform は OpenTofu と互換性がなく、required_providers ブロックで宣言しないでください。

社内プロバイダー​

誰でも独自のプロバイダーを開発および配布できます。

一部の組織は、独自のプロバイダーを開発して独自のシステムを構成し、レジストリに公開せずに OpenTofu からこれらのプロバイダーを使用したいと考えています。

このようなプロバイダーを配布する1つのオプションは、プロバイダーレジストリプロトコルを実装することによって、社内*プライベート*レジストリを実行することです。

単一のプロバイダーを社内で配布するためだけに追加のサービスを実行することは望ましくない場合があるため、OpenTofu は、*ファイルシステムミラー*を介して、プロバイダープラグインをローカルファイルシステムの特定のディレクトリに直接配置するなど、他のプロバイダーインストール方法もサポートしています。

すべてのプロバイダーには、レジストリのホスト名を含む（または暗示する）ソースアドレスが必要です。ただし、そのホスト名は実際のレジストリサービスを提供する必要はありません。ローカルファイルシステムディレクトリから配布することを意図した社内プロバイダーの場合、組織が管理するドメインで任意のホスト名を使用できます。

たとえば、企業ドメインが example.com の場合、ホスト名が DNS で実際に解決されない場合でも、プレースホルダーホスト名として tofu.example.com を使用することを選択できます。次に、そのホスト名の下で社内プロバイダーを表すために必要な名前空間とタイプを選択し、tofu.example.com/examplecorp/ourcloud のようなソースアドレスを指定できます。

コードブロック
terraform {
  required_providers {
    mycloud = {
      source  = "tofu.example.com/examplecorp/ourcloud"
      version = ">= 1.0"
    }
  }
}

このプロバイダーのバージョン 1.0.0 をローカルファイルシステムからインストールできるようにするには、暗黙のローカルミラーディレクトリのいずれかを選択し、その下に次のようなディレクトリ構造を作成します。

コードブロック
tofu.example.com/examplecorp/ourcloud/1.0.0

その 1.0.0 ディレクトリの下に、AMD64 / x64 プロセッサを搭載した Linux 用の linux_amd64 など、OpenTofu を実行しているプラットフォームを表す追加のディレクトリを1つ作成し、プロバイダープラグイン実行可能ファイルとその他の必要なファイルをそのディレクトリに配置します。

したがって、Windows システムでは、プロバイダープラグイン実行可能ファイルは次のパスにある可能性があります。

コードブロック
tofu.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/tofu-provider-ourcloud.exe

後で、バイナリを帯域外で配布するのではなく、実際のプライベートプロバイダーレジストリの使用に切り替えることにした場合、レジストリサーバーを tofu.example.com にデプロイし、同じ名前空間とタイプ名を保持できます。その場合、既存のモジュールは、レジストリサーバーを使用して同じプロバイダーを見つけるために変更を必要としません。