Add pipline/deploy_docker-compose-context/readme.MD

2025-08-10 18:55:52 +08:00 · 2025-08-10 18:55:52 +08:00 · c579e3321a
commit c579e3321a
parent f1ad7ab230
1 changed files with 113 additions and 0 deletions
--- a/pipline/deploy_docker-compose-context/readme.MD
+++ b/pipline/deploy_docker-compose-context/readme.MD
@ -0,0 +1,113 @@
+Вот подробное и структурированное **описание пайплайна развертывания с использованием Docker и удалённого хоста**, которое можно использовать как документацию или комментарий в `.gitlab-ci.yml`:
+
+---
+
+### **Описание пайплайна: Развертывание приложения через Docker Compose с аутентификацией в приватном реестре**
+
+Этот пайплайн предназначен для **безопасного развертывания приложения на удалённом Docker-хосте** с использованием `docker context` и `docker compose`. Он поддерживает защищённое подключение к Docker-демону по TLS и аутентификацию в приватном Docker-реестре (например, Nexus).
+
+---
+
+###  **Назначение**
+- Автоматическое развертывание сервисов, описанных в `docker-compose.yml`, на удалённом хосте.
+- Поддержка развёртывания в разные окружения (например, `test`, `staging`).
+- Работа с защищённым Docker-демоном (через TLS-сертификаты).
+- Аутентификация в приватном реестре с использованием base64-закодированного пароля.
+
+---
+
+###  **Ключевые компоненты**
+
+####  Аутентификация в Docker-реестре
+Используется безопасный способ входа через `--password-stdin`:
+```yaml
+.docker_login_stdin_base64: &docker-login-stdin-base64
+  - echo $REGISTRY_PASSWORD | base64 -d | docker login -u $REGISTRY_USER $REGISTRY --password-stdin
+```
+> Пароль передаётся в виде **base64-закодированной строки**, чтобы избежать проблем с спецсимволами и повысить безопасность в логах.
+
+####  Удалённое подключение к Docker (Docker Context)
+Создаётся отдельный контекст для безопасного подключения к удалённому хосту:
+```yaml
+.docker_context_create: &docker-context-create
+  - docker context create ${CI_PROJECT_NAME}-${ENV} --docker "host=tcp://${HOST},ca=${CA_FILE},cert=${CERT_FILE},key=${KEY_FILE}"
+```
+> Используются TLS-сертификаты (`ca`, `cert`, `key`) для аутентификации на Docker-хосте.
+
+####  Развертывание через Docker Compose
+```yaml
+.docker_context_deploy: &docker-context-deploy
+  - DOCKER_CONTEXT=... docker compose -f docker-compose.yml pull
+  - DOCKER_CONTEXT=... docker compose -f docker-compose.yml up -d --force-recreate
+```
+> Обновляет образы и перезапускает контейнеры с принудительным пересозданием.
+
+---
+
+### **Этапы выполнения (`deploy`)**
+
+1. **Вывод переменных окружения** (`env | sort`) — для отладки и аудита.
+2. **Логин в Docker-реестр** — с расшифровкой пароля из base64.
+3. **Создание Docker-контекста** — подключение к удалённому хосту по TLS.
+4. **Развертывание сервисов**:
+   - Скачивание актуальных образов (`pull`).
+   - Запуск сервисов в фоне с пересозданием (`up -d --force-recreate`).
+
+---
+
+### **Переменные окружения**
+
+| Переменная | Обязательная | Описание |
+|-----------|-------------|---------|
+| `ENV` | Да | Имя окружения (например, `test`, `staging`) |
+| `HOST` | Да | Адрес удалённого Docker-хоста (например, `example.com:2376`) |
+| `CA_FILE` | Да | Содержимое файла `ca.pem` (TLS) |
+| `CERT_FILE` | Да | Содержимое `cert.pem` |
+| `KEY_FILE` | Да | Содержимое `key.pem` |
+| `REGISTRY_USER` | Да | Пользователь реестра (например, `nexus`) |
+| `REGISTRY_PASSWORD` | Да | **Base64-закодированный** пароль для доступа к реестру |
+| `REGISTRY` | Да | URL Docker-реестра (например, `nexus.example.com:5000`) |
+| `COMPOSE_FILES` | Нет (по умолч. `-f docker-compose.yml`) | Дополнительные файлы Compose (например, `-f docker-compose.prod.yml`) |
+| `DOCKER_IMAGE` | Да | Образ, в котором запускается пайплайн (с установленным Docker CLI) |
+
+>  Рекомендуется хранить `CA_FILE`, `CERT_FILE`, `KEY_FILE` и `REGISTRY_PASSWORD` как **CI/CD Variables** в GitLab (с флагом "Masked", если возможно).
+
+---
+
+###  **Теги и образ**
+- **Образ**: `${DOCKER_IMAGE}` — должен содержать `docker` CLI и поддерживать `docker context` и `docker compose`.
+- **Окружение**: Указывается как `environment: name: ${ENV}` — отображается в GitLab CI.
+- **Стадия**: `deploy` — выполняется на этапе развертывания.
+
+---
+
+###  **Безопасность**
+- Пароль реестра **не передаётся напрямую**, а декодируется из base64.
+- Подключение к Docker-хосту — **по TLS**, с использованием сертификатов.
+- Все чувствительные данные передаются через защищённые CI-переменные.
+
+---
+
+###  **Пример использования**
+1. Убедитесь, что в CI/CD Variables заданы:
+   - `NEXUS_PASS_BASE64` — base64-код пароля.
+   - `CA_FILE`, `CERT_FILE`, `KEY_FILE` — содержимое сертификатов.
+2. Запустите пайплайн вручную.
+3. Выберите окружение (например, `test`) и убедитесь, что переменные `HOST` и `ENV` корректны.
+
+---
+
+###  **Примечания**
+- Убедитесь, что удалённый Docker-демон разрешает подключения по TCP с вашего CI-раннера.
+- Файлы сертификатов должны быть **полностью вставлены** в переменные (включая `-----BEGIN CERTIFICATE-----` и т.д.).
+- Для разных окружений можно создавать отдельные джобы с переопределением `ENV`, `HOST` и т.д.
+
+---
+
+ **Назначение:** Быстрое и безопасное развертывание приложений в тестовых/стейджинг окружениях с использованием Docker и приватного реестра.
+
+ **Рекомендуется использовать с GitLab CI, Docker 20.10+, и настроенным TLS на Docker-хосте.**
+
+---
+
+