Запуск ПроAPI Защита в Docker¶
В этом руководстве описывается установка и запуск ПроAPI Защита с помощью Docker.
Ознакомление с тестовой версией
Для ознакомления с тестовой версией продукта отправьте запрос на presale@webmonitorx.ru.
В запросе необходимо передать следующие данные:
• ФИО
• Email
• Название компании
Требования¶
-
Установленный и настроенный Docker и Docker Compose.
-
Спецификация:
- OpenAPI 3.0 для REST API приложения, которое должно быть защищено с помощью ПроAPI Защита.
- GraphQL для GraphQL API приложения, которое должно быть защищено с помощью ПроAPI Защита.
Шаг 1. Создайте docker-compose.yml
файл¶
Чтобы развернуть ПроAPI Защита и соответствующую среду с помощью Docker Compose, сначала создайте docker-compose.yml со следующим содержимым:
для OpenAPI 3.0
version: '3.8'
networks:
api-firewall-network:
name: api-firewall-network
services:
api-firewall:
container_name: api-firewall
image: wmx-public.gitlab.yandexcloud.net:5050/wmx-private/api-firewall
restart: on-failure
volumes:
- <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>
environment:
APIFW_API_SPECS: <PATH_TO_MOUNTED_SPEC>
APIFW_URL: http://0.0.0.0:8088/
APIFW_SERVER_URL: <PROTECTED_APP_URL>
APIFW_REQUEST_VALIDATION: <REQUEST_VALIDATION_MODE>
APIFW_RESPONSE_VALIDATION: <RESPONSE_VALIDATION_MODE>
ports:
- "8088:8088"
stop_grace_period: 1s
networks:
- api-firewall-network
backend:
container_name: api-firewall-backend
image: kennethreitz/httpbin
restart: on-failure
ports:
- 80:80
stop_grace_period: 1s
networks:
- api-firewall-network
для GraphQL
version: '3.8'
networks:
api-firewall-network:
name: api-firewall-network
services:
api-firewall:
container_name: api-firewall
image: wmx-public.gitlab.yandexcloud.net:5050/wmx-private/api-firewall
restart: on-failure
volumes:
- <HOST_PATH_TO_SPEC>:<CONTAINER_PATH_TO_SPEC>
environment:
APIFW_MODE: graphql
APIFW_GRAPHQL_SCHEMA: <PATH_TO_MOUNTED_SPEC>
APIFW_URL: <API_FIREWALL_URL>
APIFW_SERVER_URL: <PROTECTED_APP_URL>
APIFW_GRAPHQL_REQUEST_VALIDATION: <REQUEST_VALIDATION_MODE>
APIFW_GRAPHQL_MAX_QUERY_COMPLEXITY: <MAX_QUERY_COMPLEXITY>
APIFW_GRAPHQL_MAX_QUERY_DEPTH: <MAX_QUERY_DEPTH>
APIFW_GRAPHQL_NODE_COUNT_LIMIT: <NODE_COUNT_LIMIT>
APIFW_GRAPHQL_INTROSPECTION: <ALLOW_INTROSPECTION_OR_NOT>
ports:
- "8088:8088"
stop_grace_period: 1s
networks:
- api-firewall-network
backend:
container_name: api-firewall-backend
image: <IMAGE_WITH_GRAPHQL_APP>
restart: on-failure
ports:
- <HOST_PORT>:<CONTAINER_PORT>
stop_grace_period: 1s
networks:
- api-firewall-network
Шаг 2. Настройте сеть Docker¶
При необходимости измените Сеть Docker конфигурация определена в docker-compose.yml → network
.
Предоставленный docker-compose.yml инструктирует Docker создать сеть api-firewall-network
и связать с ней контейнеры приложения и ПроAPI Защита.
Рекомендуется использовать отдельную сеть Docker, чтобы обеспечить взаимодействие контейнерного приложения и ПроAPI Защита без привязки вручную.
Шаг 3. Настройте приложение для защиты с помощью ПроAPI Защита¶
Измените конфигурацию контейнерного приложения, будет защищено ПроAPI Защита. Эта конфигурация определена в docker-compose.yml → services.backend
.
При настройке собственного приложения задайте только настройки, необходимые для правильного запуска контейнера приложения. Никакой специальной настройки ПроAPI Защита не требуется.
Шаг 4. Настройка ПроAPI Защита¶
Передайте конфигурацию ПроAPI Защита в docker-compose.yml → services.api-firewall
следующим образом:
С помощью services.api-firewall.volumes
смонтируйте спецификацию OpenAPI 3.0 в каталог контейнера ПроAPI Защита:
-
<HOST_PATH_TO_SPEC>
: путь к спецификации для вашего приложения, расположенный на хост-компьютере. Форматы файлов:- YAML и JSON (расширения файлов
.yaml
,.yml
,.json
) для OpenAPI 3.0. Например:/opt/my-api/openapi3/swagger.json
. - Для GraphQL формат файла не имеет значения, но обычно это
.graphql
илиgql
. Например:/opt/my-api/graphql/schema.graphql
.
- YAML и JSON (расширения файлов
-
<CONTAINER_PATH_TO_SPEC>
: путь к каталогу контейнера для монтирования спецификации OpenAPI 3.0 или GraphQL. Например:/api-firewall/resources/swagger.json
или/opt/my-api/graphql/schema.graphql
.
С помощью services.api-firewall.environment
установите общую конфигурацию ПроAPI Защита с помощью следующих переменных среды:
Переменная среды | Описание |
---|---|
APIFW_API_SPECS | Путь к спецификации OpenAPI 3.0. Существуют следующие способы указать путь:
Обязательная переменная. |
APIFW_URL | URL для ПроAPI Защита. Например: http://0.0.0.0:8088 / . Значение порта должно соответствовать порту контейнера, опубликованному на хосте.Если ПроAPI Защита прослушивает протокол HTTPS, пожалуйста, подключите сгенерированный сертификат SSL/ TLS и закрытый ключ к контейнеру и передайте контейнеру Настройки SSL/ TLS ПроAPI Защита. Значение по умолчанию - http://0.0.0.0:8282/ .Обязательная переменная. |
APIFW_SERVER_URL | URL приложения, описанного в смонтированной спецификации OpenAPI, которое должно быть защищено ПроAPI Защита. Например: http://backend:80 .Обязательная переменная. |
APIFW_REQUEST_VALIDATION | Режим ПроAPI Защита при проверке запросов, отправляемых на URL приложения:
Обязательная переменная. |
APIFW_RESPONSE_VALIDATION | Режим ПроAPI Защита при проверке ответов приложения на входящие запросы:
Обязательная переменная. |
APIFW_LOG_LEVEL | Уровень ведения логов ПроAPI Защита. Возможные значения:
DEBUG . Логи запросов и ответов, которые не соответствуют предоставленной схеме, имеют тип ОШИБКИ.Необязательная переменная. |
APIFW_CUSTOM_BLOCK_STATUS_CODE | Код состояния HTTP-ответа возвращается ПроAPI Защита, работающим в режиме "БЛОКИРОВКИ", если запрос или ответ не соответствуют схеме, представленной в смонтированной спецификации OpenAPI 3.0. Значение по умолчанию - 403 . Необязательная переменная. |
APIFW_ADD_VALIDATION_STATUS_HEADER (ЭКСПЕРИМЕНТАЛЬНЫЙ) | Возвращать ли заголовок Apifw-Validation-Status содержащий причину блокировки запроса в ответе на этот запрос. Значение может быть true или false . Значение по умолчанию - false .Необязательная переменная. |
APIFW_SERVER_DELETE_ACCEPT_ENCODING | Если для него установлено значение true , заголовок Accept-Encoding удаляется из прокси-запросов. Значение по умолчанию - false .Необязательная переменная. |
APIFW_LOG_FORMAT | Формат логов ПроAPI Защита. Значением может быть TEXT или JSON . Значение по умолчанию - TEXT .Необязательная переменная. |
APIFW_SHADOW_API_EXCLUDE_LIST (только если ПроAPI Защита работает в режиме LOG_ONLY как для запросов, так и для ответов) | Коды состояния HTTP-ответа указывает на то, что запрошенная конечная точка API, которая не включена в спецификацию, НЕ является теневой. Вы можете указать несколько кодов состояния, разделенных точкой с запятой (например, 404; 401 ). Значение по умолчанию - 404 .По умолчанию ПроAPI Защита, работающий в Режим "LOG_ONLY" как для запросов, так и для ответов помечает все конечные точки, которые не включены в спецификацию и возвращают код, отличный от 404 , как теневые. Необязательная переменная. |
APIFW_MODE | Устанавливает общий режим ПроAPI Защита. Возможные значения: PROXY (по умолчанию), graphql и API .Необязательная переменная. |
APIFW_PASS_OPTIONS | При значении true ПроAPI Защита разрешает запросы "OPTIONS" к эндпоинтам в спецификации, даже если метод "OPTIONS" не описан. Значение по умолчанию - false .Необязательная переменная. |
APIFW_SHADOW_API_UNKNOWN_PARAMETERS_DETECTION | Указывает, будут ли запросы идентифицированы как несоответствующие спецификации, если их параметры не совпадают с параметрами, определенными в спецификации OpenAPI. Значение по умолчанию - true .При запуске ПроAPI Защита в режиме API , эта переменная принимает другое имя APIFW_API_MODE_UNKNOWN_PARAMETERS_DETECTION .Необязательная переменная. |
APIFW_SERVER_REQUEST_HOST_HEADER | Устанавливает пользовательский заголовок Host для запросов, пересылаемых на серверную часть после проверки ПроAPI Защита.Необязательная переменная. |
APIFW_GRAPHQL_SCHEMA | Путь к файлу спецификации GraphQL, подключенному к контейнеру, например: /api-firewall/resources/schema.graphql .Обязательная переменная. |
APIFW_GRAPHQL_REQUEST_VALIDATION | Режим ПроAPI Защитапри проверке запросов, отправляемых на URL приложения::
APIFW_GRAPHQL_WS_CHECK_ORIGIN . Например, если в APIFW_GRAPHQL_INTROSPECTION установлен false и установлен режим LOG_ONLY , запросы самоанализа достигают внутреннего сервера, но ПроAPI Защита генерирует соответствующие логи ошибок.Обязательная переменная. |
APIFW_GRAPHQL_MAX_QUERY_COMPLEXITY | Определяет максимальное количество запросов к узлу, которые могут потребоваться для выполнения запроса. Установка значения 0 отключает проверку сложности. Значение по умолчанию равно 0 .Обязательная переменная. |
APIFW_GRAPHQL_MAX_QUERY_DEPTH | Указывает максимально допустимую глубину запроса GraphQL. Значение 0 означает, что проверка глубины запроса пропущена.Обязательная переменная. |
APIFW_GRAPHQL_NODE_COUNT_LIMIT | Устанавливает верхний предел для количества узлов в запросе. При значении 0 проверка ограничения количества узлов пропускается.Обязательная переменная. |
APIFW_GRAPHQL_MAX_ALIASES_NUM | SУстанавливает ограничение на количество псевдонимов, которые могут использоваться в документе GraphQL. Если для этой переменной установлено значение 0 , это означает, что количество псевдонимов, которые можно использовать, не ограничено.Обязательная переменная. |
APIFW_GRAPHQL_INTROSPECTION | Разрешает запросы самоанализа, которые раскрывают структуру вашей схемы GraphQL. Если установлено значение true , эти запросы разрешены.Обязательная переменная. |
APIFW_GRAPHQL_FIELD_DUPLICATION | Определяет, разрешать или предотвращать дублирование полей в документе GraphQL. Значение по умолчанию - false .Необязательная переменная. |
APIFW_GRAPHQL_BATCH_QUERY_LIMIT | Устанавливает ограничение на количество запросов, которые могут быть объединены в один запрос GraphQL. Если для этой переменной установлено значение 0 , это означает, что ограничений на количество выполняемых запросов нет.Необязательная переменная. |
С помощью services.api-firewall.ports
и services.api-firewall.networks
задайте порт контейнера ПроAPI Защита и подключите контейнер к созданной сети. Предоставленный docker-compose.yml инструктирует Docker запустить ПроAPI Защита, подключенный к api-firewall-network
сеть на порту 8088.
Шаг 5. Разверните настроенную среду¶
Чтобы создать и запустить настроенную среду, выполните следующую команду:
docker-compose up -d --force-recreate
Проверьте логи:
docker-compose logs -f
Шаг 6. Протестируйте работу ПроAPI Защита¶
Чтобы протестировать работу ПроAPI Защита, отправьте запрос, который не соответствует установленной спецификации Open API 3.0 или GraphQL, на адрес Docker-контейнера ПроAPI Защита. Например, вы можете передать строковое значение в параметре, для которого требуется целочисленное значение.
Для OpenAPI 3.0: если запрос не соответствует предоставленной схеме API, соответствующее сообщение об ошибке будет добавлено в логи Docker-контейнера ПроAPI Защита.
Для GraphQL: при APIFW_GRAPHQL_REQUEST_VALIDATION
значении BLOCK
ПроAPI Защита работает следующим образом:
- Если ПроAPI Защита разрешает запрос, он передает запрос через прокси на внутренний сервер.
- Если ПроAPI Защита не может проанализировать запрос, он отвечает ошибкой GraphQL с кодом состояния 500.
-
Если проверка ПроAPI Защита завершается неудачно, он не передает запрос через прокси на внутренний сервер, а отвечает клиенту кодом состояния 200 и ошибкой GraphQL в ответ.
-
Если запрос не соответствует предоставленной схеме API, ПроAPI Защита возвращает следующий ответ:
{ "errors": [ { "message":"invalid query" } ] }
Соответствующее сообщение об ошибке добавляется в логи Docker-контейнера ПроAPI Защита, например, в формате JSON:{ "errors": [ { "message": "field: name not defined on type: Query", "path": [ "query", "name" ] } ] }
В сценариях, когда несколько полей в запросе недопустимы, будет сгенерировано только одно сообщение об ошибке.Шаг 7. Включите трафик через ПроAPI Защита¶
Чтобы завершить настройку ПроAPI Защита, пожалуйста, включите входящий трафик на ПроAPI Защита, обновив конфигурацию схемы развертывания вашего приложения. Например, для этого потребуется обновить настройки NGINX или балансировщика нагрузки.
Остановка развернутой среды¶
Чтобы остановить среду, развернутую с помощью Docker Compose, выполните следующую команду:
docker-compose down