Требования к провайдерам

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

Кроме того, некоторым провайдерам требуется конфигурация (например, URL конечных точек или облачные регионы), прежде чем их можно будет использовать. На странице Настройка провайдеров описано, как задавать параметры провайдеров.

Объявление требований к провайдерам​

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

Требование к провайдеру состоит из локального имени, адреса источника и ограничения версии:

terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}

Блок required_providers должен быть вложен в блок верхнего уровня terraform (который также может содержать другие параметры).

Каждый аргумент в блоке required_providers подключает один провайдер. Ключ задаёт локальное имя провайдера (его уникальный идентификатор в этом модуле), а значением является объект со следующими элементами:

• source — глобальный адрес источника провайдера, который вы собираетесь использовать, например hashicorp/aws.

• version — ограничение версии, указывающее, с каким подмножеством доступных версий провайдера совместим модуль.

Имена и адреса​

У каждого провайдера есть два идентификатора:

• Уникальный адрес источника, который используется только при объявлении требования к провайдеру.
• Локальное имя, которое используется во всех остальных случаях в модуле.

Локальные имена​

Локальные имена задаются отдельно для каждого модуля при объявлении требования к провайдеру. Локальные имена в пределах одного модуля должны быть уникальными.

За пределами блока required_providers конфигурации OpenTofu всегда ссылаются на провайдеры по их локальным именам. Например, в следующей конфигурации для mycorp/mycloud объявляется локальное имя mycloud, которое затем используется при настройке провайдера:

terraform {
  required_providers {
    mycloud = {
      source  = "mycorp/mycloud"
      version = "~> 1.0"
    }
  }
}

provider "mycloud" {
  # ...
}

Пользователи провайдера могут выбрать для него любое локальное имя. Однако почти у каждого провайдера есть предпочтительное локальное имя, которое используется в качестве префикса для всех его типов ресурсов. (Например, имена ресурсов провайдера hashicorp/aws начинаются с aws, например aws_instance или aws_security_group.)

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

Адреса источников​

Адрес источника провайдера — это его глобальный идентификатор. Он также указывает основное место, откуда OpenTofu может загрузить провайдер.

Адрес источника состоит из трёх частей, разделённых косыми чертами (/):

[<HOSTNAME>/]<NAMESPACE>/<TYPE>

• Имя хоста (необязательно): имя хоста реестра, распространяющего провайдер. Если оно не указано, используется значение по умолчанию registry.opentofu.org.

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

• Тип: краткое имя платформы или системы, которой управляет провайдер. Оно должно быть уникальным в пределах заданного пространства имён на конкретном хосте реестра.

  Тип обычно совпадает с предпочтительным локальным именем провайдера. (Есть исключения: например, hashicorp/google-beta — это альтернативный канал выпуска hashicorp/google, поэтому его предпочтительное локальное имя — google. Если вы сомневаетесь, обратитесь к документации провайдера.)

Например, официальный провайдер HTTP принадлежит пространству имён hashicorp на registry.opentofu.org, поэтому его адрес источника — registry.opentofu.org/hashicorp/http, или, что встречается чаще, просто hashicorp/http.

Адрес источника, в котором указаны все три компонента, называется полным адресом провайдера. Полные адреса встречаются в различных выходных данных, например в сообщениях об ошибках, но в большинстве случаев используется сокращённый вариант отображения. В этом варианте опускается хост источника, если это публичный реестр, поэтому вместо "registry.opentofu.org/hashicorp/random" вы можете увидеть сокращённую версию "hashicorp/random".

Разрешение конфликтов локальных имён​

По возможности мы рекомендуем использовать предпочтительное локальное имя провайдера, которое обычно совпадает с частью «тип» в его адресе источника.

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

В таком случае мы рекомендуем объединить пространство имён каждого провайдера с его именем типа, создав составные локальные имена с дефисом:

terraform {
  required_providers {
    # In the rare situation of using two providers that
    # have the same type name -- "http" in this example --
    # use a compound local name to distinguish them.
    hashicorp-http = {
      source  = "hashicorp/http"
      version = "~> 2.0"
    }
    mycorp-http = {
      source  = "mycorp/http"
      version = "~> 1.0"
    }
  }
}

# References to these providers elsewhere in the
# module will use these compound local names.
provider "mycorp-http" {
  # ...
}

data "http" "example" {
  provider = hashicorp-http
  #...
}

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

Ограничения версий​

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

Аргумент version необязателен; если его опустить, OpenTofu будет считать совместимой любую версию провайдера. Однако мы настоятельно рекомендуем указывать ограничение версии для каждого провайдера, от которого зависит модуль.

Чтобы OpenTofu всегда устанавливал одни и те же версии провайдеров для заданной конфигурации, можно воспользоваться OpenTofu CLI для создания файла блокировки зависимостей и добавить его в систему контроля версий вместе с конфигурацией. Если файл блокировки существует, OpenTofu CLI и TACOS (программное обеспечение для автоматизации и совместной работы с TF) будут соблюдать его при установке провайдеров.

Рекомендации по версиям провайдеров​

Как минимум каждый модуль должен объявлять минимальную версию провайдера, с которой он заведомо совместим, используя синтаксис ограничения версии >=:

terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = ">= 1.0"
    }
  }
}

В модуле, предназначенном для использования в качестве корневого модуля конфигурации, то есть в каталоге, где запускается tofu apply, следует также указать максимальную версию провайдера, с которой он должен работать, чтобы избежать случайного обновления до несовместимых новых версий. Оператор ~> — это удобное сокращение, позволяющее увеличивать крайнюю правую часть номера версии. В следующем примере этот оператор используется, чтобы разрешить только исправления в рамках определённого минорного выпуска:

terraform {
  required_providers {
    mycloud = {
      source  = "hashicorp/aws"
      version = "~> 1.0.4"
    }
  }
}

Не используйте ~> (или другие ограничения максимальной версии) в модулях, предназначенных для повторного использования во многих конфигурациях, даже если вы знаете, что модуль несовместим с некоторыми более новыми версиями. Иногда это помогает избежать ошибок, но чаще вынуждает пользователей модуля одновременно обновлять множество модулей при обычном обновлении. Укажите минимальную версию, задокументируйте известные проблемы совместимости, а управление максимальной версией оставьте корневому модулю.

Внутренние провайдеры​

Любой желающий может разрабатывать и распространять собственные провайдеры.

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

Один из способов распространения таких провайдеров — развернуть внутренний закрытый реестр, реализовав протокол реестра провайдеров.

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

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

Например, если бы корпоративным доменом был example.com, можно было бы выбрать tofu.example.com в качестве условного имени хоста, даже если это имя фактически не разрешается через DNS. Затем можно выбрать любое пространство имён и тип для обозначения внутреннего провайдера на этом хосте, получив адрес источника вроде tofu.example.com/examplecorp/ourcloud:

terraform {
  required_providers {
    mycloud = {
      source  = "tofu.example.com/examplecorp/ourcloud"
      version = ">= 1.0"
    }
  }
}

Чтобы сделать версию 1.0.0 этого провайдера доступной для установки из локальной файловой системы, выберите один из подразумеваемых каталогов локального зеркала и создайте в нём следующую структуру каталогов:

tofu.example.com/examplecorp/ourcloud/1.0.0

В каталоге 1.0.0 создайте ещё один каталог, обозначающий платформу, на которой запущен OpenTofu, например linux_amd64 для Linux на процессоре AMD64/x64, а затем поместите в него исполняемый файл плагина провайдера и все необходимые файлы.

Таким образом, в системе Windows исполняемый файл плагина провайдера может находиться по следующему пути:

tofu.example.com/examplecorp/ourcloud/1.0.0/windows_amd64/tofu-provider-ourcloud.exe

Если впоследствии вы решите перейти на настоящий закрытый реестр провайдеров вместо распространения двоичных файлов иным способом, можно развернуть сервер реестра по адресу tofu.example.com и сохранить те же имена пространства имён и типа. В этом случае существующие модули не придётся менять, чтобы находить тот же провайдер через сервер реестра.