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

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

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