Домены

Домены - основной объект в системе для управления услугой 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. При включении функции доступ к соответствующему разделу сайта будет только у обладателей подписанных ссылок. Генерация ссылок осуществляется клиентом.

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

Ниже представлены рекомендации по управлению доменами.

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

1. создать домен
2. загрузить/выпустить сертификат при необходимости
3. добавить список locations при необходимости
4. добавить waf при необходимости
5. включить услугу CDN

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

1. внести правки по всем интересующим пользователя настройкам
2. вызвать API метод обновления домена
3. внести изменения во второстепенные объекты (вызывать метод обновления домена не требуется)

API методы

Домены

• test_create_domain
• create_domain
• get_domain
• get_domains
• update_domain
• delete_domain
• test_enable_cdn_for_domain
• enable_cdn_for_domain
• disable_cdn_for_domain
• refill_cache
• clear_cache
• get_domain_stats

Сертификаты

• isssue_ssl_cert
• test_upload_ssl_cert
• upload_ssl_cert
• get_ssl_cert

Locations

• create_location
• get_location
• get_locations
• update_location
• delete_location

WAF

• create_waf
• get_waf
• update_waf
• delete_waf
• get_waf_logs