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

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