Установка и настройка — Kong Gateway: от основ до

Установка и настройка Kong Gateway

Правильная установка Kong зависит от среды развёртывания: Docker для локальной разработки, Kubernetes для production, bare-metal для специфических требований.

#1. Установка в Docker (локальная разработка)

Проблема: Нужно быстро развернуть Kong для локальной разработки и тестирования.

Решение: Docker Compose с минимальной конфигурацией.

#1.1. Быстрый старт с DB-less режимом

Проблема: Не хочется зависеть от PostgreSQL для локальной разработки.

Решение: DB-less режим с загрузкой конфигурации из YAML.

# docker-compose.yml
version: '3.8'

services:
  kong:
    image: kong:3.5
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /kong/kong.yml
      KONG_PROXY_ACCESS_LOG: /dev/stdout
      KONG_ADMIN_ACCESS_LOG: /dev/stdout
      KONG_PROXY_ERROR_LOG: /dev/stderr
      KONG_ADMIN_ERROR_LOG: /dev/stderr
    ports:
      - "8000:8000"
      - "8443:8443"
      - "8001:8001"
      - "8444:8444"
    volumes:
      - ./kong.yml:/kong/kong.yml:ro

volumes:
  kong_data:

# kong.yml
_format_version: "3.0"

services:
  - name: echo-service
    url: http://httpbin.org
    routes:
      - name: echo-route
        paths: [/echo]

plugins:
  - name: rate-limiting
    config:
      minute: 100
      policy: local

Запуск:

docker-compose up -d

Проверка:

# Проверка прокси
curl http://localhost:8000/echo/get

# Проверка Admin API
curl http://localhost:8001

#1.2. Полноценная установка с PostgreSQL

Проблема: Нужна персистентная конфигурация с возможностью динамического обновления через Admin API.

Решение: Docker Compose с PostgreSQL.

# docker-compose.yml
version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: kong
      POSTGRES_DB: kong
      POSTGRES_PASSWORD: kong
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U kong"]
      interval: 5s
      timeout: 5s
      retries: 5

  kong:
    image: kong:3.5
    environment:
      KONG_DATABASE: postgres
      KONG_PG_HOST: postgres
      KONG_PG_USER: kong
      KONG_PG_PASSWORD: kong
      KONG_PG_DATABASE: kong
      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: 0.0.0.0:8001
      KONG_ADMIN_GUI_LISTEN: 0.0.0.0:8002
    ports:
      - "8000:8000"
      - "8443:8443"
      - "8001:8001"
      - "8444:8444"
      - "8002:8002"
    depends_on:
      postgres:
        condition: service_healthy
    command: kong docker-start

volumes:
  postgres_data:

Важно: Перед первым запуском нужно инициализировать базу данных:

# Запускаем только PostgreSQL
docker-compose up -d postgres

# Ждём готовности БД
sleep 10

# Выполняем миграции
docker-compose run --rm kong kong migrations bootstrap

# Запускаем Kong
docker-compose up -d kong

Проверка:

# Проверка Admin API
curl http://localhost:8001

# Создание тестового сервиса
curl -X POST http://localhost:8001/services \
  --data "name=test" \
  --data "url=http://httpbin.org"

curl -X POST http://localhost:8001/services/test/routes \
  --data "name=test-route" \
  --data "paths[]=/test"

#2. Установка в Kubernetes (production)

Проблема: Нужно надёжное, масштабируемое развёртывание в production.

Решение: Helm chart от Kong.

#2.1. Установка через Helm

Проблема: Ручное создание Kubernetes-манифестов сложно поддерживать и обновлять.

Решение: Helm chart управляет версионированием и упрощает конфигурацию.

# Добавляем репозиторий Kong
helm repo add kong https://charts.konghq.com
helm repo update

# Создаём namespace
kubectl create namespace kong

# Устанавливаем Kong
helm install kong/kong \
  --namespace kong \
  --set ingressController.enabled=true \
  --set proxy.http.enabled=true \
  --set proxy.http.servicePort=8000 \
  --set proxy.http.nodePort=30800 \
  --set proxy.type=LoadBalancer \
  --set postgresql.enabled=true \
  --generate-name

#2.2. Кастомизация через values.yaml

Проблема: Нужно настроить параметры под production-требования.

Решение: Файл values.yaml с полной конфигурацией.

# values.yaml
ingressController:
  enabled: true
  ingressClass: kong
  kongAdminApi:
    create: true

proxy:
  enabled: true
  http:
    enabled: true
    servicePort: 8000
  tls:
    enabled: true
    servicePort: 8443
  type: LoadBalancer

admin:
  enabled: true
  type: ClusterIP
  http:
    enabled: true
    servicePort: 8001

postgresql:
  enabled: true
  postgresqlUsername: kong
  postgresqlPassword: secure-password-here
  postgresqlDatabase: kong

replicaCount: 3

resources:
  limits:
    cpu: 1
    memory: 1Gi
  requests:
    cpu: 500m
    memory: 512Mi

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchLabels:
              app: kong
          topologyKey: kubernetes.io/hostname

Установка:

helm install kong kong/kong \
  --namespace kong \
  -f values.yaml

#2.3. Проверка развёртывания

# Проверка подов
kubectl get pods -n kong

# Проверка сервиса
kubectl get svc -n kong

# Получение внешнего IP
kubectl get svc -n kong kong-proxy

# Проверка логов
kubectl logs -n kong -l app=kong

#3. Установка на bare-metal (Linux)

Проблема: Нужно развернуть Kong на выделенном сервере без Docker.

Решение: Установка через пакетный менеджер или бинарный файл.

#3.1. Установка через пакетный менеджер

Для Ubuntu/Debian:

# Добавляем репозиторий Kong
curl -fsSL https://download.konghq.com/gateway-3.x/debian/kong-archive-keyring.asc | \
  sudo gpg --dearmor -o /usr/share/keyrings/kong-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/kong-archive-keyring.gpg] \
  https://download.konghq.com/gateway-3.x/debian bullseye main" | \
  sudo tee /etc/apt/sources.list.d/kong.list

# Устанавливаем
sudo apt update
sudo apt install kong

Для CentOS/RHEL:

# Добавляем репозиторий
curl -fsSL https://download.konghq.com/gateway-3.x/el/kong-archive-keyring.asc | \
  sudo gpg --dearmor -o /etc/pki/rpm-gpg/kong-archive-keyring.gpg

echo -e "[kong]\nname=Kong Repository\nbaseurl=https://download.konghq.com/gateway-3.x/el/\nenabled=1\ngpgcheck=1\ngpgkey=file:///etc/pki/rpm-gpg/kong-archive-keyring.asc" | \
  sudo tee /etc/yum.repos.d/kong.repo

# Устанавливаем
sudo yum install kong

#3.2. Конфигурация kong.conf

Проблема: Нужно настроить Kong для production.

Решение: Файл конфигурации /etc/kong/kong.conf.

# /etc/kong/kong.conf

# База данных
database = postgres
pg_host = 127.0.0.1
pg_port = 5432
pg_user = kong
pg_password = secure-password
pg_database = kong

# Логи
proxy_access_log = /var/log/kong/access.log
proxy_error_log = /var/log/kong/error.log
admin_access_log = /var/log/kong/admin_access.log
admin_error_log = /var/log/kong/admin_error.log

# Слушатели
proxy_listen = 0.0.0.0:8000, 0.0.0.0:8443 ssl
admin_listen = 0.0.0.0:8001, 0.0.0.0:8444 ssl

# Производительность
nginx_worker_processes = 4
lua_package_path = /path/to/custom/?.lua;;

# Плагины (только нужные)
plugins = bundled,my-custom-plugin

#3.3. Инициализация и запуск

# Инициализация базы данных
kong migrations bootstrap

# Запуск
kong start

# Проверка статуса
kong status

# Перезапуск
kong restart

#3.4. Настройка systemd

Проблема: Нужно автоматическое управление сервисом.

Решение: Systemd unit файл /etc/systemd/system/kong.service.

[Unit]
Description=Kong Gateway
After=network.target postgresql.service

[Service]
Type=forking
User=kong
Group=kong
EnvironmentFile=/etc/kong/kong.conf
ExecStart=/usr/bin/kong start
ExecReload=/usr/bin/kong restart
ExecStop=/usr/bin/kong stop
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

# Перезагружаем systemd
sudo systemctl daemon-reload

# Включаем автозапуск
sudo systemctl enable kong

# Запускаем
sudo systemctl start kong

# Проверка статуса
sudo systemctl status kong

#4. Hybrid Mode развёртывание

Проблема: Нужно централизованное управление множеством Data Plane узлов.

Решение: Разделение Control Plane и Data Plane.

#4.1. Конфигурация Control Plane

# cp-kong.yml
_format_version: "3.0"

services:
  - name: control-plane
    url: http://localhost:8001

plugins:
  - name: rate-limiting
    config:
      minute: 100

# Запуск Control Plane
KONG_ROLE=control_plane \
KONG_DATABASE=postgres \
KONG_PG_HOST=postgres \
KONG_CLUSTER_CERT=/etc/kong/cluster.crt \
KONG_CLUSTER_CERT_KEY=/etc/kong/cluster.key \
KONG_CLUSTER_TELEMETRY_ENDPOINT=0.0.0.0:8005 \
KONG_CLUSTER_CONTROL_ENDPOINT=0.0.0.0:8006 \
kong start

#4.2. Конфигурация Data Plane

# Запуск Data Plane
KONG_ROLE=data_plane \
KONG_DATABASE=off \
KONG_CLUSTER_CERT=/etc/kong/cluster.crt \
KONG_CLUSTER_CERT_KEY=/etc/kong/cluster.key \
KONG_CLUSTER_CONTROL_PLANE=control-plane:8006 \
KONG_CLUSTER_TELEMETRY_ENDPOINT=control-plane:8005 \
kong start

#4.3. Генерация сертификатов для кластера

Проблема: Нужно безопасное соединение между CP и DP.

Решение: Взаимная TLS-аутентификация.

# Генерация CA
openssl genrsa -out cluster-ca.key 2048
openssl req -new -x509 -key cluster-ca.key -out cluster-ca.crt -days 365 \
  -subj "/CN=Kong Cluster CA"

# Генерация сертификата для Control Plane
openssl genrsa -out cp.key 2048
openssl req -new -key cp.key -out cp.csr -subj "/CN=Control Plane"
openssl x509 -req -in cp.csr -CA cluster-ca.crt -CAkey cluster-ca.key \
  -CAcreateserial -out cp.crt -days 365

# Генерация сертификата для Data Plane
openssl genrsa -out dp.key 2048
openssl req -new -key dp.key -out dp.csr -subj "/CN=Data Plane"
openssl x509 -req -in dp.csr -CA cluster-ca.crt -CAkey cluster-ca.key \
  -CAcreateserial -out dp.crt -days 365

#5. Проверка установки

#5.1. Базовые проверки

# Проверка версии
kong version

# Проверка статуса (для standalone)
kong status

# Проверка Admin API
curl http://localhost:8001

# Проверка информации о узле
curl http://localhost:8001/info

#5.2. Создание тестового сервиса

# Создание сервиса
curl -X POST http://localhost:8001/services \
  --data "name=echo" \
  --data "url=http://httpbin.org"

# Создание маршрута
curl -X POST http://localhost:8001/services/echo/routes \
  --data "name=echo-route" \
  --data "paths[]=/api"

# Тестирование
curl http://localhost:8000/api/get

#5.3. Применение плагина

# Применение rate limiting
curl -X POST http://localhost:8001/routes/echo-route/plugins \
  --data "name=rate-limiting" \
  --data "config.minute=5"

# Тестирование (5 запросов пройдут, 6-й получит 429)
for i in {1..6}; do
  curl -w "%{http_code}\n" -o /dev/null http://localhost:8000/api/get
done

#6. Troubleshooting

#6.1. Kong не запускается

Проблема: Ошибка подключения к базе данных.

Решение:

# Проверка доступности PostgreSQL
nc -zv postgres 5432

# Проверка логов
docker logs kong

# Проверка конфигурации
kong check /etc/kong/kong.conf

#6.2. Миграции не применяются

Проблема: Ошибка при выполнении kong migrations bootstrap.

Решение:

# Проверка версии БД
kong migrations current

# Принудительное применение миграций
kong migrations up --force

# Откат к предыдущей версии
kong migrations down

#6.3. Высокая задержка

Проблема: Запросы обрабатываются медленно.

Решение:

# Проверка количества worker процессов
grep nginx_worker_processes /etc/kong/kong.conf

# Увеличение worker процессов (до числа CPU ядер)
nginx_worker_processes = 8

# Проверка логов на ошибки
tail -f /var/log/kong/error.log

#7. Best Practices

#7.1. Безопасность

Ограничьте доступ к Admin API — только из внутренней сети
Используйте TLS для всех соединений
Регулярно обновляйте Kong до последней стабильной версии
Включайте только нужные плагины — уменьшает attack surface

#7.2. Производительность

Используйте Redis для rate limiting — вместо local policy
Настройте кэширование — proxy-cache для часто запрашиваемых ресурсов
Горизонтально масштабируйте Data Plane узлы
Мониторьте метрики — latency, RPS, ошибки

#7.3. Надёжность

Минимум 3 реплики в production
Pod anti-affinity в Kubernetes — распределение по узлам
Health checks — настройка liveness/readiness проб
Backup базы данных — регулярные снепшоты PostgreSQL