пайплайны и хуки в git

Представим идеальную ситуацию: я не только девопс, но и проектный менеджер, выбираю не только архитектуру проекта, но и инструменты, и команду разрабов, т.е. полный контроль над проектом. В жизни такое вряд ли встретишь, но нам, для примера, это нужно чтобы сравнить какие есть варианты.

Первый, классический пайплайн - это утилита make. Обычно она используется для сборки программ из исходного кода. На самом деле make хорошо подходит для решения сразу нескольких задач. Первая задача - отслеживание зависимостей одних файлов от других, например, при изменении сервиса пересобрать только соответствующий контейнер. Вторая задача, легко реализуемая через make - собрать в один файл много команд или скриптов, удобно их организовать. Как правило, сборка образа, его загрузка в репо, удаление временных файлов, и прочее, делается несколькими рутинными командами. Точно также можно поместить в Makefile команды запуска сервисов, тестирование приложения локально. Если эти этапы прошли успешно, можно выполнить коммит кода в репо проекта, сделать деплой в dev или stage environment. В github actions это называется jobs и steps, в make такая группа команд называется целью, она указывается параметром при вызове. Итого, несмотря на разную терминологию, по сути можно создать полноценный пайплайн для современного проекта с контейнеризованными сервисами.

Возьмём для примера проект с прокси сервером traefik и бэкендом на golang из репозитария awesome-pods. Этот репо задуман как форк замечательного проекта awesome-compose, в котором собраны конфиги docker compose для 41 самых популярных сервисов. Я же пытаюсь сделать что-то похожее для манифестов podman. Приглашаю к сотрудничеству начинающих девопс - сможете поучаствовать в открытом проекте, заработать почётные гитхаб бейджи, резко улучшить своё резюме. Подробности в CONTRIBUTING.md.

Мой проект в интересном положении - сделаны манифесты для нескольких сервисов, опробованы описанные выше подходы для миграции конфигов compose.yaml в манифесты kube.yaml. Но захотелось большего: а почему бы не сделать сразу пайплайны для тестирования, коммита в апстрим, деплоя и проч. Зайдём в каталог traefik-golang и создадим пару мейк-файлов. Для начала сделаем всё это локально, начнём с make_compose:

... $ cat make_compose
.PHONY: help build up down stop restart logs test ps stats shell
help:
       @echo "make_compose avalable targets:\n"
       @make -pRrq 2>/dev/null|grep -v ^Makefile|grep -P '^\w+:'|sort
build:
       docker compose build
up:
       docker compose up -d
down:
       docker compose down -v
stop:
       docker compose stop
restart:
       docker compose stop
       docker compose up -d
logs:
       docker compose logs
test:
       curl localhost:8080
ps:
       docker compose ps -a
stats:
       docker compose stats --no-stream
shell:
       docker exec -ti traefik /bin/sh

Этот файл уже в истории, равно как и сооветсвующий README.md, привожу его для примера. Т.к. я делаю конфиги сразу для 2 платформ - docker и podman, для включения соответствующего Makefile’а надо сделать линк на него: ln -s make_compose Makefile. Отлично, основную идею обсудили, идём дальше. В docker’е есть замечательная опция context, позволяющая работать с любыми серверами, где настроен доступ. В нашем случае список контекстов выглядит так:

... $ docker context ls
NAME            DESCRIPTION                               DOCKER ENDPOINT                                  ERROR
deb12fri        vm on https://cloud.ru                    ssh://deb12fri                                   
default         Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                      
desktop-linux   Docker Desktop                            unix:///home/ophil/.docker/desktop/docker.sock   
fc42dev *       libvirt vm fc42dev                        ssh://dev@fc42dev
localhost       localhost for make_compose pipeline       unix:///var/run/docker.sock

Здесь я использовал простейший хак - сделал копию дефолтового контекста с именем localhost. Теперь мы можем сделать наш пайплайн способным на удалённый деплой, достаточно прописать в /etc/hosts имя и адрес нашего dev сервера. Вот новая версия make_compose:

... $  nl make_compose
.PHONY: help build up down clean commit stop restart logs test ps stats shell
ifndef DKR_CONTEXT
  DKR_CONTEXT = localhost
  endif
help:
        @echo "make sure you in proper docker context: ${DKR_CONTEXT}"
        docker context use ${DKR_CONTEXT}
        docker context ls 
        @echo "make_compose avalable targets:"
        @make -pRrq 2>/dev/null|grep -v ^Makefile|grep -P '^\w+:'|sort
build: main.go make_compose
        docker compose build
up: build down
        docker compose up -d
clean:
        docker system prune -f
commit: test
        git branch -v
        @read -p "Enter commit message:" mesg;\
        git commit -am "$$mesg"
        git push
down:
        docker compose down -v
stop:
        docker compose stop
restart:
        docker compose stop
        docker compose up -d
logs:
        docker compose logs
test:
        curl ${DKR_CONTEXT}:8080
ps:
        docker compose ps -a
stats:
        docker compose stats --no-stream
shell:
        docker exec -ti traefik /bin/sh

Поясню немного подробнее. Самая первая строка : стандартное отъявление списка целей. Строки 2-4 задают дефолтовое значение переменной, если оно не задано в текущем env. В хелп, строки 5-10, добавлено предупреждение о текущем контексте, он задаётся в глобальной переменной, напр. export DKR_CONTEXT=localhost для локального контекста. Также добавлена цель commit в репо, строки 17-21, после выполнения цели test. Test, строки 31-32, в свою очередь, выполняется для текущего контекста, см. хак #1, имя контекста должно совпадать с именем хоста нашего dev-сервера. Добавлена также цель clean: очистка старых образов с локальном репо, и зависимости в цель up: убедиться, что образ пересобран и старые контейнеры остановлены.

Отлично, пайплайн для докера работает. Пробуем сделать то же самое для подмана. Здесь нас ждёт сюрприз, попробую рассказать в стиле прямого репортажа. Первоначально наш пайплайн для podmanа выглядел вот так:

... $ nl make_pods 
.PHONY: help up clean down logs test ps stats shell
help:
       @echo -e "make_pods avalable targets:\n"
       @make -pRrq 2>/dev/null|grep -v ^Makefile|grep -P '^\w+:'|sort
back: main.go make_pods
       -buildah rm backend
       buildah from --name backend scratch
       CGO_ENABLED='0' go build -v -ldflags "-w -s" -o back main.go
       buildah copy backend back /usr/local/bin/backend
       buildah config --entrypoint '["/usr/local/bin/backend"]' backend
       buildah commit backend backend:latest
clean:
       podman system prune -f
down:
       envsubst < kube.yaml | podman kube down -
up: down
       envsubst < kube.yaml | podman kube play -
logs:
       podman pod logs go-app
test:
       curl localhost:8080
ps:
       podman ps -ap
stats:
       podman stats --no-stream
shell:
       podman exec -ti go-app-traefik /bin/sh

В строке 5 определяются зависимости: target back соберёт исполняемый файл только в том случае, если код main.go или сам make_pods новее уже собранного бинарника.

Строка 6 удаляет backend контейнер с едва заметным знаком минус -, чтобы игнорировать ошибку, если контейнер с именем бэкенд не существует.

Строки 7–10 создают контейнер с именем backend из пустого (scratch) контейнера — команды buildah следуют обычным командам Dockerfile, но в нижнем регистре: FROM -> from, COPY -> copy, RUN -> run, ENTRYPOINT -> config –entrypoint и т. д. Здесь вы видите основное отличие от традиционного docker buildx подхода — вы работаете в двух контекстах одновременно, в локальном контексте, используя установленный компилятор go, и в контексте контейнера, копируете файлы в/из контейнера, запускаете команды внутри контейнера и т. д. Другая новая возможность buildah - вы можете собирать образ шаг за шагом, т. е. отлаживать процесс сборки.

Строка 8 компилирует main.go в исполняемый файл back с соответствующими флагами.

Строка 11 создаёт из контейнера новый образ (image) с тегом backend:latest.

Цель up, строка 16, зависит от цели down, строка 14, то есть она сначала останавливает pod и удаляет контейнеры, если они всё ещё запущены, затем запускает новый под.

Цель down в строке 15 подставляет глобальную переменную $XDG_RUNTIME_DIR из env пользователя в kube.yaml, используемый далее в podman kube командах, принимая новый манифест со стандартного ввода. Это также специфика podman — он работает полностью в пространстве пользователя, контейнеры взаимодействуют через собственный podman.sock. Таким образом делаем пайплайн независимым от UID.

В подмане есть фунциональность наподобие docker context, под другим именем, в подкоманде system connection:

$ podman system connection add --identity ~/.ssh/id_ed25519 --port 22 fc41dev dev@fc41dev
$ podman system connection list
Name        URI                                                          Identity                     Default
fc42dev     ssh://dev@fc42dev:22/run/user/1001/podman/podman.sock        /home/ophil/.ssh/id_ed25519  true
proba       ssh://[email protected]:37973/run/user/1000/podman/podman.sock  /home/ophil/.ssh/proba       false
proba-root  ssh://[email protected]:37973/run/podman/podman.sock            /home/ophil/.ssh/proba       false

Первым в списке стоит настроенная в прошлой статье ВМ. Пока искал правильные опции для создания коннекшена (aka контекст в докере), столкнулся с подсказкой от подмана, мол, создайте сначала машину, а именно:

$ podman system df
Cannot connect to Podman. Please verify your connection to the Linux system using
"podman system connection list", or try "podman machine init" and "podman machine start"
to manage a new Linux VM

Выполнил эти рекомендации, подман выкачал, настроил и добавил 2 новых коннекшена для новой ВМ. Какой же меня ждал сюрприз, когда я стал смотреть что же это за machine. Во-первых, в моём HOME появились новые файлы и каталоги:

$ ll ~/.ssh/proba*
-rw------- 1 ophil ophil 399 Apr 25 16:59 /home/ophil/.ssh/proba
-rw-r--r-- 1 ophil ophil  94 Apr 25 16:59 /home/ophil/.ssh/proba.pub
$ tree /home/ophil/.config/containers/podman/
/home/ophil/.config/containers/podman/
└── machine
    └── qemu
        ├── proba.ign
        ├── proba.json
        └── proba.lock

3 directories, 3 files
$ tree /home/ophil/.local/share/containers/podman
/home/ophil/.local/share/containers/podman
└── machine
    └── qemu
        ├── cache
        │   └── fedora-coreos-42.20250410.2.1-qemu.x86_64.qcow2.xz
        ├── podman.sock
        └── proba_fedora-coreos-42.20250410.2.1-qemu.x86_64.qcow2

4 directories, 3 files

Во-вторых, это полноценная ВМ fedora coreos:

$ podman machine ssh proba head /etc/os-release
NAME="Fedora Linux"
VERSION="42.20250410.2.1 (CoreOS)"
RELEASE_TYPE=stable
ID=fedora
VERSION_ID=42
VERSION_CODENAME=""
PLATFORM_ID="platform:f42"
PRETTY_NAME="Fedora CoreOS 42.20250410.2.1"
ANSI_COLOR="0;38;2;60;110;180"
LOGO=fedora-logo-icon
$ podman machine ssh proba sudo dmesg|head -2
[    0.000000] Linux version 6.14.0-63.fc42.x86_64 (mockbuild@d5701c6d040c430c8283c8c9847dc93f) (gcc (GCC) 15.0.1 20250228 (Red Hat 15.0.1-0), GNU ld version 2.44-3.fc42) #1 SMP PREEMPT_DYNAMIC Mon Mar 24 19:53:37 UTC 2025
[    0.000000] Command line: BOOT_IMAGE=(hd0,gpt3)/boot/ostree/fedora-coreos-5d67a1bf86573c8e67b45ca2e1c1bde3a618c688ea15e69053c8b88695b1a8e4/vmlinuz-6.14.0-63.fc42.x86_64 rw mitigations=auto,nosmt ostree=/ostree/boot.1/fedora-coreos/5d67a1bf86573c8e67b45ca2e1c1bde3a618c688ea15e69053c8b88695b1a8e4/0 ignition.platform.id=qemu console=tty0 console=ttyS0,115200n8 root=UUID=297242c0-0f78-47fe-9161-0ac28761bdc0 rw rootflags=prjquota boot=UUID=553bd753-07f8-4dd3-b3bd-5c0605bdae3f

Конечно, приятно, что моё мнение совпало с мнением авторов подмана, точнее, со стратегией RedHat - fedora coreos наиболее подходящая система для контейнерных приложений. С другой стороны, ВМ в подмане крутится полностью внутри пространства пользователя, у меня уже настроена почти такая же для удалённой работы всей команды разрабов. Решено, останавливаем новую виртуалку и правим мейкфайл для подмана по образцу компоуза, делаем пайплайн для деплоя и локально, и на удалённый дев. сервер.

Но прежде нам понадобится ещё один хак #2. Если в случае докера переключение контекста можно было сделать любой переменной, то для подмана между локальным, через сокет, соединением, и удалённым, через uri:ssh, имя переменной фиксировано CONTAINER_HOST. Вот как выглядит пайплайн make_pods.v1, настроенный и для локальной сборки, и для деплоя в наш дев. сервер:

... $ nl make_pods.v1 
.PHONY: help up back commit test clean down logs ps stats shell
vshell = /bin/sh -c
vhost = localhost
workdir = ${HOME}/src/traefik-golang
ifdef CONTAINER_HOST
  vshell = ssh dev@fc42dev
  vhost = fc42dev
  workdir = /home/dev/src/traefik-golang
  endif
help:
        @echo "make sure you are in proper podman system connection : ${CONTAINER_HOST}\n"
        podman system connection list
        @echo "make_pods avalable targets:\n"
        @make -pRrq 2>/dev/null|grep -v ^Makefile|grep -P '^[\w-]+:'|sort
        @echo "make vars: ${vshell} ${vhost} ${workdir}"
back: main.go make_pods
        podman build . -t backend
down:
        ${vshell} 'cd ${workdir} ; envsubst < kube.yaml | podman kube down -'
up: down
        ${vshell} 'cd ${workdir} ; envsubst < kube.yaml | podman kube play -'
test:
        curl ${vhost}:8080
clean:
        -rm back
        podman system prune -f
commit: test
        git branch -v
        git add .
        @read -p "Enter commit message:" mesg;\
        git commit -m "$$mesg"
        git push
logs:
        podman pod logs go-app
ps:
        podman ps -ap
stats:
        podman stats --no-stream
shell:
        podman exec -ti go-app-traefik /bin/sh

По большей части цели мейкфайла остались теми же, но для удалённого деплоя настраиваем переменную export CONTAINER_HOST=ssh://dev@fc42dev:22/run/user/1001/podman/podman.sock - берём её из коннекшена, она служит переключателем между локальным и удалённым контекстом. Для локального контекста эту переменную надо удалить: unset CONTAINER_HOST. Команды в строках 19, 21 и 23: это обычные команды шелла, они также меняются на локальное либо удалённое исполнение, переопределяются на основе этой же переменной CONTAINER_HOST.

Как заметил внимательный читатель, в цели back исчезла сборка контейнера утилитой buildah. Как и для docker compose, используется возможность самого подмана создавать образы на основе Containerfile, он же Dockerfile, эти названия синонимы. Это намёк - пора отвыкать от слова докер, контейнеры уже давно стали основой облачных вычислений, для них созданы сотни приложений, см. например, CNCF, и общепризнанные стандарты.

Для дальнейшего рассказа хочу обсудить принципиальный вопрос о контейнерах. Основное их преимущество - новый способ доставки приложений в облака, решение проблем с зависимостями, версиями библиотек, фреймворков и проч. Сборка контейнеров в контейнерах - это побочный эффект облачных сервисов - гитхаба, гитлаба, других похожих, с одной стороны, и ограничения докера с другой. Он не умеет, в отличие от подмана, точнее, от его сопутствующей утилиты buildah, выполнять билд и создавать образ, используя локальное окружение.

Основная проблема сборки образа внутри контейнера - неэффективное использование кэша. Да, появились возможности как-то сохранять объемные загрузки внешних библиотек, модулей: это опции --mount=type=cache для некоторых языков. Но, во-первых, эти возможности используются далеко не всегда. Во-вторых, опции для кэширования отличаются в podman и buildah, см. podman-build(1), придётся делать отдельный Containerfile. В-третьих, эффект от такого кэширования минимален. Предлагаю замерить время сборки, сделав ещё одну, 3-ю версию пайплайна. Сначала соберём команды для buildah в отдельный файл:

... $ nl buildah.cmd 
cd $HOME/src/traefik-golang
buildah rm backend
buildah from --name backend scratch
CGO_ENABLED='0' go build -v -ldflags "-w -s" -o back main.go
buildah copy backend back /usr/local/bin/backend
buildah config --entrypoint '["/usr/local/bin/backend"]' backend
buildah commit backend backend:latest

и поправим пару строк в пайплайне:

... $ diff make_pods.v{1,2}
16,17c16,17
< back: main.go make_pods.v1
<       podman build . -t backend
---
> back: main.go make_pods.v2 buildah.cmd
>       ${vshell} 'cd ${workdir} ; . ./buildah.cmd'

Уточню условия нашего эксперимента - мы настроили одинаковую среду разработки с помощью утилиты mise, см. предыдущую статью, и на нашем дев. сервере, и у каждого из разрабов команды. Репозитарий git использует этот же дев. сервер, доступ к репо и серверу по ключу, парольный доступ закрыт. Пайплайны настроены как для локальной сборки, так и на дев. сервере. Перед запуском 3-й версии пайплайна на дев. сервере нужно сделать коммит изменений в репо - buildah не знает о коннекшенах, работает с кодом в текущем каталоге, см. строку 1: после логина на сервер сначала переключается в корень проекта. Преварительно выкачиваем образ компилятора go для сборки в контейнере - это вполне честно, мы же выкачали и настроили компилятор golang заранее. Замеряем:

rm Makefile ;ln -s make_pods.v1 Makefile
time make back
...
real    0m15.328s user  0m28.341s sys   0m6.315s

rm Makefile ;ln -s make_pods.v2 Makefile
time make back
...
real    0m1.301s user   0m0.754s sys    0m0.917s

rm Makefile ;ln -s make_compose Makefile
time make build
...
real	0m13.429s user	0m0.177s sys	0m0.142s

Мы получили 10+ кратный выигрыш по времени сборки образа для подмана. Абсолютные времена не важны, так же не влияет, запускали мы сборку локально или на дев. сервере, мы сравниваем только билд в контейнере и в настроенном локальном окружении. Третье время сборка в докере, он умеет собирать только в контейнере, для него кэширование в Containerfile было настроено:

$ grep ^RUN Containerfile 
RUN --mount=type=cache,target=/go/pkg/mod CGO_ENABLED=0 go build -v -ldflags "-w -s" -o backend main.go

но оно не сильно помогло. Конечно, наш проект игрушечный, golang кэширует лучше других языков, но в целом вывод понятен - сборка в контейнере далеко не оптимальный вариант если есть возможность настроить дев. сервер для работы команды. Ещё замечание - конечно, образы, собираемые buildah совместимы с докером, их можно использовать в конфигах compose.yaml. Но для этого надо настроить репозитарий образов и сначала загрузить образ в него. Локальные репозитарии отличаются, докер использует общий репо для всех пользователей, т.н. Docker Root Dir: /var/lib/docker, в подмане всё хранится в домашнем каталоге пользователя, graphRoot: /home/$USER/.local/share/containers/storage

Как я предположил в самом начале, мы попробовали вариант с гипотетической идеальной командой разрабов, работающей в Линукс, умеющей в make. А как быть обычному девопсу с разношерстой командой, где кто-то сидит под виндой, а кто-то ни за что не откажется от привычного Макбука с M4 процем?? Есть вариант и для этого случая. Пусть они пишут код и тестируют его как им нравится, а в нашем репо на дев. сервере мы сделаем хак #3, а именно гит хук и т.н. bare репозитарий, см. githooks(5), выполняющий наши цели сборки и старта приложения при коммите в репо.

Для этого нам на пару минут придётся стать безжалостным хакером, удаляющим лишнее, открывающим скрытые возможности гита. Выполняем следующие шаги:

заходим под юзером dev на сервер, создадим пустой каталог, напр., mkdir -pv ~/bare/t0. Это станет новым GIT_DIR, зайдём в него и выполним cd ~/bare/t0;git init --bare
видим, что файлы, обычно спрятанные в каталоге .git, лежат прямо в корне. Сделаем дополнительно каталог для логов mkdir logs. Переходим в каталог hooks и создаём файл, где укажем команды выполнения при каждом изменении в репо.

... $ nl hooks/post-receive 
#!/bin/sh
#  local git build
# set -x
WORK_TREE="/var/home/dev/src/traefik-golang"
GIT_DIR="/var/home/dev/bare/t0"
while read oldrev newrev ref
do
  # echo "oldrev newrev ref:" $oldrev $newrev $ref
  # pwd;env|sort;ls -l $WORK_TREE
  x_br=$(echo $ref|cut -d/ -f3)
  git --work-tree=$WORK_TREE --git-dir=$GIT_DIR checkout -f $x_br
  LOGFILE=$(date +%y%m%d_%H%M).${x_br}.log
  (cd $WORK_TREE && make back && make up && make test && make clean)|tee -a logs/$LOGFILE
done

Закомментированные строки 3, 8, 9 полезны при отладке пайплайна. Строки 4 и 5 задают, что есть собственно репозитарий, переменная GIT_DIR, и куда будут записываться файлы проекта, переменная WORK_TREE. В цикле от строки 6 до 14 читаются и обрабатываются 3 переменных, с которыми гит вызывает этот хук. Строка 11 принимает все изменения в репо и обновляет WORK_TREE, всё то, что гит обычно делает в общем каталоге, как видим, в bare репо они разные. Далее, в 12 строим имя лога и строка 13 - собственно пайплайн.

идём в каталог где расположен репо проекта - без страха и сожаления удаляем старый и создаём новый под тем же именем: cd ~/src;rm -rf traefik-golang;mkdir traefik-golang
завершаем сессию на дев. сервере, возвращаемся на рабочий комп и заходим в репо проекта. Конечно же, репо цел, клоны репо не так просто уничтожить пока есть хотя бы одна копия. Теперь см. старые настройки git remote -v и их удаляем git remote remove fc42dev в моём случае. Создаём новый remote, указывая новый гит bare репо: git remote add bare.t0 dev@fc42dev:~/bare/t0. Это надо сделать также всем разрабам в их локальных копиях.
проверям результат, возможно, надо сделать новый комит и push в новый remote. СтОит посм. подробнее, как изменился репо проекта на сервере: проверить логи в ~/bare/t0/logs, сравнить конфиги обычного репо проекта и на сервере, проверить какие команды перестали работать в серверном репо. Например, в WORK_TREE не работают команды гит status; branch; commit; log. Т.е. наш хак #3 с git --bare не только позволил делать деплой на сервере, но также защитил репо от локальных изменений, серверный репо всегда в чистоте и порядке. Можно редактировать код, но закомитить его можно только через обычный репо, изменения на сервере удалятся после любого коммита.

Надеюсь, мне удалось показать, что пайплайны можно делать на основе древней забытой утилиты make. В следующей статье разберём как можно добавить в наш скромный дев. сервер нечно похожее на монстров гит-сервисов, гитлаба и гитхаба, создавать пайплайны, совместимые с github Actions, предоставить команде разрабов привычный интерфейс репо в браузере.

blog

О программировании и не только

пайплайны и хуки в git

вернуться обратно в блог