Провайдеры внутри модулей

В конфигурации с несколькими модулями следует учитывать некоторые особенности сопоставления ресурсов с конфигурациями провайдеров.

Каждый ресурс в конфигурации должен быть связан с одной конфигурацией провайдера. В отличие от большинства других понятий OpenTofu, конфигурации провайдеров являются глобальными для всей конфигурации OpenTofu и могут использоваться совместно разными модулями. Определять конфигурации провайдеров можно только в корневом модуле.

Провайдеры можно передавать дочерним модулям двумя способами: либо неявно посредством наследования, либо явно с помощью аргумента providers внутри блока module. Эти варианты подробнее рассматриваются в следующих разделах.

Модуль, предназначенный для вызова одним или несколькими другими модулями, не должен содержать блоки provider. Модуль с собственными конфигурациями провайдеров несовместим с метааргументами for_each, count и depends_on.

Конфигурации провайдеров используются для всех операций с соответствующими ресурсами, включая удаление удалённых объектов и обновление состояния. OpenTofu сохраняет в состоянии ссылку на конфигурацию провайдера, которая последней применяла изменения к каждому ресурсу. Когда блок resource удаляется из конфигурации или динамический экземпляр ресурса удаляется путём изменения значения, заданного метааргументу count или for_each, для поиска подходящей конфигурации используется эта запись в состоянии, поскольку аргумент provider экземпляра ресурса (если он есть) больше не будет присутствовать в конфигурации.

Поэтому перед удалением экземпляра провайдера из конфигурации необходимо убедиться, что все ресурсы, относящиеся к этому экземпляру, уничтожены. Если OpenTofu обнаружит в состоянии отслеживаемый экземпляр ресурса, для которого экземпляр провайдера больше не объявлен в конфигурации, во время планирования будет выдана ошибка с предложением повторно добавить экземпляр провайдера.

Ограничения версий провайдеров в модулях​

Хотя конфигурации провайдеров используются совместно модулями, каждый модуль должен объявлять собственные требования к провайдерам, чтобы OpenTofu мог гарантировать наличие единственной версии провайдера, совместимой со всеми модулями конфигурации, а также указать адрес источника, который служит глобальным идентификатором провайдера, не зависящим от модуля.

Чтобы объявить, что модулю нужны определённые версии конкретного провайдера, используйте блок required_providers внутри блока terraform:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 2.7.0"
    }
  }
}

Например, требование к провайдеру означает: «Этому модулю нужна версия v2.7.0 провайдера hashicorp/aws, и он будет ссылаться на него как на aws». Однако оно не указывает параметры конфигурации, определяющие, к каким удалённым конечным точкам будет обращаться провайдер, например регион AWS. Параметры конфигурации задаются в конфигурациях провайдера, и одна конфигурация OpenTofu в целом может содержать несколько разных конфигураций одного провайдера.

Псевдонимы провайдеров внутри модулей​

Чтобы объявить в модуле несколько имён конфигурации для провайдера, добавьте аргумент configuration_aliases:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 2.7.0"
      configuration_aliases = [ aws.alternate ]
    }
  }
}

Приведённые выше требования совпадают с предыдущими, но дополнены псевдонимом конфигурации провайдера aws.alternate, на который ресурсы могут ссылаться с помощью аргумента provider.

Если вы создаёте общий модуль, задавайте только минимально необходимую версию провайдера с помощью ограничения >=. Укажите минимальную версию, которая содержит функции, необходимые вашему модулю. Это позволит пользователю вашего модуля при необходимости выбрать более новую версию провайдера, если другие части его общей конфигурации используют дополнительные функции.

Сейчас нельзя передать дочернему модулю целиком конфигурацию провайдера с несколькими экземплярами (объявленную с помощью for_each), однако родительский модуль может назначить отдельный динамический экземпляр конфигурации провайдера каждому экземпляру модуля.

Неявное наследование провайдеров​

Для удобства в простых конфигурациях дочерний модуль автоматически наследует от родительского конфигурации провайдеров по умолчанию. Это означает, что явные блоки provider нужны только в корневом модуле, а последующие модули могут просто объявлять ресурсы этого провайдера, которые автоматически связываются с конфигурациями провайдера корневого модуля.

Например, в корневом модуле может быть только блок provider и блок module для создания дочернего модуля:

provider "aws" {
  region = "us-west-1"
}

module "child" {
  source = "./child"
}

После этого дочерний модуль может использовать любой ресурс этого провайдера без дополнительной настройки конфигурации провайдера:

resource "aws_s3_bucket" "example" {
  bucket = "provider-inherit-example"
}

Мы рекомендуем этот подход, если для каждого провайдера достаточно одной конфигурации во всей конфигурации.

В более сложных ситуациях может быть несколько конфигураций провайдера, либо дочернему модулю могут понадобиться настройки провайдера, отличные от родительских. В таких случаях провайдеры необходимо передавать явно.

Явная передача провайдеров​

Если дочерним модулям нужны разные конфигурации определённого провайдера или дочернему модулю требуется конфигурация провайдера, отличная от конфигурации родительского модуля, можно использовать аргумент providers внутри блока module, чтобы явно указать, какие конфигурации провайдеров доступны дочернему модулю. Например:

# The default "aws" configuration is used for AWS resources in the root
# module where no explicit provider instance is selected.
provider "aws" {
  region = "us-west-1"
}

# An alternate configuration is also defined for a different
# region, using the alias "usw2".
provider "aws" {
  alias  = "usw2"
  region = "us-west-2"
}

# An example child module is instantiated with the alternate configuration,
# so any AWS resources it defines will use the us-west-2 region.
module "example" {
  source    = "./example"
  providers = {
    aws = aws.usw2
  }
}

Аргумент providers внутри блока module похож на аргумент provider внутри блока resource, но представляет собой сопоставление, а не одну строку, поскольку модуль может содержать ресурсы множества разных провайдеров.

Ключи карты providers — это имена конфигураций провайдеров, ожидаемые дочерним модулем, а значения — имена соответствующих конфигураций в текущем модуле.

При использовании аргумента providers в блоке module он переопределяет всё поведение наследования по умолчанию, поэтому необходимо перечислить сопоставления для всех требуемых провайдеров. Это позволяет избежать путаницы и неожиданностей, которые могут возникнуть при сочетании неявной и явной передачи провайдеров.

Дополнительные конфигурации провайдеров (с заданным аргументом alias) никогда не наследуются дочерними модулями автоматически, поэтому их всегда необходимо передавать явно с помощью карты providers. Например, модулю, который настраивает связь между сетями в двух регионах AWS, скорее всего, понадобятся исходный и целевой регионы. В этом случае корневой модуль может выглядеть так:

provider "aws" {
  alias  = "usw1"
  region = "us-west-1"
}

provider "aws" {
  alias  = "usw2"
  region = "us-west-2"
}

module "tunnel" {
  source    = "./tunnel"
  providers = {
    aws.src = aws.usw1
    aws.dst = aws.usw2
  }
}

Затем в подкаталоге ./tunnel необходимо объявить псевдонимы конфигураций провайдера, чтобы вызывающий модуль мог передавать конфигурации с такими именами в аргументе providers:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 2.7.0"
      configuration_aliases = [ aws.src, aws.dst ]
    }
  }
}

Затем для каждого ресурса следует задать атрибут provider со значением aws.src или aws.dst, чтобы выбрать одну из двух конфигураций провайдера.