Перейти к содержанию

Запуск ПроAPI Защита в Docker

В этом руководстве описывается установка и запуск ПроAPI Защита с помощью Docker.

Требования

  • Установленный и настроенный 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.ymlnetwork.

Предоставленный docker-compose.yml инструктирует Docker создать сеть api-firewall-network и связать с ней контейнеры приложения и ПроAPI Защита.

Рекомендуется использовать отдельную сеть Docker, чтобы обеспечить взаимодействие контейнерного приложения и ПроAPI Защита без привязки вручную.

Шаг 3. Настройте приложение для защиты с помощью ПроAPI Защита

Измените конфигурацию контейнерного приложения, будет защищено ПроAPI Защита. Эта конфигурация определена в docker-compose.ymlservices.backend.

При настройке собственного приложения задайте только настройки, необходимые для правильного запуска контейнера приложения. Никакой специальной настройки ПроAPI Защита не требуется.

Шаг 4. Настройка ПроAPI Защита

Передайте конфигурацию ПроAPI Защита в docker-compose.ymlservices.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.
  • <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. Существуют следующие способы указать путь:
  • Путь к файлу спецификации, подключенному к контейнеру, например: /api-firewall/resources/swagger.json. При запуске контейнера смонтируйте этот файл с помощью -v <HOST_PATH_TO_SPEC>:Опция <CONTAINER_PATH_TO_SPEC>.
  • URL-адрес файла спецификации, например: https://example.com/swagger.json. При запуске контейнера опустите -v <HOST_PATH_TO_SPEC>:Опция <CONTAINER_PATH_TO_SPEC>.

Обязательная переменная.
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 приложения:
  • BLOCK для блокирования и регистрации запросов, которые не соответствуют схеме, представленной в смонтированной спецификации OpenAPI 3.0 (на заблокированные запросы будет возвращен ответ 403 Forbidden). Логи отправляются в службы настройки STDOUT и STDERR.
  • LOG_ONLY регистрировать, но не блокировать запросы, которые не соответствуют схеме, представленной в смонтированной спецификации OpenAPI 3.0. Логи отправляются в службы настройки STDOUT и STDERR.
  • DISABLE для отключения проверки запроса.

  • Обязательная переменная.
APIFW_RESPONSE_VALIDATION Режим ПроAPI Защита при проверке ответов приложения на входящие запросы:
  • BLOCK для блокировки и регистрации запроса, если ответ приложения на этот запрос не соответствует схеме, представленной в подключенной спецификации OpenAPI 3.0. Этот запрос будет перенаправлен на URL приложения, но клиент получит ответ "403 Запрещено". Логи отправляются в службы настройки STDOUT и STDERR.
  • LOG_ONLY для регистрации, но не блокирования запроса, если ответ приложения на этот запрос не соответствует схеме, представленной в подключенной спецификации OpenAPI 3.0. Логи отправляются в службы настройки STDOUT и STDERR.
  • DISABLE для отключения проверки запроса.

Обязательная переменная.
APIFW_LOG_LEVEL Уровень ведения логов ПроAPI Защита. Возможные значения:
  • DEBUG для регистрации событий любого типа (ИНФОРМАЦИЯ, ОШИБКА, ПРЕДУПРЕЖДЕНИЕ и ОТЛАДКА).
  • INFO для регистрации событий типов INFO, WARNING и ERROR.
  • WARNING для регистрации событий типов WARNING и ERROR.
  • ERROR для регистрации событий только типа ERROR.
  • TRACE для регистрации входящих запросов и ответов Про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 приложения::
  • BLOCK блокирует и регистрирует запросы, не соответствующие подключенной схеме GraphQL, возвращая 403 Forbidden. Логи отправляются are sent to the STDOUT and STDERR Docker services.
  • LOG_ONLY регистрирует (но не блокирует) несоответствующие запросы.
  • DISABLE отключает проверку запроса.
Эта переменная влияет на все остальные параметры, кроме 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