Пользовательский домен для AWS API Gateway

Быстрые ссылки

• Запрос сертификата в ACM и привязка к API Gateway

• Связывание DNS с API Gateway

AWS API Gateway отлично подходит как фронтенд для Lambda-функций и других сервисов AWS. По умолчанию конечная точка использует поддомен amazonaws.com, что неудобно для пользователей. В этой статье пошагово показано, как получить пользовательский домен с HTTPS и направить на него ваш API.

Что понадобится

• Права на создание сертификатов в AWS Certificate Manager (ACM).
• Доступ к управлению DNS для домена (Route 53 или сторонний регистратор).
• Права на управление API в API Gateway.

Важно: вы должны владеть доменом или иметь право управлять его DNS-записями.

Запрос сертификата в ACM и привязка к API Gateway

Выберите поддомен, который будет использоваться для API, например:

api.example.com

Нужно выполнить две операции: запросить SSL-сертификат в ACM и настроить DNS для указания на API Gateway.

1. Войдите в консоль AWS и откройте AWS Certificate Manager.
2. Нажмите «Request a certificate» и выберите тип “Public” (публичный сертификат).
3. Введите домен(ы), которые хотите защитить. Обычно достаточно одного поддомена.

Валидация домена доступна двумя способами:

• DNS-валидация — нужно добавить CNAME-запись в DNS. Быстро и управляемо через Route 53.
• Email-валидация — AWS отправит письмо на контактный email WHOIS. Не работает при скрытой WHOIS-информации.

DNS-вариант проще и надежнее. На следующем экране ACM выдаст имя и значение CNAME-записи, которые нужно добавить в DNS. Если вы используете Route 53, можно нажать “Create Record In Route 53” — AWS создаст запись автоматически.

После добавления записи подождите: у провайдеров DNS распространение занимает от нескольких минут до нескольких часов. После успешной валидации статус сертификата в ACM станет “Issued”.

Далее перейдите в консоль API Gateway и откройте раздел Custom Domain Names. Создайте новый пользовательский домен, укажите имя домена и выберите сертификат, который вы только что выпустили. Убедитесь, что выбран правильный тип API (REST API, HTTP API или WebSocket).

Создайте домен. В списке появится новая запись. Нажмите “Edit” для добавления сопоставления пути (path mapping) — это связывает поддомен и путь с определённым API и стадией. Например:

api.example.com/v1/

Рекомендуем создавать отдельные пути для разных стадий: разработка для $default или dev, и продуктив для prod.

После создания скопируйте значение Target Domain Name — это доменное имя, на которое будет указывать ваша DNS-запись. Это не URL API, а целевой домен для DNS.

Связывание DNS с API Gateway

После настройки в API Gateway ваш домен настроен внутри AWS, но внешние запросы не попадут на него, пока DNS не укажет на целевой домен.

Для сторонних регистраторов используйте CNAME-запись. CNAME указывает один домен на другой и требует дополнительного DNS lookup.

Пример:

api.example.com CNAME api-id.execute-api.region.amazonaws.com/stage

Если используете Route 53, сделайте A-запись в режиме “Alias” и укажите API Gateway из списка — это выполняет перенаправление в один lookup и управляется внутри AWS.

После внесения записей подождите распространения. Когда DNS обновится, ваш API станет доступен по пользовательскому домену. Обязательно используйте HTTPS — API Gateway не примет незащищённые соединения.

Проверка и отладка

Если API недоступен после внесения записей:

• Проверьте, что в ACM сертификат имеет статус “Issued”.
• Убедитесь, что DNS-запись указывает на значение Target Domain Name, а не на API endpoint напрямую.
• Используйте dig/nslookup для проверки CNAME/A Alias:

dig +short CNAME api.example.com

• Если используете Route 53 Alias, проверьте, что выбрана правильная региональная конфигурация API (регион и тип API).
• Убедитесь, что в том же Custom Domain настроен правильный Path Mapping на нужную стадию API.
• Проверьте, что вы обращаетесь по HTTPS.

Частые ошибки и когда это не работает

• Email-валидация не проходит из‑за скрытой WHOIS-информации. Используйте DNS-валидацию.
• Попытка поставить CNAME для корневого домена (example.com) — CNAME запрещён в корне. В этом случае используйте Route 53 Alias или перенаправление с www.
• Неправильный регион API или выбор типа API при создании Custom Domain в консоли.

Альтернативные подходы

• Использовать CDN (CloudFront) перед API Gateway: позволяет добавить дополнительные политики кеширования, WAF и управление гео‑трафиком.
• Если домен регистрирован вне AWS, добавить Route 53 только для нужных записей (делегирование) и использовать Alias.

Пошаговый чек-лист перед релизом

• Сертификат в ACM выдан (Issued).
• Custom Domain создан в API Gateway и привязан сертификат.
• Path Mapping настроен для нужной стадии API.
• DNS-запись (CNAME или Alias A) добавлена и указывает на Target Domain Name.
• HTTPS доступен и проверен curl/браузером.
• Документированы имена записей и сроки обновления.

Роли и обязанности

DevOps / Инженер по платформе:

• Запрос сертификата в ACM.
• Создание Custom Domain в API Gateway.
• Настройка Path Mapping.

DNS-администратор:

• Добавление CNAME у стороннего регистратора или Alias A в Route 53.
• Контроль TTL и времени распространения.

Владелец продукта:

• Утверждение доменного имени и стратегий версионирования API (путь для dev/prod).

Модель принятия решений

Если DNS в вашей организации управляется вне AWS, и вы не хотите менять регистратора:

• Используйте CNAME для поддоменов.
• Для корневого домена используйте перенаправление на поддомен или настройте Alias через Route 53 (делегирование зоны).

flowchart TD
  A[Нужен пользовательский домен?] --> B{Домен в Route 53?}
  B -- Да --> C[Использовать Alias A к API Gateway]
  B -- Нет --> D{Это корневой домен?}
  D -- Да --> E[Делегировать зону в Route 53 или использовать перенаправление]
  D -- Нет --> F[Создать CNAME к Target Domain Name]
  C --> G[Проверить HTTPS и Path Mapping]
  E --> G
  F --> G

Факт-бокс: ключевые моменты

• Валидация сертификата: DNS или Email. DNS предпочтительнее.
• Route 53 Alias позволяет избежать дополнительного DNS lookup.
• CNAME нельзя использовать для корневого домена.
• Path Mapping связывает поддомен/путь с конкретной стадией API.

Критерии приёмки

• Домен отвечает по HTTPS и возвращает корректный ответ API для нужной стадии.
• Сертификат действителен и выдан ACM (Issued).
• DNS-запись указывает на Target Domain Name.

Глоссарий (в 1 строке)

• ACM: AWS Certificate Manager, сервис управления SSL/TLS сертификатами.
• Target Domain Name: имя, которое API Gateway предоставляет для привязки из DNS.
• Alias: специальная A-запись в Route 53, указывающая на ресурсы AWS.

Часто задаваемые вопросы

Какой способ валидации сертификата выбрать?

DNS-валидация надёжнее и автоматизируемая в Route 53; email-валидация может не работать при скрытой WHOIS-информации.

Можно ли использовать CNAME для корневого домена example.com?

Нет, CNAME запрещён в корне. Используйте Alias в Route 53 или перенаправление на поддомен.

Почему браузер показывает ошибку сертификата?

Возможные причины: сертификат не выдан, DNS указывает не на Target Domain Name, либо вы обращаетесь по HTTP вместо HTTPS.

Краткое резюме:

1. Выпустите сертификат в ACM и подтвердите домен через DNS.
2. Создайте Custom Domain в API Gateway и установите Path Mapping.
3. Добавьте в DNS CNAME (сторонний регистратор) или Alias A (Route 53) на Target Domain Name.
4. Проверьте HTTPS и корректность ответов API.

Важно: документируйте все внесённые записи и сохраняйте копию Target Domain Name для будущих изменений.