From 4eb613fdb882730feaec075b33592903076b3d7b Mon Sep 17 00:00:00 2001 From: pashko Date: Sun, 10 Aug 2025 19:09:19 +0800 Subject: [PATCH] Add pipline/docker_build/readme.MD --- pipline/docker_build/readme.MD | 188 +++++++++++++++++++++++++++++++++ 1 file changed, 188 insertions(+) create mode 100644 pipline/docker_build/readme.MD diff --git a/pipline/docker_build/readme.MD b/pipline/docker_build/readme.MD new file mode 100644 index 0000000..46c797c --- /dev/null +++ b/pipline/docker_build/readme.MD @@ -0,0 +1,188 @@ + +--- + +### 📝 **Описание пайплайна: Сборка и ретегирование Docker-образов с помощью Buildah** + +Этот пайплайна предназначен для **безопасной, rootless-совместимой сборки, тегирования и публикации Docker-образов** в приватный реестр с использованием **Buildah** — инструмента для работы с образами без необходимости запуска Docker-демона. + +Пайплайн поддерживает: +- Сборку образов из `Dockerfile`. +- Автоматическое тегирование по ветке или тегу. +- Публикацию в GitLab Container Registry. +- Ретегирование существующих образов (например, `latest`, `stable`). +- Работу в CI/CD без привилегированных прав (поддержка rootless-режима). + +--- + +### 🧱 **Основные возможности** + +| Функция | Описание | +|--------|--------| +| ✅ `buildah bud` | Сборка образа из `Dockerfile` с поддержкой аргументов и кэширования | +| ✅ `buildah push` | Загрузка образа в приватный реестр | +| ✅ Авто-тегирование | Образы тегируются по имени ветки (`develop`, `feature/*`) или по тегу (`v1.2.3`) | +| ✅ `latest` для `main`/`master` | При коммите в `main` или `master` — образ дополнительно помечается как `:latest` | +| ✅ Ретегирование | Перенос тегов между образами (например, `app:v1.5` → `app:prod`) | +| 🔐 Безопасный login | Использование `--password-stdin` + base64-декодирование пароля | + +--- + +### 🛠️ **Используемые Buildah-шаблоны** + +```yaml +.buildah_info: &buildah-info + - until buildah --version; do sleep 1; done +``` +> Проверяет доступность Buildah (полезно при старте контейнера). + +```yaml +.buildah_login_stdin_base64: &buildah-login-stdin-base64 + - echo "$REGISTRY_PASSWORD" | base64 -d | buildah login -u $REGISTRY_USER $REGISTRY --password-stdin +``` +> Безопасный вход в реестр: пароль в base64-кодировке, не попадает в логи напрямую. + +```yaml +.buildah_build: &buildah-build + - buildah bud $BUILD_STORAGE_DRIVER $BUILD_CACHE $BUILD_ARGS --isolation=$BUILDAH_ISOLATION -f $DOCKERFILE_PATH -t $DOCKER_TAG $CONTEXT_PATH +``` +> Сборка образа с поддержкой: +> - кастомных `--build-arg` +> - отключения кэша (`--no-cache`) +> - выбора драйвера хранения (по умолчанию `vfs` — совместим с rootless) + +```yaml +.buildah_push: &buildah-push + - buildah images + - buildah push $DOCKER_TAG + - if [[ "${CI_COMMIT_REF_SLUG}" == "main" || ... ]]; then buildah tag ... :latest; fi + - if [[ ... ]]; then buildah push ... :latest; fi +``` +> Отправка образа в реестр и автоматическое обновление тега `:latest` на `main`/`master`. + +```yaml +.buildah_retag: &buildah-retag + - buildah pull $SOURCE_IMAGE + - buildah tag $SOURCE_IMAGE $TARGET_IMAGE + - buildah push $TARGET_IMAGE +``` +> Ретегирование: скачивает существующий образ и выставляет новый тег (например, для релизов или продакшена). + +```yaml +.buildah_logout: &buildah-logout + - buildah logout $REGISTRY +``` +> Очистка сессии после работы. + +--- + +### 🏗️ **Стадии пайплайна** + +#### 1. `build` — Сборка и публикация образа +- **Образ CI**: `sed-docker.artifacts.tn.tngrp.ru/buildah:v1.39.3-ca` +- **Переменные по умолчанию**: + - `CONTEXT_PATH`: корень проекта + - `DOCKERFILE_PATH`: `Dockerfile` в корне + - `DOCKER_TAG`: `$CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG` (например, `image:develop`) +- **Тегирование по тегу релиза**: + ```bash + Если CI_COMMIT_TAG = v1.2.3 → образ: image:v1.2.3 + Иначе → image:feature-login + ``` +- **Автоматическое обновление `:latest`** при коммите в `main`/`master`. + +#### 2. `retag` — Ретегирование существующего образа +- Используется для: + - Продвижения образа (например, `app:v1.5` → `app:prod`) + - Установки `:stable`, `:canary`, `:rollback` и т.п. +- Требует ручного запуска и указания: + - `SOURCE_IMAGE` — исходный образ (например, `registry/app:v1.5`) + - `TARGET_IMAGE` — целевой тег (например, `registry/app:prod`) + +--- + +### ⚙️ **Ключевые переменные** + +| Переменная | Описание | +|----------|--------| +| `CI_REGISTRY` / `CI_REGISTRY_USER` / `CI_REGISTRY_PASSWORD` | Данные для доступа к GitLab Registry (автоматически заданы в CI) | +| `CI_REGISTRY_IMAGE` | Полный путь к образу (например, `registry.example.com/group/app`) | +| `CI_COMMIT_REF_SLUG` | Имя ветки в URL-безопасном формате | +| `CI_COMMIT_TAG` | Тег коммита (если запущено по тегу) | +| `BUILD_ARGS` | Дополнительные аргументы сборки (через `--build-arg`) | +| `BUILD_CACHE` | Кэширование слоёв (`--no-cache` по умолчанию) | +| `BUILDAH_ISOLATION` | Режим изоляции: `chroot` (подходит для rootless) | +| `BUILD_STORAGE_DRIVER` | Драйвер хранения: `vfs` — рекомендуется для rootless | + +--- + +### 🔐 **Безопасность** +- Пароль реестра **не передаётся в открытом виде** — используется `echo "$REGISTRY_PASSWORD" | base64 -d | buildah login --password-stdin`. +- Поддержка **rootless-режима** через `vfs` и `chroot`. +- Все операции выполняются в изолированном CI-раннере. + +--- + +### 🧪 **Примеры использования** + +#### ✅ Сборка при пуше в ветку `develop` +```bash +# Образ: registry/app:develop +# Сборка с --no-cache +# Без тега latest +``` + +#### ✅ Сборка при теге `v2.1.0` +```bash +# Образ: registry/app:v2.1.0 +# Не влияет на latest +``` + +#### ✅ Сборка в `main` → обновление `:latest` +```bash +# Образ: registry/app:main + registry/app:latest +``` + +#### ✅ Ретегирование (ручной запуск) +```yaml +variables: + SOURCE_IMAGE: registry/app:v2.1.0 + TARGET_IMAGE: registry/app:prod +``` +> Результат: `registry/app:prod` указывает на тот же слой, что и `v2.1.0`. + +--- + +### 📌 **Требования** +- GitLab CI с доступом к `buildah`-образу. +- Настроенные права на запись в Container Registry. +- Для `retag` — образ должен уже существовать в реестре. +- Раннер должен поддерживать выполнение `buildah` (обычно на хосте с `fuse-overlayfs` или `vfs`). + +--- + +### 📎 Рекомендации +- Используйте `BUILD_CACHE: ""` для включения кэширования в промышленных сборках. +- Храните кастомные `BUILD_ARGS` в переменных CI. +- Для продакшена используйте `retag` вместо пересборки. + +--- + +✅ **Назначение**: Современная, безопасная и гибкая альтернатива Docker-in-Docker (DinD) для сборки образов в CI/CD. +🔧 Подходит для GitLab CI, Kubernetes-раннеров, rootless-окружений и air-gapped систем. + +--- + +Вы можете вставить это описание в начало `.gitlab-ci.yml`: + +```yaml +# .gitlab-ci.yml +# +# === ПАЙПЛАЙН: Сборка образов через Buildah === +# +# Описание: +# Данный пайплайн использует Buildah для rootless-сборки и публикации... +# +# ... +``` + +Или сохранить как `docs/ci-buildah-pipeline.md`. \ No newline at end of file