Terraform

Репозитории (реестры) Terraform VK Registry предназначены для публикации и скачивания модулей Terraform. Модуль — версионированный архив с конфигурациями Terraform для создания облачных ресурсов.

Публикация модулей выполняется с помощью API VK Registry.

Скачивание, получение версий и ссылок на модули выполняется по протоколу реестра модулей (Module Registry protocol), который определяет, как Terraform CLI работает с репозиторием. Подробнее — в официальной документации Terraform.

В таблице 1 приведены особенности репозиториев Terraform VK Registry.

Подробнее о создании репозитория и его параметрах — в разделе Создание репозитория.

1. Архив модуля должен иметь одно из расширений: tar.bz2, tar.gz, tar.tbz2, tbz2, tgz, txz, zip.

2. Путь к артефакту внутри репозитория Terraform должен соответствовать формату:

    
   <ПРОСТРАНСТВО_ИМЕН>/<ИМЯ_МОДУЛЯ>/<СИСТЕМА>/<ВЕРСИЯ_МОДУЛЯ>/<ИМЯ_АРХИВА>.<РАСШИРЕНИЕ_АРХИВА>

   Здесь:

   • <ПРОСТРАНСТВО_ИМЕН> — идентификатор организации или владельца. Пример: my-org.
   • <ИМЯ_МОДУЛЯ> — название модуля Terraform. Пример: my-module.
   • <СИСТЕМА> — название провайдера или платформы, для которой предназначен модуль. Пример: generic.
   • <ВЕРСИЯ_МОДУЛЯ> — семантическая версия модуля. Примеры: 1.0.0, v1.0.0.
   • <ИМЯ_АРХИВА> — имя файла архива. Пример: my-module-1_0_0.
   • <РАСШИРЕНИЕ_АРХИВА> — расширение архива. Полный список разрешенных расширений — в пункте 1.

3. Компонент модуля должен включать параметры: пространство имен, имя модуля и версия модуля.

4. Артефакт должен иметь атрибуты: пространство имен, имя модуля, система и версия модуля.

5. Если в репозитории Terraform включена проверка MIME-типа, модули должны иметь типы согласно таблице 2.

Чтобы начать работу с репозиториями VK Registry через Terraform CLI, отредактируйте файл конфигурации:

1. Откройте файл:

   • ~/.terraformrc для Unix-подобных ОС;
   • %APPDATA%\terraform.rc для Windows.

2. Добавьте в файл данные для доступа к модулям:

   • Имя хоста VK Registry и имя репозитория Terraform.
   • API-ключ пользователя для доступа к репозиторию Terraform.

   Формат указания данных:

    
   host "<ХОСТ>" {  services = {    "modules.v1"   = "https://<ХОСТ>/repository/<ИМЯ_РЕПОЗИТОРИЯ>"  }}credentials "<ХОСТ>" {  token = "<API_КЛЮЧ>"}

   Здесь:

   • <ХОСТ> — имя хоста вашего экземпляра VK Registry.
   • <ИМЯ_РЕПОЗИТОРИЯ> — имя репозитория.
   • <API_КЛЮЧ> — API-ключ Terraform из профиля пользователя или администратора (подробнее — в разделе Управление API-ключами).

1. Убедитесь, что в рабочей директории есть файл с расширением .tf, в котором запрашивается хотя бы один модуль из репозитория Terraform.

   Формат запроса модуля:

    
   module "my_module" {  source  = "<ХОСТ>/<ПРОСТРАНСТВО_ИМЕН>/<ИМЯ_МОДУЛЯ>/<СИСТЕМА>"  version = "= <ВЕРСИЯ_МОДУЛЯ>"}

   Здесь:

   • <ХОСТ> — имя хоста вашего экземпляра VK Registry.
   • <ПРОСТРАНСТВО_ИМЕН> — идентификатор организации или владельца. Пример: my-org.
   • <ИМЯ_МОДУЛЯ> — название модуля Terraform. Пример: my-module.
   • <СИСТЕМА> — название провайдера или платформы, для которой предназначен модуль. Пример: generic.
   • <ВЕРСИЯ_МОДУЛЯ> — семантическая версия модуля. Примеры: 1.0.0, v1.0.0.

2. Выполните команду Terraform CLI из рабочей директории:

   • terraform init — для инициализации рабочего каталога, в том числе загрузки модуля из репозитория Terraform.
   • terraform get — для загрузки модулей, указанных в конфигурации Terraform, в директорию .terraform/modules.

1. Убедитесь, что модуль соответствует требованиям (подробнее — в разделе Требования к загружаемым модулям).

2. Авторизуйтесь в VK Registry.

3. Перейдите в раздел Система → API.

4. Перейдите в раздел Компоненты V2 → Загрузить компонент, чтобы отправить запрос POST /v2/components​.

5. Укажите имя репозитория Terraform в query-параметре repository.

6. Заполните параметры в теле запроса:

   • terraform.asset — архив модуля. Чтобы загрузить, нажмите кнопку Select File.
   • terraform.asset.name — имя модуля.
   • terraform.asset.namespace — пространство имен.
   • terraform.asset.system — система.
   • terraform.asset.version — версия модуля.

   Формат запроса для загрузки модуля:

    
   $ curl 'https://<ХОСТ>/service/rest/v2/components?repository=<ИМЯ_РЕПОЗИТОРИЯ>' \  --request POST \  --header 'Content-Type: multipart/form-data' \  --header 'Accept: */*' \  --form 'terraform.asset=@<ИМЯ_АРХИВА>.<РАСШИРЕНИЕ_АРХИВА>' \  --form 'terraform.asset.name=<ИМЯ_МОДУЛЯ>' \  --form 'terraform.asset.namespace=<ПРОСТРАНСТВО_ИМЕН>' \  --form 'terraform.asset.system=<СИСТЕМА>' \  --form 'terraform.asset.version=<ВЕРСИЯ_МОДУЛЯ>'

7. Нажмите Send для отправки запроса.

Подробнее о работе с REST API — в разделе REST API.

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

Формат команды:

 
$ curl 'https://<ХОСТ>/repository/<ИМЯ_РЕПОЗИТОРИЯ>/<ПРОСТРАНСТВО_ИМЕН>/<ИМЯ_МОДУЛЯ>/<СИСТЕМА>/versions'

Используйте утилиту curl, чтобы получить ссылку на скачивание модуля.

Формат команды:

 
$ curl -i 'https://<ХОСТ>/repository/<ИМЯ_РЕПОЗИТОРИЯ>/<ПРОСТРАНСТВО_ИМЕН>/<ИМЯ_МОДУЛЯ>/<СИСТЕМА>/<ВЕРСИЯ_МОДУЛЯ>/download'