Запуск Про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 со следующим содержимым:

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

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.

• <CONTAINER_PATH_TO_SPEC>: путь к каталогу контейнера для монтирования спецификации OpenAPI 3.0 или GraphQL. Например: /api-firewall/resources/swagger.json или /opt/my-api/graphql/schema.graphql.

С помощью services.api-firewall.environment установите общую конфигурацию ПроAPI Защита с помощью следующих переменных среды:

С помощью 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