Настройка провайдеров

Провайдеры позволяют OpenTofu взаимодействовать с облачными провайдерами, SaaS-провайдерами и другими API.

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

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

Настройка провайдеров​

Конфигурации провайдеров должны находиться в корневом модуле конфигурации OpenTofu. (Дочерние модули получают конфигурации провайдеров из корневого модуля; дополнительную информацию см. в разделах Метааргумент providers и Разработка модулей: провайдеры внутри модулей.)

Конфигурация провайдера задаётся с помощью блока provider:

provider "google" {
  project = "acme-app"
  region  = "us-central1"
}

Имя, указанное в заголовке блока (в этом примере — "google"), является локальным именем настраиваемого провайдера. У каждого модуля есть собственное пространство имён локальных имён провайдеров, определённых в его блоке required_providers.

Тело блока (между { и }) содержит аргументы конфигурации провайдера. Большинство аргументов в этом разделе определяются самим провайдером; в данном примере и project, и region относятся к провайдеру google.

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

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

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

Кроме того, для всех блоков provider доступны два «метааргумента», определённые самим OpenTofu:

• alias — для определения дополнительных конфигураций одного и того же провайдера
• for_each — для определения нескольких динамических экземпляров конфигурации провайдера
• version, который мы больше не рекомендуем использовать (вместо него используйте требования к провайдерам)

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

alias: Несколько конфигураций провайдера​

При необходимости можно определить несколько конфигураций одного и того же провайдера и выбирать, какую из них использовать для каждого ресурса или модуля. Главная причина для этого — поддержка нескольких регионов облачной платформы; среди других примеров — работа с несколькими хостами Docker, несколькими хостами Consul и т. д.

Чтобы создать несколько конфигураций для заданного провайдера, включите несколько блоков provider с одним и тем же именем провайдера. Для каждой дополнительной конфигурации, отличной от конфигурации по умолчанию, используйте метааргумент alias, чтобы добавить дополнительный сегмент имени. Конфигурация провайдера с псевдонимом называется альтернативной конфигурацией провайдера. Например:

# The default provider configuration; resources that begin with `aws_` will use
# it as the default, and it can be referenced as `aws`.
provider "aws" {
  region = "us-east-1"
}

# Alternate provider configuration for west coast region; resources can
# reference this as `aws.west`.
provider "aws" {
  alias  = "west"
  region = "us-west-2"
}

Чтобы объявить псевдоним конфигурации внутри модуля и получить альтернативную конфигурацию провайдера от родительского модуля, добавьте аргумент configuration_aliases в запись required_providers этого провайдера. В следующем примере в содержащем модуле объявлены имена конфигураций провайдера mycloud и mycloud.alternate:

terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
      configuration_aliases = [ mycloud.alternate ]
    }
  }
}

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

Блок provider без аргумента alias является конфигурацией провайдера по умолчанию. Ресурсы, в которых не задан метааргумент provider, используют конфигурацию провайдера по умолчанию, соответствующую первому слову в имени типа ресурса. (Например, ресурс aws_instance использует конфигурацию провайдера aws по умолчанию, если не указано иное.)

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

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

for_each: Несколько экземпляров конфигурации провайдера​

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

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

Любая альтернативная конфигурация провайдера (объявленная с помощью аргумента alias) может также содержать аргумент for_each, который указывает, что конфигурацию следует создать в нескольких экземплярах на основе значения-коллекции:

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

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

  region = each.key
}

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

У каждого экземпляра есть ключ экземпляра, однозначно определяющий его среди всех экземпляров, принадлежащих одной конфигурации провайдера. Значение, присвоенное for_each, должно иметь тип map или object либо быть множеством строк. Для типа map или object ключ элемента или имя атрибута становится ключом экземпляра. Для множества строк ключом экземпляра становится само значение элемента.

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

aws_regions = {
  eu-central-2 = {
    vpc_cidr_block = "10.1.0.0/16"
  }
  ap-northeast-1 = {
    vpc_cidr_block = "10.2.0.0/16"
  }
}

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

Выбор альтернативных конфигураций провайдера​

Каждый ресурс в конфигурации OpenTofu должен быть привязан к одной конфигурации провайдера.

По умолчанию каждый ресурс привязывается к конфигурации провайдера по умолчанию, выбираемой автоматически на основе первого сегмента имени типа ресурса. Например, блок resource "azurerm_subnet" "example" будет привязан к конфигурации по умолчанию того провайдера, локальное имя которого в модуле, где объявлен ресурс, — «azurerm».

Чтобы использовать альтернативную конфигурацию провайдера, блок resource или data должен включать метааргумент provider со ссылкой на экземпляр провайдера, содержащей псевдоним выбранной конфигурации:

resource "aws_instance" "foo" {
  provider = aws.west

  # ...
}

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

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

resource "aws_instance" "foo" {
  provider = aws

  # ...
}

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

Для явных ссылок на конфигурации провайдера OpenTofu использует специальный синтаксис ссылок на конфигурации провайдеров вида <PROVIDER NAME>.<ALIAS>. Например, aws.west ссылается на блок provider "aws" с alias = "west".

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

• Метааргумент provider блока resource или data
• Метааргумент providers блока module

Для конфигурации провайдера без for_each тот же синтаксис, который используется для ссылки на конфигурацию, также ссылается на её единственный экземпляр провайдера. Поэтому в большинстве случаев ссылку на конфигурацию провайдера и ссылку на экземпляр провайдера можно считать эквивалентными.

Однако если конфигурация провайдера объявляет ноль или более динамических экземпляров с помощью for_each, синтаксис ссылки расширяется дополнительным компонентом, который указывает, какой экземпляр выбрать, используя ключи экземпляров конфигурации. Например, aws.by_region["eu-west-1"] ссылается на экземпляр aws.by_region с ключом экземпляра "eu-west-1".

В выражении в квадратных скобках используется обычный синтаксис выражений; обычно ключ экземпляра выбирается динамически для каждого экземпляра ресурса, а не задаётся явно. Например:

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

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

  region = each.key
}

resource "aws_vpc" "private" {
  # 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
  }
  provider = aws.by_region[each.key]

  cidr_block = each.value.vpc_cidr_block
}

Блок resource "aws_vpc" "private" использует for_each, чтобы объявить по одному экземпляру ресурса для каждого ненулевого элемента var.aws_regions. Затем аргумент provider использует each.key для выбора отдельного экземпляра aws.by_region для каждого экземпляра ресурса, чтобы каждый из них создавался в отдельном регионе.

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

Хотя выражение ключа экземпляра в квадратных скобках является динамическим, ссылка на конфигурацию провайдера остаётся статической, чтобы OpenTofu мог определить зависимости между блоками resource и provider до вычисления выражений. Эти зависимости позволяют OpenTofu разрешать динамические выражения в правильном порядке. Это означает, что все экземпляры определённого ресурса должны быть привязаны к экземплярам одного и того же блока конфигурации провайдера, но каждый из них может быть привязан к отдельному экземпляру.

Передача конфигураций провайдера между модулями​

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

Дополнительную информацию см. в разделе Метааргумент providers в блоках module.

version (Устарел)​

Метааргумент version задаёт ограничение версии провайдера и работает так же, как аргумент version в блоке required_providers. Ограничение версии в конфигурации провайдера используется только в том случае, если для этого провайдера оно не указано в required_providers.

Всегда объявляйте ограничения версий провайдеров в блоке required_providers.