devops/pipline/docker_build/readme.MD

---

📝 Описание пайплайна: Сборка и ретегирование 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-шаблоны

.buildah_info: &buildah-info
  - until buildah --version; do sleep 1; done

Проверяет доступность Buildah (полезно при старте контейнера).

.buildah_login_stdin_base64: &buildah-login-stdin-base64
  - echo "$REGISTRY_PASSWORD" | base64 -d | buildah login -u $REGISTRY_USER $REGISTRY --password-stdin

Безопасный вход в реестр: пароль в base64-кодировке, не попадает в логи напрямую.

.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)

.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.

.buildah_retag: &buildah-retag
  - buildah pull $SOURCE_IMAGE
  - buildah tag $SOURCE_IMAGE $TARGET_IMAGE
  - buildah push $TARGET_IMAGE

Ретегирование: скачивает существующий образ и выставляет новый тег (например, для релизов или продакшена).

.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)
• Тегирование по тегу релиза:

  Если 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

# Образ: registry/app:develop
# Сборка с --no-cache
# Без тега latest

✅ Сборка при теге v2.1.0

# Образ: registry/app:v2.1.0
# Не влияет на latest

✅ Сборка в main → обновление :latest

# Образ: registry/app:main + registry/app:latest

✅ Ретегирование (ручной запуск)

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:

# .gitlab-ci.yml
#
# === ПАЙПЛАЙН: Сборка образов через Buildah ===
#
# Описание:
#   Данный пайплайн использует Buildah для rootless-сборки и публикации...
#
# ...

Или сохранить как docs/ci-buildah-pipeline.md.