Kong Gateway на Ubuntu 24.04: пошаговая установка

MAATRIX

Когда за одним доменом прячется десяток микросервисов, каждый со своей аутентификацией, лимитами и логированием, держать это вручную в nginx.conf становится больно: любое изменение — правка конфига руками и перезапуск. Kong Gateway решает эту задачу как отдельный слой перед вашими сервисами — маршрутизация, авторизация, rate limiting и логи настраиваются через API или админку, без единой правки конфигов на лету. Ниже — установка Kong на чистый Ubuntu 24.04 с PostgreSQL, без Kubernetes и лишней магии, шаг за шагом.

Что такое Kong Gateway и когда он нужен

Kong — это API-шлюз (API gateway) на базе nginx и OpenResty (Lua-надстройка над nginx). По сути это программируемый reverse proxy: запросы клиентов сначала попадают в Kong, а он уже решает, куда их отправить, кого пустить, а кого остановить лимитом.

Типичные причины поставить Kong перед микросервисами:

• Единая точка входа. Клиенты стучатся в один домен, Kong маршрутизирует запросы по внутренним сервисам через services и routes.
• Аутентификация в одном месте. Плагины key-auth, JWT, OAuth2, LDAP — не нужно реализовывать проверку токена в каждом сервисе отдельно.
• Rate limiting и защита от перегрузки. Ограничения по IP, ключу API или потребителю задаются декларативно.
• Логирование и наблюдаемость. Плагины http-log, file-log, а также экспорт метрик в Prometheus — единая точка для сбора данных о трафике.
• Трансформации запросов/ответов. Добавить заголовок, переписать путь, сжать ответ — без изменения кода бэкенда.

Если у вас один монолит без внутренних сервисов — Kong, скорее всего, избыточен, хватит nginx или Caddy. А когда сервисов пять и больше — Kong снимает эту головную боль системно.

Требования к серверу и подготовка

Kong (community edition, OSS) в режиме с базой данных требует PostgreSQL 13+ или Cassandra; на практике почти все ставят PostgreSQL. Есть ещё DB-less режим (конфиг из YAML-файла) — о нём ниже отдельно.

Минимальные требования для тестового или небольшого прод-стенда:

Под серьёзную нагрузку Kong масштабируется горизонтально — несколько нод перед общей базой, но для старта хватит одного сервера с 2 vCPU и 4 GB RAM.

Обновите систему и поставьте базовые пакеты:

apt update && apt upgrade -y
apt install -y curl gnupg2 lsb-release apt-transport-https ca-certificates

Если на сервере ещё не настроен firewall — сделайте это перед тем, как открывать порты Kong наружу, инструкция есть в статье про настройку UFW на Ubuntu.

Установка PostgreSQL и подготовка базы для Kong

Kong хранит конфигурацию (сервисы, маршруты, плагины, потребителей) в PostgreSQL. Если у вас ещё нет базы на сервере, разверните её по нашей статье про установку PostgreSQL на Ubuntu 24.04 — там подробно про создание пользователя и настройку доступа. Здесь — минимальный набор команд специально под Kong.

apt install -y postgresql postgresql-contrib
systemctl enable --now postgresql

Создайте пользователя и базу для Kong:

sudo -u postgres psql -c "CREATE USER kong WITH PASSWORD 'замените_на_свой_пароль';"
sudo -u postgres psql -c "CREATE DATABASE kong OWNER kong;"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE kong TO kong;"

Пароль храните в менеджере секретов или хотя бы в файле с правами 600 — он понадобится в конфиге Kong. Если PostgreSQL стоит на отдельном сервере (что для прод-нагрузки разумнее), убедитесь, что pg_hba.conf разрешает подключение с IP сервера Kong, а порт 5432 доступен только доверенным адресам, а не всему интернету.

Установка Kong Gateway из официального репозитория

Kong публикует .deb-пакеты под Ubuntu через собственный APT-репозиторий. На конец августа 2026 актуальная стабильная линейка — Kong 3.x; точную последнюю версию и корректную ссылку на пакет всегда проверяйте на странице загрузок Kong — версии выходят регулярно, и жёстко зашитый номер в статье быстро устаревает.

Добавляем репозиторий и ставим пакет:

curl -1sLf 'https://packages.konghq.com/public/gateway-oss/gpg.7B341C9DD2AAF15D.key' | gpg --dearmor -o /usr/share/keyrings/kong.gpg
echo "deb [signed-by=/usr/share/keyrings/kong.gpg] https://packages.konghq.com/public/gateway-oss/deb/ubuntu noble main" | tee /etc/apt/sources.list.d/kong.list

apt update
apt install -y kong

noble — кодовое имя Ubuntu 24.04, используйте именно его в строке репозитория. Если апт ругается на отсутствие пакета — проверьте, поддерживает ли репозиторий Kong noble для вашей линейки; если нет, временно подойдёт jammy (22.04) — пакеты обычно совместимы, но это компромисс.

Альтернатива без системного пакета — Docker-контейнер с образом kong:latest, удобнее для CI/CD, но здесь разбираем установку через systemd — она проще для одиночного сервера и понятнее для дебага.

Инициализация базы данных и первый запуск

Настройте Kong через конфиг /etc/kong/kong.conf — по умолчанию там лежит kong.conf.default, скопируйте его:

cp /etc/kong/kong.conf.default /etc/kong/kong.conf

Откройте файл и пропишите параметры подключения к БД:

database = postgres
pg_host = 127.0.0.1
pg_port = 5432
pg_user = kong
pg_password = замените_на_свой_пароль
pg_database = kong

proxy_listen = 0.0.0.0:8000, 0.0.0.0:8443 ssl
admin_listen = 127.0.0.1:8001

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

Прогоняем миграции — Kong сам создаёт нужные таблицы в базе:

kong migrations bootstrap -c /etc/kong/kong.conf

Запускаем Kong:

kong start -c /etc/kong/kong.conf

Проверка, что всё живо:

curl -i http://127.0.0.1:8001/

В ответ должен прийти JSON с версией Kong и текущей конфигурацией. Порт 8000 — это proxy-порт, куда будут стучаться клиенты; 8001 — админ-API для настройки. Для автозапуска после перезагрузки сервера включите systemd-юнит, который ставится вместе с пакетом:

systemctl enable kong

Настройка маршрутов, сервисов и первого плагина

Логика Kong строится на двух сущностях: Service (куда проксировать — ваш реальный бэкенд) и Route (по какому пути/домену/методу этот сервис вызывается). Добавляются они через админ-API (REST-запросы к порту 8001) или через декларативный YAML в DB-less режиме.

Пример: у вас есть бэкенд на http://10.0.0.5:3000, и вы хотите проксировать на него запросы по пути /api/users.

Создаём сервис:

curl -i -X POST http://127.0.0.1:8001/services \
  --data name=users-service \
  --data url=http://10.0.0.5:3000

Привязываем маршрут:

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

Проверяем через proxy-порт:

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

Запрос уйдёт на 10.0.0.5:3000, ответ вернётся через Kong.

Теперь добавим ограничение частоты запросов (rate limiting) — один из самых частых сценариев использования Kong:

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

Это ограничит клиентов 60 запросами в минуту на сервис. Параметр config.policy=local хранит счётчик в памяти ноды Kong — для одной ноды достаточно; при кластере из нескольких нод лимиты нужно синхронизировать через Redis (config.policy=redis), иначе каждая нода считает независимо и реальный лимит окажется в разы выше задуманного.

Для базовой аутентификации по ключу API добавьте плагин key-auth на сервис и создайте потребителя (consumer) с ключом — это уже отдельная тема, но общий принцип тот же: плагин на сервис/маршрут, конфигурация через админ-API, никаких правок кода в бэкенде.

Логирование, мониторинг и защита админки

Kong логирует доступ и ошибки как обычный nginx — по умолчанию файлы лежат в /usr/local/kong/logs/access.log и error.log (путь зависит от установки, проверьте prefix в конфиге). Для продакшена полезнее централизованный сбор — плагин http-log отправляет структурированные логи во внешнюю систему, а file-log пишет в формате, который заберёт агент вроде Promtail. Если у вас уже развёрнут стек логов, конфигурация описана в статье про Grafana Loki на Ubuntu 24.04.

Для метрик у Kong есть встроенный плагин prometheus — включается так же, глобально или на сервис:

curl -i -X POST http://127.0.0.1:8001/plugins \
  --data name=prometheus

После этого метрики Kong доступны на /metrics через admin API (обычно :8001/metrics), их можно скрейпить Prometheus-сервером и визуализировать в Grafana — установка обеих частей описана в статье про Grafana и Prometheus на Ubuntu 24.04.

Отдельно закройте порт 8001 (admin API) в firewall от внешнего мира, если ещё не сделали:

ufw deny 8001/tcp
ufw allow 8000/tcp
ufw allow 443/tcp

Порт 8000 (или 8443 для HTTPS) остаётся открытым — туда идёт клиентский трафик. SSL-сертификат на Kong вешается через флаг ssl в proxy_listen; для получения самого сертификата Let's Encrypt подойдёт certbot — принцип тот же, что в статье про certbot и acme.sh, только сертификат указывается в конфигурации Kong, а не nginx.

Резервное копирование и обновление

Вся конфигурация Kong живёт в PostgreSQL, поэтому резервное копирование сводится к обычному бэкапу базы:

pg_dump -U kong -h 127.0.0.1 kong > kong_backup_$(date +%F).sql

Автоматизируйте через cron — потеря базы Kong означает потерю всех маршрутов, плагинов и потребителей, а восстанавливать это руками через API долго и чревато ошибками.

Обновление Kong — это, по сути, обновление пакета и прогон миграций:

apt update
apt install --only-upgrade kong
kong migrations up -c /etc/kong/kong.conf
kong restart -c /etc/kong/kong.conf

Перед обновлением в проде проверьте changelog версии — Kong иногда меняет поведение плагинов между мажорными релизами, и то, что работало на 3.4, не всегда без изменений работает на 3.8. Тестируйте сначала на staging-копии сервера.

Если предпочитаете контейнерный подход — пригодится статья про Docker Compose в продакшене на Ubuntu 24.04: те же принципы health-check и рестарт-политик применимы и к контейнеру с Kong.

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