Метааргумент модуля providers

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

# 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
  }
}

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

Поведение по умолчанию: наследование провайдеров по умолчанию​

Если дочерний модуль не объявляет никаких псевдонимов конфигураций, аргумент providers является необязательным. Если его не указывать, дочерний модуль наследует все конфигурации провайдеров по умолчанию родительского модуля. (Конфигурации провайдеров по умолчанию — это конфигурации, в которых не используется аргумент alias.)

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

Использование и поведение​

Аргумент providers использует синтаксис, похожий на запись карты, с фигурными скобками в качестве разделителей ({, }). В указанном сопоставлении:

• Ключи — это адреса конфигураций провайдеров, которые будут использоваться внутри дочернего модуля.
• Значения — это адреса экземпляров провайдеров из родительского модуля.

В обеих частях используется синтаксис ссылок на экземпляры провайдеров, который для альтернативных конфигураций провайдеров имеет вид <PROVIDER NAME>.<ALIAS>.

В дочернем модуле ресурсы назначаются конфигурациям провайдеров обычным образом: либо OpenTofu выбирает конфигурацию по умолчанию на основе имени типа ресурса, либо ресурс указывает альтернативную конфигурацию с помощью аргумента provider. Если при вызове модуль получает карту providers, имена конфигураций провайдеров, используемые внутри модуля, фактически переназначаются на указанные конфигурации из родительского модуля.

Когда указывать провайдеры​

Есть две основные причины использовать аргумент providers:

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

Изменение конфигураций провайдеров по умолчанию​

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

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

Аргумент 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
  }
}

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

Экземпляры модуля с разными экземплярами провайдера​

Если написать блок provider с использованием метааргумента for_each, конфигурация провайдера динамически объявляет ноль или более экземпляров провайдера.

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

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

variable "aws_regions" {
  type = map(object({
    vpc_cidr_block = string
  }))
}

provider "aws" {
  alias    = "by_region"
  for_each = var.aws_regions

  region = each.key
}

module "per_region" {
  source = "./per-region"
  # This expression filters var.aws_regions to include only
  # the elements whose value is not null. Refer to the
  # warning in the text below for more information.
  for_each = {
    for region, config in var.aws_regions : region => config
    if config != null
  }
  providers = {
    aws = aws.by_region[each.key]
  }

  region_name    = each.key
  vpc_cidr_block = each.value.vpc_cidr_block
}

Модуль в ./per-region следует написать так, чтобы все его ресурсы AWS были привязаны к конфигурации провайдера AWS по умолчанию для этого модуля. Аргумент providers в блоке module гарантирует, что конфигурация провайдера AWS по умолчанию для каждого экземпляра модуля будет привязана к отдельному экземпляру aws.by_region.

Все экземпляры модуля должны ссылаться на экземпляры одной и той же конфигурации провайдера: между экземплярами модуля может различаться только выражение в скобках (each.key в примере выше).

Дополнительная информация для разработчиков модулей​

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