Провайдеры в модулях

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

Каждый ресурс в конфигурации должен быть связан с одной конфигурацией провайдера. В отличие от большинства других понятий 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, чтобы выбрать одну из двух конфигураций провайдера.