Конфигурация провайдера

Провайдеры позволяют 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, версия которого контролируется системой контроля версий.

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

• 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 ключ элемента или имя атрибута становится ключом экземпляра. Для множества строк ключом экземпляра становится значение самого элемента.

Пользователь этой конфигурации должен предоставить значение типа map для входной переменной aws_regions, где ключ каждого элемента является допустимым именем региона 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.