Argo CD Diff Preview — инструмент для отображения различий (diff) между двумя ветками Git-репозитория. Он предназначен для рендеринга манифестов, генерируемых Argo CD, и даёт наглядное представление об изменениях между ветками. По принципу работы он похож на Atlantis для Terraform: создаёт план с описанием предлагаемых изменений.
Зачем это нужно?
В мире Kubernetes для генерации манифестов принято использовать шаблонизаторы — Kustomize и Helm. Они упрощают сопровождение конфигурации и её унификацию между приложениями и окружениями. Но они же затрудняют понимание того, какая конфигурация реально применяется в кластере.
Разбирать в уме шаблоны Helm и патчи Kustomize без рендеринга итогового результата крайне сложно. Поэтому ошибки при изменении конфигурации приложения случаются довольно легко.
В подходе GitOps и «инфраструктуры как кода» вся конфигурация хранится в Git и изменяется через Pull Request’ы. Человек, проводящий ревью, должен понимать, что именно изменилось. Когда конфигурация генерируется шаблонизаторами вроде Kustomize или Helm, сделать это значительно труднее.
Обзор
Использование эфемерных кластеров
Использование заранее настроенных кластеров
Самый надёжный способ вносить изменения в Helm-чарты и Kustomize-оверлеи в GitOps-репозитории — доверить рендеринг самому Argo CD. Это достигается запуском эфемерного кластера (или подключением к заранее настроенному) в рамках автоматизированных пайплайнов. Поскольку diff рендерит сам Argo CD, результат максимально точен.
Подробнее: Как это работает
Возможности
-
Точные диффы — манифесты рендерятся самим Argo CD, поэтому результат максимально достоверен
-
Полная изоляция — работает с эфемерными кластерами, доступ к реальному кластеру или экземпляру Argo CD не требуется
-
Подключение к установленному Argo CD — пропустите создание кластера и сэкономьте порядка 60–90 секунд на каждый запуск
-
Локальный запуск — проверяйте изменения до открытия Pull Request’а
-
Приватные репозитории и чарты — поддерживаются приватные Git-репозитории и Helm-чарты
-
Мультиисточниковые приложения — полная поддержка Argo CD multi-source apps
-
ApplicationSet — поддерживаются генераторы List, Git, Matrix, Merge и другие
-
Плагины управления конфигурацией (Config Management Plugins) — подключайте собственные CMP через конфигурацию Helm-чарта Argo CD
-
Видимость внешних чартов — наглядно видно, что изменилось при обновлении версии Helm-чарта (например, Nginx). Пример PR
-
Умная фильтрация — фильтруйте приложения по пути к файлу, регулярному выражению, меткам или по факту наличия изменений
-
Фильтрация шума в диффе — игнорируйте автоматические обновления версий, генерируемые значения и другие незначительные изменения с помощью
--diff-ignore -
Несколько форматов вывода — генерирует Markdown (для комментариев к PR), HTML и полные YAML-манифесты
-
Режим «сухого запуска» (dry run) — посмотрите, какие приложения будут отрендерены, без создания кластера
|
Совет
|
== Попробуйте демо локально — всего 3 команды! Сначала убедитесь, что Docker запущен. Например, выполните Затем выполните три команды: Вывод будет примерно таким: Наконец, просмотреть diff можно командой |
Базовое использование в GitHub Actions Workflow
Ниже приведён минимальный пример использования argocd-diff-preview в GitHub Actions. В этом примере инструмент запускается при каждом Pull Request’е в ветку main, а diff публикуется как комментарий к PR.
Пример работает только при условии, что Git-репозиторий публичный и вы используете публичные Helm-чарты. Если репозиторий или чарты приватные, необходимо передать инструменту соответствующие учётные данные. Подробнее см. в полной документации.
# .github/workflows/generate-diff.yml
name: Argo CD Diff Preview
on:
pull_request:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
path: pull-request
- uses: actions/checkout@v4
with:
ref: main
path: main
- name: Generate Diff
run: |
docker run \
--network=host \
-v /var/run/docker.sock:/var/run/docker.sock \
-v $(pwd)/main:/base-branch \
-v $(pwd)/pull-request:/target-branch \
-v $(pwd)/output:/output \
-e TARGET_BRANCH=refs/pull/${{ github.event.number }}/merge \
-e REPO=${{ github.repository }} \
dagandersen/argocd-diff-preview:v0.2.11
- name: Post diff as comment
run: |
gh pr comment ${{ github.event.number }} --repo ${{ github.repository }} --body-file output/diff.md --edit-last || \
gh pr comment ${{ github.event.number }} --repo ${{ github.repository }} --body-file output/diff.md
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}Приложения ArgoCD, генерируемые через Helm/Kustomize
argocd-diff-preview ищет в репозитории YAML-файлы с kind: Application или kind: ApplicationSet. Если ваши приложения генерируются из Helm-чарта или Kustomize-шаблона, необходимо добавить в пайплайн шаг рендеринга чарта/шаблона. Подробнее см. в полной документации.
Другие системы контроля версий
Если вы используете GitLab, Bitbucket, Jenkins, CircleCI или любой другой инструмент — всё должно работать. Однако документация для них может отсутствовать, поскольку всё, что выходит за рамки GitHub-документации, создаётся силами сообщества. Если вам удалось настроить интеграцию с каким-то инструментом, которого нет в документации, — поделитесь своим опытом с сообществом ❤️
Ускорение процесса рендеринга
Вместо запуска эфемерного кластера при каждом предпросмотре диффа можно подключиться к кластеру с уже установленным Argo CD. Это экономит примерно 60 секунд на каждый запуск. Подробнее — в документации.
Рендеринг манифестов для всех приложений в репозитории при каждом PR может занимать значительное время, особенно в больших монорепозиториях. По умолчанию argocd-diff-preview рендерит все найденные приложения, однако можно существенно ускорить процесс, ограничив набор обрабатываемых приложений. Подробнее — в разделе Application Selection документации.
Полная документация
Статьи в блоге
Доклады
ArgoCon NA 2024
argocd-diff-preview был представлен на ArgoCon 2024 в Солт-Лейк-Сити, США. Доклад охватывал существующие инструменты и методы визуализации изменений кода в GitOps-процессах и знакомил с новым подходом: использованием эфемерных кластеров для точного рендеринга диффов прямо в Pull Request’ах.
-
Описание доклада: GitOps Safety: Rendering Accurate ArgoCD Diffs Directly on Pull Requests
-
Запись доклада: YouTube
ArgoCon EU 2026
argocd-diff-preview будет представлен на ArgoCon EU 2026 в Амстердаме, Нидерланды. Доклад покажет, как сократить время предпросмотра с минут до секунд за счёт подключения к заранее настроенному экземпляру Argo CD вместо запуска эфемерных кластеров. Включает реальные примеры из практики компаний Egmont и TangoMe.
-
Описание доклада: Argo CD: Previewing Pull Request Changes in SECONDS!
Все контрибьюторы
История звёзд
Участие в разработке
Мы рады любому вкладу в ArgoCD Diff Preview — будь то исправление ошибок, добавление новых возможностей или улучшение документации.
Ознакомьтесь с руководством по участию в разработке: там описано, как настроить окружение, запустить тесты и отправить изменения.
Вопросы, проблемы, предложения
Если вы столкнулись с проблемой или у вас есть вопросы или предложения — откройте issue в этом репозитории! 🚀