Метааргумент 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 в примере выше).

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

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