Версия: Next

Домены

Домены - основной объект в системе для управления услугой CDN для сайтов.

Управление доменами

Статусы домена

Для определения текущего состояния домена используется поле status объекта (domain.status).

Возможные значения:

OK (CDN для домена включен)
DISABLED (CDN для домена выключен)
BLOCKED (домена заблокирован)
CHECKING_NS_LIST (проводится проверка делегации домена)
DOMAIN_NOT_DELEGATED (домен не делегирован)
CREATING_SSL_CERT (выпускается сертификат для домена)
SSL_CERT_CREATING_ERROR (ошибка выпуска сертификата для домена)
UPDATING_DNS_RECORDS (проводится обновление записей на PDNS)
UPDATING_DNS_RECORDS_ERROR (ошибка обновления записей на PDNS)

Создание домена

Создание домена происходит синхронно, в системе создается объект domain.

примечание

Сразу после создания домена услуга CDN неактивна. Статус домена - DISABLED.

Для каждого домена генерируется поле cdn_domain. Это доменное имя, с которого будет раздаваться статический контент из кэширующих серверов. Если тип создаваемого домена cname, то для объекта также генерируется и заполняется поле cname_url. Это доменное имя, которое при необходимости можно указать в качестве контента в CNAME запись в DNS клиента.

Обновление домена

Обновление домена происходит синхронно, в системе обновляется объект domain. Для изменений используются доступные поля соответствующего API метода.

Работа с TLS/SSL сертификатами

После создания домена пользователь может автоматически выпустить бесплатный сертификат от Let's Encrypt либо загрузить свой. Для выпуска сертификата используется метод issue_cert. При этом создается задача с типом ISSUE_CERT. Бесплатный сертификат будет обновляться автоматически каждые 60 дней. Автоматическое обновление можно отключить на уровне приложения. Для загрузки пользовательского сертификата использовать метод upload_ssl_cert. Данный метод работает синхронно. Допускается обновление/загрузка сертификата как при выключенной, так и при включенной услуге CDN.

Загрузка сертификата для доменов с типом `delegated`

При загрузке сертификата для домена типа delegated выполняется проверка того, что сертификат выпущен для доменного имени domain.name, указанного при создании объекта domain. Поле API-метода domain_name в валидации не участвует.

к сведению

Значение поля domain.cdn_domain для домена типа delegated всегда равно значению поля domain.name.

Пример использования:

cоздать домен с именем "example.com" и типом delegated
загрузить сертификат
среди списка доменных имен загружаемого сертификата (Subject Alternative Name) обязательно должно быть "example.com" либо "*.example.com"
включить CDN для домена
после обновления кэша DNS-серверов шифрование запросов при обращении к "example.com" будет происходить с помощью загруженного сертификата

Загрузка сертификата для доменов с типом `cname`

Для загрузки сертификата для домена типа cname необходимо указать желаемое доменное имя в поле domain_name. Это доменное имя, при обращении к которому запросы будут проходить через серверы CDN. Оно не может совпадать с domain.name.

warning

После успешной загрузки сертификата у объекта domain изменяется значение поля cdn_domain.

Пример использования:

cоздать домен с именем "example.com" и типом cname
для домена автоматически будет заполнено поле cname_url, например, "d121.static-clients.arviol.com"
загрузить сертификат, указав в поле domain_name доменное имя, с которого планируется раздача статики сайта, например, "cdn.example.com"
среди списка доменных имен загружаемого сертификата (Subject Alternative Name) обязательно должно быть "cdn.example.com" либо "*.example.com"
после успешной загрузки сертификата у объекта domain поле cdn_domain изменится на "cdn.example.com"
включить CDN для домена
в настройках DNS-хостинга добавить CNAME-запись: name="cdn.example.com", data="d121.static-clients.arviol.com"
после обновления кэша DNS-серверов запросы по домену "cdn.example.com" будут отправлены через серверы CDN

Включение услуги CDN для домена

Для включения услуги необходимо использовать API метод enable_cdn_for_domain. При успешном выполнении метода в системе создается задача ENABLE_CDN. Если услуга уже включена для данного домена, то метод вернет соответствующий код ошибки. Одним из этапов включения услуги является выпуск нового SSL/TLS сертификата или обновление текущего, если он просрочен. Если перед включением для домена был загружен пользовательский сертификат, то никаких действий с ним не производится. После успешного выполнения задачи домен получает статус OK - услуга активна. Доменное имя для получения статики из кэш-серверов: cdn_domain.

Выключение услуги CDN для домена

Для выключения услуги необходимо использовать API метод disable_cdn_for_domain. При успешном выполнении метода в системе создается задача DISABLE_CDN. Если услуга уже выключена для данного домена, то метод вернет соответствующий код ошибки. После успешного выполнения задачи домен получает статус DISABLED - услуга выключена.

WAF

Объекты waf являются второстепенными по отношению к доменам. Для управления waf реализован набор API методов.

Структура объекта:

{
    "id": 1,
    "domain_id": 1,
    "sec_rule_engine": "detection_only",
    "paranoia_level": 1,
    "executing_paranoia_level": 1,
    "critical_anomaly_score": 5,
    "error_anomaly_score": 4,
    "warning_anomaly_score": 3,
    "notice_anomaly_score": 2,
    "in_score_threshold": 5,
    "out_score_threshold": 4,
    "sampling_percentage": 100
}

Выгрузка логов WAF

Для получения логов WAF по домену доступен API-метод get_waf_logs.

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

В результате метод возвращает объект, который содержит total_count - общее количество записей в хранилище по указанным датам и logs - массив json-записей c данными об ошибке.

примечание

Значение total_count не соответствует длине массива logs.

Например, если всего в хранилище 2000 записей (ids=1-2000) по указанными датам, а в запросе указан limit = 100, offset = 100, то в ответе получим: total_count = 2000, logs.length = 100 (id=101-200).

Locations

Для каждого домена возможно добавить до 10 второстепенных объектов locations. Для управления locations реализован набор API методов.

Структура объекта и значения полей по умолчанию:

{
    "id": 1,
    "domain_id": 1,
    "name": "/static/",
    "type": "matching",
    "headers": [
        {
            "key": "Accept-Encoding",
            "value": "gzip, deflate, br"
        }
    ],
    "request_headers": [
        {
            "key": "X-Origin-Routing",
            "value": "beta"
        }
    ],
    "cors_headers": {
        "access_control_allow_origin": [
            "*"
        ],
        "access_control_expose_headers": [
            "*"
        ],
        "access_control_max_age": 600,
        "access_control_allow_credentials": true,
        "access_control_allow_methods": [
            "DELETE"
        ],
        "access_control_allow_headers": [
            "*"
        ]
    }
}

headers — массив заголовков ответа, добавляемых CDN при возврате контента пользователю. Каждый элемент задается парой key и value. Подходит для настройки кэширования, внедрения политик безопасности или передачи служебных меток.

request_headers — массив заголовков, которые CDN проксирует на origin при обращении за оригинальным ресурсом. Каждый элемент задается парой key и value. Используется для передачи дополнительных признаков маршрутизации, параметров A/B-тестов и другой служебной информации backend-системам.

Ограничение доступа

Для доменов доступна функция ограничения доступа, за которую отвечает объект domain.access_params. Структура объекта:

{
    "disallowed_country_codes": [
        "RU",
        "BY"
    ]
}

В поле disallowed_country_codes указывается список кодов стран, при запросах из которых клиент получит ответ с кодом ошибки 403 Forbidden. Коды стран должны соответствовать двухбуквенным обозначениям по ISO 3166 Alpha-2.

Подписанные ссылки

За включение и выключение функции ограничения доступа к разделам сайта по подписанным ссылкам отвечают поля signed_url_enabled и signed_url_key объектов location. Включить и выключить функцию можно обновив объект location. При включении функции доступ к соответствующему разделу сайта будет только у обладателей подписанных ссылок. Генерация ссылок осуществляется клиентом.

Домены

Управление доменами

Статусы домена

Создание домена

Обновление домена

Работа с TLS/SSL сертификатами

Загрузка сертификата для доменов с типом `delegated`

Загрузка сертификата для доменов с типом `cname`

Включение услуги CDN для домена

Выключение услуги CDN для домена

WAF

Выгрузка логов WAF

Locations

Ограничение доступа

Подписанные ссылки

Рекомендуемые сценарии

Первичное включение:

Обновление домена:

API методы

Домены

Сертификаты

Locations

WAF

Управление доменами​

Статусы домена​

Создание домена​

Обновление домена​

Работа с TLS/SSL сертификатами​

Загрузка сертификата для доменов с типом delegated​

Загрузка сертификата для доменов с типом cname​

Включение услуги CDN для домена​

Выключение услуги CDN для домена​

WAF​

Выгрузка логов WAF​

Locations​

Ограничение доступа​

Подписанные ссылки​

Рекомендуемые сценарии​

Первичное включение:​

Обновление домена:​

API методы​

Домены​

Сертификаты​

Locations​

WAF​

Управление доменами

Статусы домена

Создание домена

Обновление домена

Работа с TLS/SSL сертификатами

Загрузка сертификата для доменов с типом `delegated`

Загрузка сертификата для доменов с типом `cname`

Включение услуги CDN для домена

Выключение услуги CDN для домена

WAF

Выгрузка логов WAF

Locations

Ограничение доступа

Подписанные ссылки

Рекомендуемые сценарии

Первичное включение:

Обновление домена:

API методы

Домены

Сертификаты

Locations

WAF