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

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 всегда ссылаются на провайдеры по их локальным именам. Например, следующая конфигурация объявляет mycloud локальным именем для mycorp/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 и сохранить те же имена пространства имён и типов. В этом случае существующие модули не придётся изменять, чтобы находить тот же провайдер через сервер реестра.