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

dns_zones/variables.tf

@@ -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({