Модули Terraform#

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

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

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

Назначение#

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

Примечание

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

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

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

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

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

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

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

Название модулей, размещенных в реестре Astra 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/

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

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

Примечание

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

.terraformrc

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

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

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

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

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

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

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

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

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

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

Необходим доступ к реестру Astra 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 }]
}
```
Примечание

Для всех модулей из реестра Astra 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 см. в документе Среда исполнения.

Поле	Значение
`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`