Соглашения об именовании в Terraform

Прошло уже почти 5 лет с тех пор, как я избрал Terraform в качестве одного из основных наборов инструментов DevOps и облачной инженерии для управления сервисами моих проектов на AWS, Azure, OpenStack, Github и Datadog. Его очень удобно использовать благодаря простому и понятному человеку синтаксису, а также огромному количеству модулей в реестре HashiCorp. Кроме того, множество поддерживаемых сервисов стали очень популярными среди DevOps и Cloud инженеров, ведь у вас в итоге может быть всего один инструмент для выполнения всех ваших ежедневных IaC рутин.

В этой статье я поделюсь своим опытом в отношении соглашений об именовании при написании стандартных блоков кода в Terraform. Некоторые из них стремятся улучшить стандартный файл Terraform, а некоторые необходимо учитывать из-за скрытых ограничений в соглашениях об именовании в API поставщиков, таких как AWS и Azure.

Общие соглашения

• Всегда используйте _ (нижнее подчеркивание) вместо - (тире)

resource "aws_db_instance" "dev_db" {   ...   name                 = "backend_db_instance"   ... }

• Используйте только буквы в нижнем регистре и цифры:

resource "aws_key_pair" "ops" {   key_name   = "roozbeh_key_1"   public_key = "ssh-rsa ..." }

Соглашения о ресурсах и источниках данных

• Не дублируйте тип ресурса в имени ресурса (ни частично, ни полностью):

resource "aws_route_table" "public" {   vpc_id = aws_vpc.example.id   ... }

• Имя ресурса должно быть проименовано this, если не удается подобрать более описательного и общего имени:

resource "aws_nat_gateway" "this" {   allocation_id = aws_eip.nat.id   subnet_id     = aws_subnet.example.id   ... }

• В качестве имен всегда используйте существительные в единственном числе:

resource "aws_eip" "loadbalancer" {   instance = aws_instance.web.id   vpc      = true }

• Использование — внутри значений аргументов и в местах, где значение будет продемонстрировано человеку (например, внутри DNS-имени инстанса RDS или записи Route 53):

resource "aws_route53_record" "www" {   zone_id = aws_route53_zone.primary.zone_id   name    = "www.example-domain.com"   type    = "A"   ttl     = "300"   records = [aws_eip.lb.public_ip] }

• Добавляйте аргумент count в самый верх блока ресурсов и отделяйте его от остального новой строкой для наглядности:

resource "aws_instance" "web" {   count = "5"      ... }

• Добавляйте аргумент tags, если он поддерживается ресурсом, в качестве последнего реального аргумента, после которого следуют depends_on и lifecycle при необходимости. Все они должны быть разделены одной пустой строкой:

resource "aws_nat_gateway" "this" {   count         = "1"    ...    tags = {     Name = "..."   }    depends_on = ["aws_internet_gateway.this"]    lifecycle {     create_before_destroy = true   } }

• При использовании условия в аргументе count по возможности используйте какое-либо логическое значение, в противном случае используйте length или другую интерполяцию:

count = "${length(var.public_subnets) > 0 ? 1 : 0}"

• Чтобы сделать инвертированные условия, не создавайте новую переменную, если в этом нет реальной необходимости, используйте вместо этого 1 - boolean value:

count = "${1 - var.create_public_subnets}"

Соглашения о переменных

• Не изобретайте колесо в ресурсных модулях — используйте те же имена переменных, описание и значение по умолчанию как определено в разделе «Argument Reference» для ресурса, с которым вы работаете.

• Используйте объявление type = "list", если default = []:

variable "availability_zone_names" {   type    = list(string)   default = [     "eu-central-1a"     "eu-central-1b"     "eu-central-1c"   ] }

• Используйте объявление type = "map", если default = {}:

variable "images" {   type = "map"    default = {     eu-central-1 = "image-1234"     eu-west-1    = "image-4567"   } }

• Используйте множественное числа в именах переменных типа list и map:

variable "users" {   type    = "list"   ... }

variable "images" {   type = "map"   ... }

• При определении переменных порядок следующий: description , type, default. Всегда добавляйте description для всех переменных, даже если вы думаете, что это очевидно.

variable "key" {   description = "description"   type        = "string"   default     = "value" }

Выводы (Outputs)

Важно именовать выводы таким образом, чтобы сделать их единообразными и понятными за пределами их области действия (когда пользователь использует модуль, должно быть очевидно какой тип и атрибут значения возвращаются).

• Общая рекомендация для именования выводов состоит в том, что они должны быть достаточно описательными для значения, которое они содержат, и иметь более лаконичную форму, чем вы обычно хотели бы.

• Хорошая структура для имен вывода выглядит так — {имя}_{тип}_{атрибут}, где:

1. {имя} — имя ресурса или источника данных без префикса поставщика. {имя} для aws_subnet — это subnet, а для aws_vpc — vpc.

2. {тип} — это тип источника ресурса.

3. {атрибут} является атрибутом возвращаемого вывода.

• Если выход возвращает значение с интерполяционными функциями и множеством ресурсов, {имя} и {тип} должны быть максимально стандартизованы (this зачастую является наиболее общим и поэтому предпочтительным).

• Если возвращаемое значение является списком, оно должно иметь имя во множественном числе.

• Всегда включайте description для всех результатов, даже если вы думаете, что это очевидно.

---

Материал подготовлен в рамках курса «Infrastructure as a code». Если вам интересно узнать подробнее о формате обучения и программе, познакомиться с преподавателем курса — приглашаем на день открытых дверей онлайн. Регистрация здесь.