# DNS API Selectel (actual)

> Проверьте DNS запись Selectel перед переводом трафика: убедитесь, что активный A адрес и TTL совпадают с планом изменения.

- HTML: https://poapi.ru/selectel/api-dns-hostinga-actual
- Компания: Selectel
- Страница компании: https://poapi.ru/company/selectel
- Категории: Администрирование
- Сайт API: https://docs.selectel.ru/dns-hosting/about-dns/
- Документация: https://docs.selectel.ru/api/dns-actual/

## Подключение и ограничения
- Авторизация: Передавайте IAM-токен проекта в X-Auth-Token. Срок действия — 24 часа; адрес DNS actual API для российских регионов — https://api.selectel.ru/domains/v2.
- Ограничения: DNS API actual v2.0 требует FQDN с завершающей точкой для имени зоны и RRSet. GET /zones/{zone_id}/rrset принимает limit и offset, фильтры rrset_types и name, возвращает count, next_offset и result. API показывает состояние у Selectel; кеши рекурсивных DNS-серверов нужно проверять отдельно. Нужны Bash, curl и jq; тайм-аут подключения — 5 секунд, общий тайм-аут — 30 секунд.

```bash
#!/usr/bin/env bash
set -euo pipefail
: "${DNS_TOKEN:?set project IAM token}"
: "${ZONE_ID:?set zone UUID}"
: "${RECORD_NAME:?set FQDN ending with a dot, e.g. api.example.com.}"
: "${EXPECTED_IP:?set expected IPv4 address}"
: "${EXPECTED_TTL:?set expected TTL in seconds}"
base='https://api.selectel.ru/domains/v2/zones/'"$ZONE_ID"'/rrset'
offset=0
found=false
while :; do
  response=$(curl --fail --silent --show-error --connect-timeout 5 --max-time 30 \
    --header "X-Auth-Token: $DNS_TOKEN" --get "$base" \
    --data-urlencode 'limit=1000' --data-urlencode "offset=$offset" \
    --data-urlencode 'rrset_types=A' --data-urlencode "name=$RECORD_NAME")
  sets=$(printf '%s\n' "$response" | jq --arg name "$RECORD_NAME" '[.result[] | select(.name == $name and .type == "A")] | length')
  if (( sets > 0 )); then
    (( sets == 1 )) || { echo 'multiple matching A record sets returned' >&2; exit 1; }
    printf '%s\n' "$response" | jq -e --arg name "$RECORD_NAME" --arg ip "$EXPECTED_IP" --argjson ttl "$EXPECTED_TTL" \
      '([.result[] | select(.name == $name and .type == "A")] | .[0]) as $rrset | $rrset.ttl == $ttl and ([$rrset.records[] | select((.disabled // false) == false) | .content] | sort) == [$ip]' >/dev/null || { echo 'A record values or TTL do not match expected active RRSet' >&2; exit 1; }
    found=true
  fi
  next=$(printf '%s\n' "$response" | jq -r '.next_offset')
  [[ $next == null || $next == 0 ]] && break
  [[ $next =~ ^[0-9]+$ && $next -gt $offset ]] || { echo 'invalid DNS pagination cursor' >&2; exit 1; }
  offset=$next
done
[[ $found == true ]] || { echo 'expected A record set not found' >&2; exit 1; }
echo 'DNS A record and TTL preflight passed'

```
- Результат: HTTP 200 JSON содержит result[] с RRSet {name, ttl, type, records[]}; запись содержит content и disabled. Пример проходит страницы по next_offset, находит ровно один RRSet и принимает его только если TTL совпадает, а полный список активных адресов содержит ровно ожидаемый IP. disabled=true не считается активным; дополнительный активный адрес приводит к отказу. Клиентская логика проверена локально на искусственных ответах, без обращения к API Selectel.
- Ошибки: Для списка документированы 401, 404, 422 и 500; curl --fail прерывает сценарий при HTTP-ошибке. Отсутствующий RRSet, неверный TTL, отключённый адрес, лишний активный адрес, несколько RRSet или некорректный next_offset завершают пример с ошибкой.
- Проверено по документации: 2026-11-15
- [DNS API actual v2](https://docs.selectel.ru/api/dns-actual/)
- [Стоимость и ограничения DNS-хостинга](https://docs.selectel.ru/dns-hosting/about-dns/)
- [URL API Selectel](https://docs.selectel.ru/api/urls/)

## Описание
DNS API (actual) управляет зонами DNS хостинга и их RRSet — наборами однотипных записей в зоне. API поддерживает создание, чтение, обновление и удаление зон и записей, изменение состояния зоны и защиту от удаления. Для поддомена или домена приложение может автоматизировать проверку A/AAAA/MX/TXT записей, а уполномоченный процесс — менять наборы записей. Это актуальный DNS API Selectel; не смешивайте его с legacy DNS API, для которого документация отдельно описывает завершение поддержки.

## Зона, RRSet и пределы проверки

DNS actual API управляет зонами и RRSet — наборами записей одного имени и типа с общим TTL. API actual использует отдельный endpoint от устаревшего DNS legacy.

Хостинг предоставляется бесплатно в дополнение к другим платным услугам. Для доступа нужна регистрация и пополнение баланса не менее чем на 200 ₽. Selectel DNS нельзя использовать как Secondary DNS.

## Проверка активной A-записи

Пример читает RRSet по UUID зоны и FQDN, проходит страницы по next_offset и сравнивает TTL с ожидаемым. Он принимает только один RRSet с ровно одним активным адресом — ожидаемым IPv4.

Записи с disabled=true не считаются активными. Если адрес выключен, TTL другой или есть дополнительный активный адрес, скрипт завершится ошибкой; перевод трафика нужно остановить.

## Безопасное изменение и проверка распространения

Перед изменением сохраните весь текущий RRSet и проверьте managed_by. Если набором управляет другой сервис, его контроллер может вернуть прежнее значение; согласуйте изменение с владельцем.

После изменения перечитайте RRSet и проверьте адреса и TTL. Затем проверьте DNS-ответ через рекурсивные DNS-серверы клиентов: API подтверждает состояние у провайдера, но кеши могут обновиться позже.

## Когда использовать
- Перед переключением приложения проверьте, что A-запись содержит ровно один активный IPv4-адрес из плана изменения и заданный TTL.
- Система управления доменом перечитывает RRSet после согласованного изменения и сверяет полный набор значений.
- При переносе домена с DNS legacy на actual команда проверяет, что зона создана в актуальном API до смены делегирования.

## Порядок интеграции
1. Создайте зону DNS actual в нужном проекте, делегируйте домен на авторитетные NS Selectel и сохраните UUID. Хостинг бесплатен как дополнение к другим платным услугам; для доступа нужна регистрация и минимальное пополнение баланса 200 ₽.
2. Получите IAM-токен проекта и выберите адрес https://api.selectel.ru/domains/v2. Имя зоны и RRSet указывайте как FQDN с завершающей точкой.
3. Запросите RRSet фильтрами name и rrset_types=A. Следуйте next_offset; сравните TTL и весь список активных records[].content с ожидаемым IP.
4. При несовпадении остановите переключение. Перед изменением сохраните прежний RRSet и проверьте managed_by; после согласованного изменения перечитайте объект и снова сравните TTL и адреса.
5. Отдельно проверьте DNS-ответы из сетей клиентов. Рекурсивный сервер может хранить прежний ответ до истечения TTL.

## Что проверить перед запуском
- Имя зоны и RRSet должно быть полным доменным именем с точкой на конце, например api.example.com.
- Наличие ожидаемого IP среди нескольких активных значений не соответствует проверке: сравнивайте весь список активных адресов, флаг disabled и TTL.
- Список RRSet разбит на страницы. Не делайте вывод об отсутствии записи, пока API возвращает следующий offset.
- Ответ API не подтверждает обновление кешей рекурсивных серверов. Проверьте DNS-ответ из нужных сетей и учтите TTL.
- DNS actual и legacy используют разные API; legacy отключается в 2026 году. Используйте endpoint actual.

## Связанные API
- [DNS-хостинг Selectel (legacy): перенос зон](https://poapi.ru/selectel/dns-hosting-legacy): Legacy DNS хостинг Selectel больше нельзя менять через API или панель; перенесите зоны в актуальный сервис до отключения старых NS 1 декабря 2026 года.
- [Managed Kubernetes API Selectel](https://poapi.ru/selectel/api-managed-kubernetes): Проверьте завершение операции Managed Kubernetes Selectel и готовность кластера к выкладке: дождитесь DONE, затем сверьте ACTIVE и требуемую версию Kubernetes.
