Add pipline/docker_build/readme.MD
This commit is contained in:
parent
a4c9d0092a
commit
4eb613fdb8
188
pipline/docker_build/readme.MD
Normal file
188
pipline/docker_build/readme.MD
Normal file
@ -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`.
|
||||
Loading…
x
Reference in New Issue
Block a user