Ctrl+K

Это не самая новая версия документации. Для изменения используйте переключатель версий или перейдите на новейшую версию!

Ctrl+K
Ctrl+K

Модули Terraform

Модули Terraform#

Предупреждение

Terraform не является частью Astra Automation. Модули, размещенные в реестре Automation Hub, со временем будут удалены.

Использование модулей позволяет упростить управление ресурсами с помощью Terraform. Модули Terraform, разрабатываемые командой Astra Automation, доступны в реестре.

Назначение#

Каждому модулю из реестра Automation Hub соответствует отдельный репозиторий. Модули ориентированы на определенное рабочее окружение для развертывания (ПК СВ «Брест», Yandex Cloud, Cloud.ru и другие) и выполняют определенную функцию. Например, модуль yandex-cloud-compute-instance используется для создания одного или нескольких экземпляров (instance) виртуальных машин в облаке Yandex Cloud.

Примечание

Terraform можно использовать для управления инфраструктурой в окружениях, для которых существуют соответствующие провайдеры.

Структура рабочего окружения#

При использовании модулей из реестра Automation Hub схема работы Terraform имеет вид:

../../../_images/terraform-schema-light.svg ../../../_images/terraform-schema-dark.svg

  1. Terraform загружает на управляющий узел необходимые провайдеры из реестра провайдеров HashiCorp (или другого источника) и модули из реестра Automation Hub.

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

Содержание реестра#

Название модулей, размещенных в реестре Automation Hub, зависит от используемого провайдера и типа ресурсов. Список существующих модулей представлен в документе Модули Terraform.

Структура модуля#

В составе модуля могут быть следующие файлы и каталоги:

  • datasources.tf

    Источники данных, используемые модулем, например:

    data "vsphere_datacenter" "datacenter" {
  name = var.vsphere_datacenter_name
}

data "vsphere_network" "project_network" {
  name          = "${var.name}-port-group"
  datacenter_id = data.vsphere_datacenter.datacenter.id
  depends_on    = [vsphere_host_port_group.port_group]
}

    Здесь datacenter и project_network – источники данных типов vsphere_datacenter и vsphere_network соответственно. При этом доступ к нужному ресурсу типа vsphere_datacenter производится с помощью поиска по названию (атрибут name), а доступ к ресурсу типа vsphere_network – по названию сети и идентификатору ресурса типа vsphere_datacenter.

  • main.tf

    Основной код модуля. Содержит описание создаваемых ресурсов и зависимостей между ними.

  • outputs.tf

    Описание значений, возвращаемых модулем.

    Возвращаемые значения имеют следующие особенности:

    • выводятся в терминал при выполнении команд Terraform;

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

    Пример описания возвращаемых значений:

    output "id" {
  description = "The VPC ID in UUID format."
  value       = sbercloud_vpc.this.id
}

output "name" {
  description = "Specifies the name of the VPC."
  value       = try(sbercloud_vpc.this.name, "")
}

output "subnet_ids" {
  description = "Map of subnet name => subnet ID pairs"
  value       = { for sb in var.subnets : sb.name => sbercloud_vpc_subnet.subnet[sb.name].id if sbercloud_vpc_subnet.subnet[sb.name].id != null }
}

    Здесь:

    • id – идентификатор облачной сети;

    • name – название облачной сети;

    • subnet_ids – список идентификаторов подсетей.

  • variables.tf

    Описание переменных модуля: названия, типы, ограничения, способы проверки, значения по умолчанию и так далее.

    Например, в модуле sbercloud-vpc имеется такое описание переменной subnets:

    variable "subnets" {
  description = "A list of subnets inside the VPC"
  type = list(object({
    name                              = string,
    cidr                              = string,
    availability_zone                 = string,
    gateway_ip                        = optional(string, null),
    create_nat_gateway                = optional(bool, false),
    nat_gateway_spec                  = optional(string, "1"),
    nat_gateway_description           = optional(string, null),
    nat_gateway_enterprise_project_id = optional(string, null)
  }))
  default = [{ name = "vpc-default-subnet1", cidr = "10.0.0.0/24", gateway_ip = "10.0.0.1", create_nat_gateway = false, availability_zone = "ru-moscow-1a" }]
}

    Здесь:

    • subnets – название переменной.

    • description – краткое описание переменной.

    • type – тип переменной. В данном случае – список объектов, каждый из которых содержит следующие поля:

      • name – название подсети;

      • cidr – диапазон IP-адресов подсети в формате CIDR;

      • availability_zone – зона доступности, в которой размещается подсеть;

      • gateway_ip – IP-адрес шлюза, используемого подсетью;

      • create_nat_gateway – использование технологии NAT;

      • nat_gateway_spec – тип шлюза, определяющий максимальное количество подключений SNAT;

      • nat_gateway_description – описание шлюза;

      • nat_gateway_enterprise_project_id – идентификатор проекта на платформе Enterprise.

      Примечание

      Поля gateway_ip, create_nat_gateway, nat_gateway_spec, nat_gateway_description и nat_gateway_enterprise_project_id не обязательны для заполнения.

    • default – значение переменной subnets по умолчанию. Для указанных выше полей используются следующие значения:

      Поле

      Значение

      name

      vpc-default-subnet1

      cidr

      10.0.0.0/24

      gateway_ip

      10.0.0.1

      create_nat_gateway

      false

      availability_zone

      ru-moscow-1a

  • versions.tf

Требования к версиям Terraform и провайдера, например:

terraform {
  required_version = ">= 1.3.0"

  required_providers {
    yandex = {
      source  = "yandex-cloud/yandex"
      version = ">= 0.84"
    }
  }
}

Здесь:

  • terraform.required_version – для работы с модулем следует использовать версию Terraform не ниже 1.3.0;

  • terraform.required_providers.yandex – модуль зависит от провайдера Yandex Cloud;

  • terraform.required_providers.yandex.source – ссылка для загрузки файлов провайдера Yandex Cloud (указанное здесь значение будет использовано, если источник не задан в настройках проекта);

  • terraform.required_providers.yandex.version – для работы с модулем следует использовать версию провайдера Yandex Cloud не ниже 0.84.

Применение#

Несмотря на то, что Terraform не имеет строгих требований к структуре проекта, описанные в документации Astra Automation проекты Terraform устроены одинаково.

Типовая структура проекта#

Проекты, описанные в документе Модули Terraform, имеют одинаковую структуру и могут включать в себя следующие каталоги и файлы:

  • .terraform/modules/

    Каталог с кодом сторонних модулей. В него загружаются модули из реестра Automation Hub.

  • .terraform/providers/

    Каталог с файлами провайдеров.

Примечание

Каталог .terraform/ и его подкаталоги создаются в каталоге проекта автоматически в результате выполнения команды terraform init.

  • .terraformrc

    Настройки, влияющие на поведение Terraform. Как правило, в этом файле указываются альтернативные источники для загрузки файлов провайдеров.

  • provider.tf

    Список используемых провайдеров и их настройки.

  • variables.tf

    Декларация переменных, используемых в проекте. Для каждой переменной указываются:

    • обязательные параметры:

      • название;

      • тип;

    • опциональные параметры:

      • описание;

      • правила проверки;

      • значение по умолчанию.

  • terraform.tfvars

    Присваивание фактических значений переменным, декларированным в файле variables.tf.

  • metadata.yml

    Настройки ВМ для сервисов, поддерживающих технологию Cloud-Init.

  • main

    Здесь размещается описание инфраструктуры. В этом же файле подключаются и используются модули из реестра Automation Hub.

  • deployment и deployment.pub

    Пара ключей SSH, которая используется для подключения к создаваемым ВМ.

    Пошаговая инструкция по созданию ключей приведена в секции Ключи SSH для доступа к стендам.

Использование модулей#

Использование модулей Terraform из реестра Automation Hub имеет следующие особенности:

  • Необходим доступ к реестру Automation Hub по SSH, настроенный согласно инструкции.

  • Для подключения нужных модулей используется конструкция следующего вида:

    module "module_name" {
  source = "git::ssh://git@hub.astra-automation.ru:2222/aa-gca/AMFT/module_name.git"
  name   = "resource_name"
  # ...
}

    где

    • module_name – название модуля;

    • resource_name – название ресурса.

    Например, для модуля brest-virtual-machine указанная запись должна иметь вид:

    module "brest-virtual-machine" {
  source               = "git::ssh://git@git.astralinux.ru:7999/amft/brest-virtual-machine.git"
  name                 = "brest-virtual-machine-module-test"
  group                = "brest-mng-group"
  system_disk_image_id = 204
  networks             = [{ id = 1 }]
}

    Примечание

    Для всех модулей из реестра Automation Hub в поле source следует указывать ссылку на соответствующий репозиторий.

  • Перед первым использованием модули необходимо загрузить в рабочий каталог с помощью команды:

    docker run \
   --rm \
   --interactive \
   --tty \
   --volume ~/.ssh/hub.astra-automation.ru:/root/.ssh/id_rsa \
   --volume "$(pwd):/app" \
   registry.astralinux.ru/aa/aa-base-ee \
   bash -c 'terraform init'

    Подробности об использовании EE см. в документе Среда исполнения.

Содержание