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

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. Этот провайдер предоставляет источник данных terraform_remote_state.

Поскольку этот провайдер встроен в OpenTofu, для использования его функций не нужно объявлять его в блоке required_providers. Однако для единообразия у него есть специальный адрес источника провайдера — terraform.io/builtin/terraform. Этот адрес иногда может появляться в сообщениях об ошибках и других выходных данных OpenTofu, чтобы однозначно указать на встроенный провайдер, а не на гипотетический сторонний провайдер с типом «tofu».

Также существует провайдер с адресом источника hashicorp/terraform — это более старая версия провайдера, который теперь встроен в OpenTofu. hashicorp/terraform несовместим с OpenTofu, и его никогда не следует объявлять в блоке required_providers.

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

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

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