Локальный Kubernetes-кластер в один клик: развертывание с OAuth и Stripe через Kindling

Локальный Kubernetes-кластер в один клик: развертывание с OAuth и Stripe через Kindling

Разработка микросервисных приложений осложняется несовместимостью сред. Локальный запуск через Docker Compose скрывает особенности сетевой структуры, Ingress-контроллеров и секретов в Kubernetes. Для тестирования внешних интеграций — таких как авторизация OAuth (через Auth0) или обработка платежных вебхуков Stripe — требуются публичные HTTPS-адреса. Командам приходится развертывать промежуточные среды (staging) в облаке, что увеличивает затраты и замедляет цикл разработки.

Инструмент Kindling решает эту задачу, позволяя развернуть локальный кластер Kubernetes на базе Kind (Kubernetes in Docker) прямо на рабочей станции. Он автоматически генерирует манифесты, интегрирует локальные CI/CD-пайплайны и упрощает проброс внешнего трафика для тестирования интеграций.

Архитектура демонстрационного приложения

Для разбора возможностей платформы используется приложение oauth-example, представляющее собой распределенную систему:

1. Фронтенд: UI на React, развернутый под управлением Nginx.
2. Шлюз (Gateway): сервис на Go для маршрутизации и проверки авторизации.
3. Сервис заказов (Orders): бэкенд на Python/FastAPI, работающий с PostgreSQL.
4. Сервис инвентаря (Inventory): бэкенд на Node.js/Fastify, работающий с MongoDB.
5. Очередь сообщений: брокер Redis для асинхронного обмена событиями.

Пошаговый чек-лист локального развертывания

Ниже представлено официальное руководство по настройке локальной инфраструктуры, генерации конфигураций и запуску микросервисов.

Предварительные требования

• ОС: macOS (пакетный менеджер Homebrew) или Linux.
• Среда контейнеризации: запущенный Docker (Kind создает узлы Kubernetes в контейнерах).
• Репозиторий GitHub и токен доступа (PAT) для регистрации runner.
• Ключ API Kindling для генерации манифестов.
• Внешние учетные записи: аккаунты в панелях Auth0 и Stripe (в режиме тестирования).

!IMPORTANT Никогда не сохраняйте в Git и не передавайте публично секретные ключи: клиентский секрет Auth0, приватный API-ключ Stripe, токен GitHub PAT или сессионный секрет приложения. Используйте встроенные механизмы хранения секретов Kindling.

Шаг 1. Установка и инициализация Kindling

Выполните установку CLI Kindling через Homebrew и запустите инициализацию локального кластера:

brew install kindlingdev/tap/kindling
kindling init

Где происходит действие: терминал локального компьютера. Что делает команда: скачивает CLI, разворачивает локальный кластер Kubernetes на базе Kind, устанавливает внутренний реестр (Registry), Traefik Ingress Controller и оператор управления. Проверка: команда kindling status должна вернуть статус готовности локального окружения.

Шаг 2. Регистрация локального GitHub Actions Runner

Для сборки контейнеров и развертывания кода внутри кластера подключите агент сборки (runner):

kindling runners -u <github-user> -r oauth-test -t <github-pat>

Где происходит действие: терминал локального компьютера. Что делает команда: регистрирует и запускает под с self-hosted runner внутри Kind-кластера, связывая его с вашим репозиторием GitHub. Проверка: в настройках репозитория GitHub (Settings -> Actions -> Runners) зарегистрированный раннер должен быть Online.

Шаг 3. Генерация манифестов и пайплайнов

Запустите сканирование исходного кода проекта для генерации инфраструктурных файлов:

kindling generate -k <api-key> -r .

Где происходит действие: терминал в корневой директории вашего проекта. Что делает команда: ИИ-движок Kindling анализирует репозиторий и создает конфигурацию GitHub Actions, манифесты развертывания Kubernetes и файлы DSE. Она планирует запуск зависимостей: PostgreSQL, MongoDB и Redis.

Шаг 4. Настройка секретов перед первым развертыванием

Зарегистрируйте приложение в Auth0 (Regular Web Application) и скопируйте Domain, Client ID и Client Secret. В панели Stripe скопируйте тестовый секретный ключ (начинается с sk_test_). Запишите переменные в хранилище секретов кластера:

kindling secrets set AUTH0_DOMAIN your-tenant.auth0.com
kindling secrets set AUTH0_CLIENT_ID your-client-id
kindling secrets set AUTH0_CLIENT_SECRET your-client-secret
kindling secrets set SESSION_SECRET $(openssl rand -hex 32)
kindling secrets set STRIPE_SECRET_KEY sk_test_your_stripe_secret_key
kindling secrets set STRIPE_WEBHOOK_SECRET placeholder
kindling secrets set PUBLIC_URL http://localhost

Что делает команда: сохраняет конфиденциальные данные внутри секретов Kubernetes. Вместо реального Stripe Webhook Secret мы пишем заглушку placeholder.

Шаг 5. Запуск сборки и развертывания

Отправьте изменения в ваш GitHub-репозиторий:

git add -A
git commit -m "initial deploy"
git push origin main

Что делает команда: отправка кода запускает workflow на GitHub. Локальный runner перехватывает задачу, собирает четыре образа контейнеров с помощью Kaniko, помещает их во внутренний реестр localhost:5001 и применяет манифесты. Проверка: в терминале выполните kindling status. Все поды должны быть в статусе 1/1 Running. Проверьте локальный доступ по адресу http://jeff-vincent-ui.localhost.

Шаг 6. Настройка внешнего HTTPS-туннеля

Чтобы внешние сервисы могли отправлять данные на вашу локальную машину, настройте туннелирование:

brew install cloudflared
sudo cloudflared service install <your-token>
kindling expose

Что делает команда: устанавливает клиент Cloudflare и пробрасывает локальный Traefik Ingress наружу, выделяя публичный HTTPS-адрес вида https://<random-subdomain>.trycloudflare.com. Проверка: откройте полученный HTTPS-адрес в браузере — вы должны увидеть интерфейс вашего приложения.

Шаг 7. Привязка внешних интеграций к туннелю

1. В настройках приложения Auth0 пропишите адреса:
   • Allowed Callback URLs: https://<your-tunnel-url>/auth/callback
   • Allowed Logout URLs: https://<your-tunnel-url>
   • Allowed Web Origins: https://<your-tunnel-url>
   • Предостережение: в продуктивных окружениях запрещено использовать localhost или адреса отладочных туннелей.
2. В панели управления Stripe (Webhooks) нажмите Create event destination:
   • Endpoint URL: https://<your-tunnel-url>/webhooks/stripe.
   • Select events: выберите checkout.session.completed и payment_intent.succeeded.
   • Создайте эндпоинт и скопируйте секретный ключ подписи вебхуков (whsec_...).

Шаг 8. Обновление секретов и тестирование

Замените временные заглушки реальными значениями туннеля и подписи вебхука:

kindling secrets set PUBLIC_URL https://<your-tunnel-url>
kindling secrets set STRIPE_WEBHOOK_SECRET whsec_your_signing_secret

Поды шлюза автоматически перезапустятся. Выполните проверку статуса интеграций:

curl http://jeff-vincent-gateway.localhost/auth/status
curl http://jeff-vincent-gateway.localhost/stripe/status

Успешный результат: теперь вы можете открыть адрес туннеля, пройти авторизацию через Auth0 и эмулировать платеж Stripe. Запросы успешно пройдут через внешние сервера и попадут в ваш локальный под.

Оптимизация процесса разработки (Inner Loop)

После успешного развертывания вы можете использовать инструменты быстрой разработки, не требующие коммита кода для каждого изменения:

• Синхронизация файлов: команда kindling sync -d jeff-vincent-gateway отслеживает изменения в кодах на диске и мгновенно копирует их прямо в работающий контейнер, обеспечивая быструю перезагрузку (hot reload).
• Удаленная отладка: команда kindling debug -d jeff-vincent-orders --port 5678 запускает отладочную сессию внутри пода.

Риски, ограничения и переход на Production

Использование локального стейджинга значительно ускоряет работу, однако необходимо учитывать следующие нюансы:

1. Динамические адреса туннелей: при перезапуске процесса cloudflared адрес туннеля может измениться. В этом случае придется заново обновить настройки Callback URLs в Auth0 и Endpoint URL в Stripe.
2. Обработка вебхуков Stripe: Stripe ожидает быстрый ответ HTTP 200 от вашего вебхука. Если обработка платежа занимает много времени, Stripe посчитает запрос неудачным. Выносите длительную обработку в асинхронные фоновые задачи (например, через Redis).
3. Требования к TLS: Stripe требует обязательного шифрования TLS версий 1.2 или 1.3 для доставки вебхуков. При работе напрямую с localhost платежи приходить не будут.
4. Переход в продуктивное окружение: локальный кластер служит только для функционального тестирования. При развертывании в продуктивный кластер необходимо переключить контекст с помощью kindling dashboard --prod-context <your-prod-cluster-context>, заменить все тестовые ключи sk_test_ на живые sk_live_, настроить постоянные DNS-записи для Ingress и подключить cert-manager.