docs: подробные комментарии в примерах DNS-зон и записей

2026-10-16 16:04:19 +03:00
parent 42048d058a
commit c8acf87c0c
8 changed files with 138 additions and 36 deletions
@@ -1,40 +1,72 @@
 # =============================================================================
-# Пример: доменные зоны компании и записи в них — через Terraform.
+# Пример: доменные зоны компании и записи DNS — целиком через Terraform.
+#
+# Задача: держать доменные зоны и их записи в коде (IaC), а не руками в ЛК.
 #
 # Ресурсы провайдера Nubes:
-#   - nubes_zones_v2        (сервис 109)              — DNS-зона;
-#   - nubes_zones_v2_record (подресурс зоны, record)  — запись внутри зоны.
+#   - nubes_zones_v2        (сервис 109)             — DNS-зона;
+#   - nubes_zones_v2_record (подресурс зоны, record) — запись внутри зоны
+#     (A / CNAME / …). Записи — ОТДЕЛЬНЫЕ ресурсы, поэтому ими можно управлять
+#     адресно: добавить/изменить/удалить одну запись, не трогая зону целиком.
 #
-# ⚠️ Имя поля в HCL = `name` из схемы (snake_case); `code` (camelCase) — имя в API.
+# ⚠️ В HCL пишется `name` поля из схемы (snake_case): `zone_name`, `record_name`,
+#    `record_type`, `record_input`, `record_ttl`. `code` (camelCase) — внутреннее
+#    имя в API, в HCL НЕ используется.
 #
-# Зоны задаются картой `var.zones` (ключ → zone_name + records).
-# Чтобы добавить/убрать зону или запись — правьте `var.zones` и делайте `apply`.
+# КАК РАСШИРЯТЬ: чтобы добавить/убрать зону или запись — правьте `var.zones`
+# (в variables.tf или terraform.tfvars) и делайте `terraform apply`.
+# Ключи карт (`a`, `b`, `www`, …) — это АДРЕСА объектов в state. Меняйте их
+# осознанно: смена ключа = «удалить старый объект + создать новый», а не
+# «переименовать». Само значение `zone_name`/`record_input` меняется обычным
+# `apply`.
 # =============================================================================

+# ── locals.records: «уплощаем» вложенную структуру «зоны → записи» ────────────
+#
+# var.zones — карта «зона → { zone_name, records }», где records — ещё одна
+# карта «имя записи → { type, values }».
+#
+# Ресурсу записи нужен ОДИН плоский набор, где у каждого элемента УНИКАЛЬНЫЙ
+# ключ: тогда `for_each` создаст ровно по одному ресурсу на запись и даст
+# стабильные адреса вида `nubes_zones_v2_record.record["a:www"]`.
+#
+# `merge([ ... ]...)` — разворот (`...`) списка карт в один вызов merge —
+# склеивает карты из каждой зоны в общую. Ключ собираем как "<зона>:<запись>",
+# чтобы записи с одинаковыми именами в разных зонах не столкнулись.
 locals {
-  # Плоская карта записей «зона:имя» (вложенный цикл → merge/flatten),
-  # чтобы `for_each` у записей давал стабильные адреса.
  records = merge([
    for zk, z in var.zones : {
      for rk, r in z.records :
      "${zk}:${rk}" => {
-        zone   = zk
-        name   = rk
-        type   = r.type
-        values = r.values
+        zone   = zk       # какая зона (ключ карты var.zones)
+        name   = rk       # имя записи
+        type   = r.type   # тип записи (A / CNAME / …)
+        values = r.values # список значений записи
      }
    }
  ]...)
 }

-# Зоны: N штук из var.zones (for_each по ключам карты — стабильные адреса).
+# ── Зоны ─────────────────────────────────────────────────────────────────────
+# `for_each = var.zones` — по одному ресурсу на каждый КЛЮЧ карты зон.
+# `each.key`  — короткое имя зоны (a, b, …), `each.value` — её параметры.
+# `resource_name` — человекочитаемое имя ресурса в Nubes; `zone_name` — сам
+# домен (FQDN зоны).
 resource "nubes_zones_v2" "zone" {
  for_each      = var.zones
  resource_name = "dns-zone-${each.key}"
  zone_name     = each.value.zone_name
 }

-# Записи: record_input = [{record=<значение>}, ...] из списка values.
+# ── Записи ───────────────────────────────────────────────────────────────────
+# `for_each = local.records` — по одному ресурсу на запись (плоская карта выше).
+# `zones_v2_id` — ссылка на id СВОЕЙ зоны (через for_each зоны): Terraform сам
+#   построит зависимость «зона создаётся раньше своих записей».
+#
+# `record_input` — платформа ждёт JSON-массив объектов `[{ record = "<значение>" },
+# …]`, поэтому собираем его из плоского списка `values` через `jsonencode`.
+# Одна запись может иметь НЕСКОЛЬКО значений (напр. два A-адреса) — это одна
+# запись с массивом, а не две отдельные.
 resource "nubes_zones_v2_record" "record" {
  for_each     = local.records
  zones_v2_id  = nubes_zones_v2.zone[each.value.zone].id
@@ -43,3 +75,4 @@ resource "nubes_zones_v2_record" "record" {
  record_input = jsonencode([for v in each.value.values : { record = v }])
  record_ttl   = 3600
 }
+
@@ -1,3 +1,8 @@
+# Конфигурация провайдера Nubes.
+#   api_token    — секрет (передаётся из secrets.auto.tfvars);
+#   api_endpoint — адрес API Gateway стенда.
+# ⚠️ Атрибута `realm` у провайдера НЕТ — ресурсная платформа задаётся параметром
+#    ресурса (напр. `startup_configuration.resource_realm`), а не здесь.
 provider "nubes" {
  api_token    = var.api_token
  api_endpoint = var.api_endpoint
@@ -1,19 +1,36 @@
-# Переменные примера. api_token — СЕКРЕТ, держать в secrets.auto.tfvars (не коммитить).
+# =============================================================================
+# Переменные примера «DNS-зоны и записи».
+#
+# ⚠️ api_token — СЕКРЕТ. НЕ кладите его в terraform.tfvars. Держите в отдельном
+#    файле `secrets.auto.tfvars` (Terraform сам подхватывает `*.auto.tfvars`),
+#    а этот файл закройте в .gitignore. Значение — JWT из ЛК (Профиль → Токены).
+# =============================================================================

+# Токен доступа (JWT) к API Nubes. `sensitive = true` — Terraform не покажет
+# значение в выводе плана/apply.
 variable "api_token" {
  description = "Nubes API token (JWT). Секрет — в secrets.auto.tfvars."
  type        = string
  sensitive   = true
 }

+# Адрес API Gateway стенда. Для TEST — как в default.
 variable "api_endpoint" {
  description = "API Gateway URL стенда"
  type        = string
  default     = "https://lk-api-gateway-test.ngcloud.ru/api/v1/svc"
 }

-# Зоны: карта «короткое имя → { zone_name, records }».
-# records — карта «имя записи → { type, values }».
+# ── Зоны и записи ────────────────────────────────────────────────────────────
+# Карта «короткое имя зоны → { zone_name, records }»:
+#   - КЛЮЧ карты (a, b, …) — адрес зоны в state (стабильный id объекта в TF);
+#   - zone_name            — сам домен (FQDN зоны);
+#   - records              — карта «имя записи → { type, values }»:
+#       - type   — тип записи (A / CNAME / TXT / …), по умолчанию "A";
+#       - values — СПИСОК значений (одна запись может иметь их несколько,
+#                  напр. два A-адреса у одного имени).
+#
+# Здесь задан дефолт (2 зоны × 3 записи). Можно переопределить в terraform.tfvars.
 variable "zones" {
  description = "Зоны компании: имя + записи (type / values[])"
  type = map(object({
@@ -1,9 +1,13 @@
+# Версии Terraform и провайдера Nubes.
 terraform {
-  required_version = ">= 1.5.0"
+  required_version = ">= 1.5.0" # минимальная версия Terraform

  required_providers {
    nubes = {
-      source  = "tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes"
+      # Реестр провайдера стенда TEST. Для другого стенда — свой namespace:
+      #   PROD → .../nubes/nubes,  DEV → .../nubes-dev/nubes
+      source = "tf-registry.containerk8s.services.ngcloud.ru/nubes-test/nubes"
+      # Фиксируем версию провайдера — для воспроизводимости.
      version = "3.4.0"
    }
  }