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

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

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