app_image: добавлена роль (сборка и доставка docker-образа)

2026-07-24 18:47:39 +03:00
parent aca0d03772
commit db72932f0d
5 changed files with 217 additions and 0 deletions
@@ -0,0 +1,72 @@
+# app_image
+
+Собирает docker-образ приложения **локально** (на control-хосте) и доставляет
+его на сервер через `docker save`/`load`. Тулчейн сборки (Go, node, …) на
+сервере не нужен — туда едет готовый образ.
+
+Роль — первый кирпичик деплоя: её задача, чтобы на сервере оказался образ
+`<app_image_name>:<tag>`. Запуском приложения (рендер config и docker-compose,
+`docker compose up`) занимается остальная часть плейбука — позже это может стать
+отдельным кирпичиком.
+
+Тег образа — случайный `BUILD_ID`, который роль генерит на каждый прогон.
+Дедупликации по содержимому нет: каждый деплой везёт образ и пересоздаёт
+контейнер. Для ручного нечастого деплоя это осознанный выбор — простота важнее
+экономии одного рестарта.
+
+## Контракт с приложением
+
+Приложение реализует **команду сборки образа** в своей рабочей директории.
+Роль — инициатор: она вызывает эту команду и передаёт ей случайный `BUILD_ID`
+через окружение. Команда обязана собрать **полный** образ и затегать его
+`<app_image_name>:$BUILD_ID`.
+
+Пример реализации на Taskfile (тег из `$BUILD_ID`, по умолчанию `dev`):
+
+```yaml
+image:
+  desc: 'Полный docker-образ. Тег из $BUILD_ID (по умолчанию dev).'
+  deps: [build]
+  cmds:
+    - docker build -t {{.BINARY}}:${BUILD_ID:-dev} .
+```
+
+`${BUILD_ID:-dev}` держит команду обратно совместимой: `task image` без
+переменной по-прежнему собирает `<app>:dev` для локальной работы.
+
+## Как работает
+
+1. Роль генерит случайный `BUILD_ID` — это же и есть `app_image_tag`.
+2. Гоняет `app_image_command` в `app_image_src_dir` → приложение собирает
+   `<app_image_name>:$BUILD_ID`.
+3. `docker save` образа → копирует tar на сервер → `docker load`.
+4. Отдаёт факт `app_image_tag`, чистит локальный тег и оба tar-файла.
+
+Локальный тег на control-хосте снимается по завершении (образ уже на сервере).
+Старые образы на сервере подчищает `docker image prune -af` по крону (см.
+`playbook-system.yml`).
+
+## Переменные
+
+| Переменная | Обязат. | По умолчанию | Назначение |
+|---|---|---|---|
+| `app_image_name` | да | — | имя приложения; под ним тегается и живёт образ |
+| `app_image_src_dir` | да | — | рабочая директория приложения на control-хосте |
+| `app_image_command` | нет | `task image` | команда сборки образа (контракт); одна команда через `command`, без shell-синтаксиса |
+
+## Выход
+
+- Факт **`app_image_tag`** — тег доставленного образа (= `BUILD_ID`).
+- На сервере — образ `<app_image_name>:<app_image_tag>`.
+
+## Пример
+
+```yaml
+- name: 'Build and deliver application image'
+  ansible.builtin.import_role:
+    name: app_image
+  vars:
+    app_image_name: 'jellybit'
+    app_image_src_dir: '{{ (playbook_dir, "..", "jellybit") | path_join }}'
+# далее compose-роль использует app_image_tag
+```