Radius MCP Server

# GitLab CI/CD для Radius MCP Server Этот документ описывает настройку и использование CI/CD пайплайна для автоматической сборки и развертывания Radius MCP Server в соответствии со стандартами **Radius**. ## 🏗️ Архитектура пайплайна Пайплайн основан на стандартах **gitlab-ci-apps** и включает следующие этапы: ### Этапы пайплайна 1. **Prebuild** - сборка Docker образов с werf и кастомными тегами 2. **UnitTestBack** - юнит-тесты и линтинг с PostgreSQL (только для Node.js проектов) 3. **CheckApproves** - проверка апрувов MR через GitLab API 4. **Converge** - развертывание в Kubernetes с помощью werf и Helm (Standard и AfterTest) 5. **E2ETest** - интеграционные тесты в кластере Kubernetes 6. **Cleanup** - очистка старых образов и релизов ## 📋 Стандарты именования веток Пайплайн поддерживает следующие форматы веток: ### ✅ Допустимые форматы: ```bash # Основные ветки develop testing prod20 # Фича ветки task-1234/feat/add-calendar-integration feat/task-1234-calendar-integration task-1234/feature/user-authentication improvement/task-5678-performance # Исправления task-1234/fix/calendar-api-bug fix/task-1234-memory-leak # Cherry-pick cherry-pick-1234 cherry-pick/hotfix-auth ``` ### ❌ Недопустимые форматы: ```bash feature/calendar bugfix/auth-issue hotfix-1234 random-branch-name ``` ## 🚀 Использование ### Автоматические действия #### При пуше в `develop`: - ✅ Сборка Docker образа - ✅ Запуск unit тестов и линтеров - 🔄 Автоматический деплой в **dev** окружение (Standard) - 🔄 Ручной деплой после тестов (AfterTest) #### При пуше в `testing`: - ✅ Все этапы выше - 🔄 Автоматический деплой в **testing** окружение (Standard) - 🔄 Ручной деплой после тестов (AfterTest) - 🔄 Ручные e2e тесты в кластере #### При пуше в `prod20`: - ✅ Все этапы выше - 🔄 Автоматический деплой в **production** окружение (Standard) - 🔄 Ручной деплой после тестов (AfterTest) ### Ручные действия #### Деплой после тестов ```bash # В GitLab → Pipelines → выбрать пайплайн → Manual actions # Converge Dev AfterTest (для develop) # Converge Staging AfterTest (для testing) # Converge Production AfterTest (для prod20) ``` #### E2E тесты в кластере ```bash # В GitLab → Pipelines → Manual actions → Back Tests # Запускает npm run test внутри пода в testing namespace ``` ## 🏢 Окружения ### Development (dev) - **Ветка:** `develop` - **URL:** https://radius-mcp-server-dev.myradius.ru - **Реплики:** 1 - **Ресурсы:** 500m CPU, 512Mi RAM - **Деплой:** Автоматический Standard + Ручной AfterTest ### Testing (testing) - **Ветка:** `testing` - **URL:** https://radius-mcp-server-testing.myradius.ru - **Реплики:** 2 - **Ресурсы:** 1000m CPU, 1Gi RAM - **Деплой:** Автоматический Standard + Ручной AfterTest - **E2E тесты:** Доступны ### Production (production) - **Ветка:** `prod20` - **URL:** https://radius-mcp-server.myradius.ru - **Реплики:** 3 (auto-scaling 3-10) - **Ресурсы:** 2000m CPU, 2Gi RAM - **Деплой:** Автоматический Standard + Ручной AfterTest ## 📁 Структура файлов ``` . ├── .gitlab-ci.yml # Основной пайплайн ├── _common.yml # Общие шаблоны (в корне!) ├── werf.yaml # Конфигурация werf ├── .werfignore # Исключения для сборки ├── Dockerfile # Многоэтапная сборка └── .helm/ # Helm чарт ├── Chart.yaml # Метаданные чарта ├── values.yaml # Базовые настройки ├── values.dev.yaml # Настройки dev ├── values.testing.yaml # Настройки testing ├── values.prod20.yaml # Настройки production └── templates/ # Kubernetes манифесты ├── deployment.yaml ├── service.yaml └── ingress.yaml ``` ## 🔧 Переменные GitLab CI/CD Настройте следующие переменные в Settings → CI/CD → Variables: ### 🔐 Werf и Registry ```bash # Werf repository URL WERF_REPO # Builds registry for images BUILDS_REGISTRY_URL # Cleanup password WERF_IMAGES_CLEANUP_PASSWORD # Helm charts token (для приватных чартов) HELM_CHARTS_TOKEN ``` ### 🔑 MR Approvals ```bash # GitLab token для проверки MR GITLAB_TOKEN_FOR_CI # Список пользователей для аппрува (через запятую) APPROVAL_AUTHORS="user1,user2,user3" ``` ### 📦 Application Secrets Секреты приложения устанавливаются через values файлы: ```bash # В values.dev.yaml, values.testing.yaml, values.prod20.yaml secrets: CALENDAR_API_HOST_URL: "https://api.dev.myradius.ru" CALENDAR_API_KEY: "your-api-key" ``` ## 🧪 Тестирование ### Unit тесты Выполняются автоматически в этапе `UnitTestBack`: ```bash npm run lint # ESLint проверки npm run format:check # Prettier проверки npm run build # TypeScript компиляция npm run test # Jest тесты ``` ### E2E тесты в кластере Запускаются вручную в этапе `Back Tests`: ```bash # Находит pod приложения в namespace testing kubectl -n testing exec $PODNAME -- sh -c "npm run test" ``` ## 🔄 Workflow ### 1. Разработка ```bash # Создание фича ветки git checkout -b task-1234/feat/calendar-integration # Разработка + коммиты git add . && git commit -m "Add calendar API integration" # Пуш ветки git push origin task-1234/feat/calendar-integration ``` ### 2. Merge Request ```bash # Создание MR в GitLab # Автоматически запускается: # - Prebuild # - UnitTestBack # - Check MR Approves (если целевая ветка develop/testing/prod20) ``` ### 3. Деплой в dev ```bash # Мерж в develop git checkout develop git merge task-1234/feat/calendar-integration git push origin develop # Автоматически запускается: # - Prebuild + UnitTestBack # - Converge Dev Standard (автоматический деплой) # # Ручные опции: # - Converge Dev AfterTest ``` ### 4. Деплой в testing ```bash # Мерж в testing git checkout testing git merge develop git push origin testing # Аналогично dev + Back Tests ``` ### 5. Деплой в production ```bash # Мерж в prod20 git checkout prod20 git merge testing git push origin prod20 # Финальный деплой в продакшн ``` ## 🧹 Очистка ### Автоматическая очистка - Запускается по расписанию (`schedule`) - Очищает старые образы werf с помощью `werf cleanup` - Лимит истории релизов: 3 (WERF_RELEASES_HISTORY_MAX) ## 📊 Мониторинг ### Health Checks - **Liveness probe:** `GET /mcp` каждые 10 сек (задержка 30 сек) - **Readiness probe:** `GET /mcp` каждые 5 сек (задержка 5 сек) ### Логи ```bash # Логи приложения kubectl logs -f deployment/radius-mcp-server -n $NAMESPACE # Логи werf werf logs --env $ENV ``` ## ❓ Частые проблемы ### Ошибка формата ветки ```bash Error: Неверный формат ветки ``` **Решение:** Используйте допустимые форматы (см. раздел "Стандарты именования веток") ### Ошибка MR approval ```bash Almost there! Please get approval from one of the following users... ``` **Решение:** Получите аппрув от пользователей из переменной `APPROVAL_AUTHORS` ### Ошибка деплоя werf ```bash werf converge failed ``` **Решение:** ```bash # Проверить состояние кластера kubectl get pods -n $NAMESPACE # Проверить логи werf werf logs --env $ENV # Проверить values файлы cat .helm/values.$ENV.yaml ``` ### Ошибка тестов ```bash npm run test failed ``` **Решение:** ```bash # Проверить PostgreSQL подключение kubectl get pods | grep postgres # Проверить переменные окружения env | grep POSTGRES ``` ## 🔒 Безопасность - ✅ Werf с автоматической очисткой образов - ✅ Проверка аппрувов для критичных веток - ✅ Валидация формата веток - ✅ SSL/TLS через nginx-ingress + cert-manager - ✅ Изоляция окружений через namespaces