name: zones_v2
service_id: 109
service_display_name: Управление DNS
service_short_name: zonesV2
service_man: '# Управление DNS
## Что делает сервис
Управляет DNS-зоной вашего домена в инфраструктуре `ngcloud.ru`.
Сервис помогает:
- создать DNS-зону;
- поддерживать записи в зоне (добавлять, удалять, массово менять);
- удалять зону;
- синхронизировать данные зоны с фактическим состоянием на DNS-серверах.
Сервис работает с авторитетными DNS-серверами зоны:
- `ns3.ngcloud.ru`
- `185.247.187.83`
- `2a10:aa80:0:5::3`
- `ns4.ngcloud.ru`
- `81.22.46.43`
- `2a10:aa80:0:6::3`
## Очень важно: что сделать у регистратора домена
Чтобы зона действительно начала обслуживаться, **нужно делегировать домен** у регистратора на авторитетные DNS-серверы:
- `ns3.ngcloud.ru`
- `ns4.ngcloud.ru`
В панели регистратора нужно заменить NS-серверы домена на значения выше.
Без этого записи в зоне могут быть созданы, но интернет не будет использовать их для вашего домена.
## Проверка после настройки
Проверить ответы от серверов зоны:
```bash
dig <ваш_домен> @ns3.ngcloud.ru
dig <ваш_домен> @ns4.ngcloud.ru
```
Проверить, что делегирование у регистратора применилось:
```bash
dig <ваш_домен> NS
```
В ответе должны быть `ns3.ngcloud.ru` и `ns4.ngcloud.ru`.
'
lifecycle:
suspend_on_destroy_default: false
adopt_existing_on_create_default: false
outputs:
params:
- code: state_params
type: map
- code: state_out
type: map
- code: state_params_flat
type: map
- code: state_out_flat
type: map
- code: vault_secrets
type: map
sensitive: true
- code: vault_url
type: string
- code: vault_user_path
type: string
- code: vault_fields
type: list
operations:
- name: create
id: 254
kind: instance
action: create
man: '# Операция `create` (создание DNS-зоны)
## Что делает операция
`create` создает новую DNS-зону на авторитетных серверах сервиса.
После создания зона закрепляется за пользователем, который запустил создание инстанса.
## Когда использовать
- подключаете домен к сервису впервые;
- нужна новая отдельная зона.
## Важное условие после создания
У регистратора домена нужно делегировать зону на:
- `ns3.ngcloud.ru`
- `185.247.187.83`
- `2a10:aa80:0:5::3`
- `ns4.ngcloud.ru`
- `81.22.46.43`
- `2a10:aa80:0:6::3`
Если этого не сделать, зона будет создана технически, но в интернете домен не начнет работать через эти DNS.
## Объяснение параметра `Типа зоны`
### `NATIVE`
Это основная (ведущая) зона в нашем сервисе.
Вы управляете записями здесь, и именно эта зона считается источником правды.
### `SLAVE`
Это копия зоны, которая подтягивает данные с внешнего DNS-сервера.
Такой режим нужен, когда истинный источник записей находится не в нашем сервисе, а на другом DNS.
## Что проверяет операция
- что такая зона еще не существует на целевых DNS;
- корректность входных параметров зоны;
- ограничения на служебные/запрещенные имена зон.'
params:
- id: 761
code: zoneName
data_type: string
required: true
regex: ^([a-z0-9-]+\.)+[a-z0-9-]+$
maxlength: 64
minlength: 1
descr: Имя зоны
sort: 20
- id: 762
code: zoneKind
data_type: string
required: true
default: NATIVE
value_list:
- NATIVE
- SLAVE
descr: Тип зоны
sort: 30
- id: 763
code: zoneMastersForSlave
data_type: string
required: false
descr: Использовать если выбран тип SLAVE. IP адреса в формате через пробел для настройки Master-серверов
man: Пример:
**8.8.8.8 8.8.4.4**
sort: 40
- id: 764
code: zoneRefresh
data_type: integer > 0
required: true
default: "86400"
minvalue: 600
descr: Время ожидания ответа вторичного DNS перед запросом SOA-записи с первичных серверов
sort: 50
- id: 765
code: zoneRetry
data_type: integer > 0
required: true
default: "7200"
minvalue: 600
descr: Время в течение которого сервер повторно попробует синхронизировать информацию с первичных DNS-серверов
sort: 60
- id: 766
code: zoneExpire
data_type: integer > 0
required: true
default: "3600000"
minvalue: 3600
descr: Время в течение которого вторичный DNS будет пытаться завершить синхронизацию зоны с первичным
sort: 70
- id: 767
code: zoneTTL
data_type: integer > 0
required: true
default: "86400"
minvalue: 600
descr: Время, в течение которого информация будет кешироваться другими DNS-серверами
sort: 80
- id: 768
code: resourceRealm
data_type: string
required: true
default: powerdns
value_list:
- powerdns
func: getAvailableResourceRealms
sort: 10
- name: create_record
id: 260
kind: subresource
action: create
subresource: record
man: '# Операция `create_record` (добавление одной записи)
## Что делает операция
`create_record` точечно добавляет одну DNS-запись в существующую зону.
Если аналогичная запись уже есть, итоговый набор дополняется в рамках логики типа/имени.
## Когда использовать
- нужно добавить одну новую запись без массовой переработки зоны;
- нужно быстро внести точечное изменение.
'
params:
- id: 777
code: recordName
data_type: string
required: true
regex: ^([a-zA-Z0-9\-_]+\.)*[a-zA-Z0-9\-_]+$|^(\d{1,3}\.){3}\d{1,3}$|^.+$
unique_scope: parent
maxlength: 64
minlength: 1
man: Имя зоны в конце проставляется автоматически
sort: 10
- id: 778
code: recordTTL
data_type: integer > 0
required: true
default: "3600"
maxvalue: 84000
minvalue: 30
man: Time-to-Leave записи. Раз в какое время запись будет обновлена
sort: 20
- id: 779
code: recordType
data_type: string
required: true
default: A
value_list:
- A
- AAAA
- CNAME
- MX
- SRV
- TXT
- LUA
- NS
- SSHFP
sort: 30
- id: 780
code: recordInput
data_type: string
required: true
man: Валидация производится только после запуска операции. Если при указанном типе будет указано некорректно значение, это будет описано в логе ошибки операции
sort: 40
- name: delete
id: 255
kind: instance
action: delete
man: '# Операция `delete` (удаление зоны)
## Что делает операция
`delete` удаляет DNS-зону целиком вместе со всеми записями.
## Когда использовать
- зона больше не нужна;
- домен выводится из эксплуатации в рамках сервиса.
## Важная логика
- удаляется вся зона, а не отдельные записи;
- перед удалением стоит проверить, что домен действительно не используется.
'
params: []
- name: delete_record
id: 261
kind: subresource
action: delete
subresource: record
man: '# Операция `delete_record` (удаление записей по имени)
## Что делает операция
`delete_record` удаляет все записи с указанным именем (`recordName`), независимо от типа (`A`, `TXT`, `CNAME` и т.д.).
## Когда использовать
- нужно полностью убрать конкретное имя из зоны;
- требуется быстро очистить все варианты записи для одного имени.
## Важная логика
- удаляются все типы записей для выбранного имени;
- если нужно удалить только один тип записи, лучше использовать `modify_record` с нужным целевым состоянием.
'
params:
- id: 781
code: recordName
data_type: string
required: true
- name: modify
id: 256
kind: instance
action: modify
man: '# Операция `modify` (массовое изменение записей зоны)
## Что делает операция
`modify` обновляет записи зоны целиком на основе переданного массива `records`.
Это операция "приведения к целевому состоянию": система берет входной набор и применяет его на DNS-серверах.
## Когда использовать
- нужно массово обновить зону;
- нужно заменить сразу несколько записей одним запуском;
- нужно синхронно привести зону к заранее подготовленному списку записей.
## Важная логика
- запись группируется по `(имя, тип, TTL)`;
- операция ориентирована на полное обновление набора, а не на "точечную мелкую правку".
Для точечных изменений одной записи обычно удобнее `create_record` или `modify_record`.
'
params:
- id: 769
code: records
data_type: array-map-fixed
required: true
sort: 10
sub_params:
- id: 86
code: recordName
data_type: string
required: true
default: ""
regex: ^([a-zA-Z0-9\-_]+\.)*[a-zA-Z0-9\-_]+$|^(\d{1,3}\.){3}\d{1,3}$|^.+$
man: Имя зоны в конце проставляется автоматически
is_modifiable: false
- id: 88
code: recordTTL
data_type: integer > 0
required: true
default: "3600"
man: Time-to-Leave записи. Раз в какое время запись будет обновлена
is_modifiable: false
- id: 85
code: recordType
data_type: string
required: true
default: A
value_list:
- A
- AAAA
- CNAME
- MX
- SRV
- TXT
- LUA
- NS
- SSHFP
is_modifiable: false
- id: 87
code: recordInput
data_type: string
required: true
default: ""
man: Валидация производится только после запуска операции. Если при указанном типе будет указано некорректно значение, это будет описано в логе ошибки операции
is_modifiable: false
- name: modify_record
id: 262
kind: subresource
action: modify
subresource: record
man: '# Операция `modify_record` (изменение конкретной записи)
## Что делает операция
`modify_record` заменяет записи с указанным именем одной новой записью заданного типа и значения.
## Когда использовать
- нужно исправить одну конкретную запись;
- нужно заменить старые значения записи на новое целевое значение.
## Важная логика
- существующие записи выбранного имени очищаются;
- затем добавляется одна новая запись с переданными параметрами.
'
params:
- id: 783
code: recordName
data_type: string
required: true
sort: 10
- id: 784
code: recordTTL
data_type: integer > 0
required: true
maxvalue: 84000
minvalue: 30
man: Time-to-Leave записи. Раз в какое время запись будет обновлена
sort: 20
- id: 785
code: recordType
data_type: string
required: true
value_list:
- A
- AAAA
- CNAME
- MX
- SRV
- TXT
- LUA
- NS
- SSHFP
sort: 30
- id: 786
code: recordInput
data_type: string
required: true
man: Валидация производится только после запуска операции. Если при указанном типе будет указано некорректно значение, это будет описано в логе ошибки операции
sort: 40
- name: reconcile
id: 259
kind: action
action: reconcile
man: '# Операция `reconcile` (актуализация состояния зоны)
## Что делает операция
`reconcile` подтягивает актуальное фактическое состояние DNS-зоны и синхронизирует его с данными инстанса.
Операция техническая: она нужна для выравнивания состояния, а не для бизнес-изменений записей.
## Когда использовать
- записи менялись вручную на DNS-серверах;
- нужно обновить схему/состояние инстанса в личном кабинете;
- нужно импортировать текущие записи в управляемое состояние.
## Важная логика
- актуализируется список записей в данных инстанса;
- стандартно ничего "нового" для клиента не добавляет и не удаляет само по себе, а приводит данные к реальности.
'
params: []