Как установить и настроить Kong Gateway на VPS

MAATRIX

Когда микросервисов становится больше трёх-четырёх, каждый со своей аутентификацией, лимитами и логами, поддерживать это вручную в каждом сервисе — терять время на дублирование кода. Kong Gateway решает задачу иначе: аутентификация, rate limiting и логирование выносятся на уровень единого API-шлюза перед сервисами, а сами сервисы занимаются только бизнес-логикой. Разберём установку Kong на VPS через Docker Compose — от базы данных до первого маршрута с плагинами.

Что такое Kong Gateway и зачем он нужен

Kong — это API-шлюз (API gateway) на базе Nginx и OpenResty, который стоит перед вашими микросервисами и принимает на себя весь входящий трафик. Вместо того чтобы каждый сервис сам проверял токены, считал лимиты запросов и писал логи в едином формате, эту работу берёт на себя Kong через систему плагинов.

Ключевые сущности в Kong — это Service, Route, Consumer и Plugin. Service описывает, куда проксировать запрос (адрес вашего бэкенда). Route определяет, по какому пути или домену запрос попадает в этот Service. Consumer — это клиент API (пользователь, приложение, партнёр), которому можно выдать ключи или токены. Plugin — модуль, который вешается на Service, Route или Consumer и добавляет функциональность: проверку API-ключа, ограничение частоты запросов, логирование в внешнюю систему, трансформацию заголовков и десятки других сценариев из коробки.

Честно про ограничения: Kong — это дополнительный компонент инфраструктуры со своей базой данных, своим Admin API и своей кривой обучения. Для одного-двух сервисов за глаза хватит обычного Nginx или Traefik с базовой авторизацией — Kong там будет избыточен. Гейтвей окупается, когда сервисов много, к ним обращаются разные потребители с разными правами, а лимиты и аутентификацию нужно менять на лету через API, не трогая код самих сервисов.

Подготовка VPS и запуск PostgreSQL

Kong с PostgreSQL под умеренной нагрузкой комфортно живёт на 2 ядрах и 4 ГБ RAM; для прод-нагрузки с десятками сервисов закладывайте больше — реальные цифры зависят от количества плагинов и трафика, ориентируйтесь на мониторинг после запуска. Установите Docker, если его ещё нет:

curl -fsSL https://get.docker.com | sh
systemctl enable --now docker

Локацию сервера имеет смысл выбирать по географии клиентов вашего API: RU — для аудитории в России и близких странах, UK — для Европы, US — для сервисов, завязанных на американскую инфраструктуру. У MAATRIX доступны все три локации с оплатой из России картой, СБП или криптой, включая токен MAAT, так что для гейтвея не придётся искать иностранную карту.

Kong классической сборки (не DB-less) хранит конфигурацию в PostgreSQL. Создайте сеть и запустите базу отдельным контейнером:

docker network create kong-net

docker run -d --name kong-database \
  --network kong-net \
  -e POSTGRES_USER=kong \
  -e POSTGRES_DB=kong \
  -e POSTGRES_PASSWORD=change-me-strong-password \
  -v kong-pg-data:/var/lib/postgresql/data \
  postgres:16

Пароль обязательно смените на свой — в проде его стоит хранить не в открытом виде в команде запуска, а через переменные окружения или Docker secrets (об этом — в статье про управление паролями через Docker secrets).

Установка Kong Gateway через Docker Compose

Прежде чем запускать сам Kong, базу нужно подготовить миграциями — это создание таблиц и структуры под конкретную версию Kong. Соберите всё в compose.yaml:

services:
  kong-migrations:
    image: kong:3.7
    command: kong migrations bootstrap
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: change-me-strong-password
    networks:
      - kong-net
    restart: on-failure

  kong:
    image: kong:3.7
    restart: unless-stopped
    depends_on:
      - kong-migrations
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: kong-database
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: change-me-strong-password
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
      KONG_ADMIN_LISTEN: 127.0.0.1:8001
      KONG_PROXY_LISTEN: 0.0.0.0:8000
    ports:
      - "8000:8000"
      - "127.0.0.1:8001:8001"
    networks:
      - kong-net

networks:
  kong-net:
    external: true

Обратите внимание на KONG_ADMIN_LISTEN — Admin API сразу привязан к 127.0.0.1, чтобы не торчать наружу без защиты (подробнее об этом ниже, в разделе про безопасность). Порт 8000 — это proxy-порт, на который приходит клиентский трафик и который Kong дальше маршрутизирует на ваши сервисы. Используйте актуальный тег образа с Docker Hub — на момент написания статьи ветка 3.x стабильна, но для новых установок стоит свериться с текущей версией и changelog перед выбором тега.

Запустите стек и проверьте, что Kong поднялся:

docker compose up -d
curl -i http://127.0.0.1:8001/

Ответ 200 OK с JSON, где есть поле version, означает, что Kong работает и Admin API отвечает.

Первый сервис и маршрут через Admin API

Вся конфигурация Kong в классическом режиме делается через Admin API — REST-интерфейс на порту 8001. Добавим Service, который указывает на реальный бэкенд, и Route, который решает, какие запросы к нему направлять.

Создайте Service:

curl -i -X POST http://127.0.0.1:8001/services \
  --data name=my-api \
  --data url=http://backend-app:3000

Здесь url — это адрес вашего бэкенда: контейнера в той же сети Docker или внешнего хоста, доступного с VPS. Теперь привяжите к Service маршрут:

curl -i -X POST http://127.0.0.1:8001/services/my-api/routes \
  --data name=my-api-route \
  --data paths[]=/api/v1

Проверьте, что маршрутизация работает — запрос на proxy-порт с путём /api/v1 должен уйти на бэкенд:

curl -i http://127.0.0.1:8000/api/v1/

Если бэкенд ответил, а не Kong вернул 404, маршрут настроен верно. Такой же результат получится через файл декларативной конфигурации в DB-less режиме (без PostgreSQL, с конфигом в YAML), но там Admin API становится преимущественно read-only и не годится для динамического управления сервисами через CRUD-запросы — для команды, которая хочет менять маршруты и плагины на лету через API, классический режим с базой данных удобнее.

Плагины: аутентификация, лимиты, логирование

Плагины — то, ради чего Kong обычно и выбирают. Подключим три типовых сценария.

Аутентификация по API-ключу (key-auth). Включаем плагин на Route:

curl -i -X POST http://127.0.0.1:8001/routes/my-api-route/plugins \
  --data name=key-auth

Создаём потребителя API и выдаём ему ключ:

curl -i -X POST http://127.0.0.1:8001/consumers \
  --data username=partner-1

curl -i -X POST http://127.0.0.1:8001/consumers/partner-1/key-auth \
  --data key=my-secret-api-key

После этого запросы к маршруту без заголовка apikey: my-secret-api-key будут получать 401. Для более серьёзных сценариев вместо key-auth используют плагин jwt — он проверяет подписанные JWT-токены без обращения к базе на каждый запрос.

Ограничение частоты запросов (rate-limiting) защищает бэкенд от перегрузки и злоупотреблений:

curl -i -X POST http://127.0.0.1:8001/services/my-api/plugins \
  --data name=rate-limiting \
  --data config.minute=60 \
  --data config.policy=local

config.policy=local хранит счётчики в памяти самого узла Kong — этого достаточно для одного инстанса. Если Kong будет работать в нескольких экземплярах за балансировщиком, счётчики нужно синхронизировать через policy=redis, иначе каждый узел будет считать лимит независимо и реальный лимит окажется в разы выше заданного.

Логирование запросов настраивается плагином file-log (простой вариант, пишет в файл на диске) или http-log/tcp-log для отправки во внешнюю систему сбора логов:

curl -i -X POST http://127.0.0.1:8001/services/my-api/plugins \
  --data name=file-log \
  --data config.path=/tmp/kong-access.log

Каждый плагин можно навесить на Service (действует на все маршруты сервиса), на Route (только на конкретный маршрут) или на Consumer (только на запросы этого клиента) — порядок и уровень применения стоит продумать заранее, чтобы не плодить дублирующиеся правила.

Безопасность Admin API и HTTPS

Admin API Kong — это полный контроль над гейтвеем: через него можно создавать сервисы, менять маршруты и снимать плагины аутентификации. Если он торчит в интернет без защиты, это открытая дверь в вашу инфраструктуру. В конфиге выше KONG_ADMIN_LISTEN уже привязан к 127.0.0.1, и это должно быть правилом, а не исключением: управляйте Kong либо с самого сервера, либо через SSH-туннель:

ssh -L 8001:127.0.0.1:8001 user@your-vps-ip

После такого туннеля Admin API доступен на localhost:8001 вашей локальной машины, а извне порт не виден вообще. Дополнительно закройте порт файрволом на всякий случай:

ufw deny 8001

Для HTTPS на proxy-порту у Kong есть встроенная поддержка TLS-сертификатов через объект certificates в Admin API, но проще и привычнее для большинства команд поставить перед Kong терминирующий TLS-прокси — Nginx или Traefik — и настроить автообновление сертификатов Let's Encrypt на нём, оставив Kong работать по HTTP внутри Docker-сети. Как это сделать, подробно разобрано в статье про установку и настройку Let's Encrypt SSL на VPS; альтернативный вариант с автоматическим SSL по меткам контейнеров — Traefik как обратный прокси, который можно поставить перед Kong тем же способом, что и перед обычными сервисами.

Частые вопросы