Предисловие:
Добрый день всем, кто читает эту статью. Меня зовут Минисламов Руслан. Я работаю DevOps инженером и в этой статье хотел бы рассказать и показать как подключать плагины к такому инструменту как ArgoCD и автоматизировать установку приложений в k8s.

Вступление:
В этой статье я буду использовать стандартные для Argo CD выражения (например, Application), а также другие сущности Kubernetes, подразумевая, что вы либо уже знакомы с ними, либо сможете самостоятельно изучить их по документации. Код и команды используемые в статье будет выложен в репозиторий, ссылка в конце статьи.
В ArgoCD есть сущность Config Management Plugins (CMP) которые позволяют заменить стандартный движок рендеринга манифестов на удобный вам . В этой статье я поделюсь опытом настройки собственного стенда и расскажу о двух интересных подходах к управлению Helm-чартами: Helmfile и Helmwave. Оба инструмента решают схожие задачи, но имеют принципиальные различия в идеологии, которые важно понимать при выборе.

Config Management Plugins: архитектура и заблуждения

Что такое Config Management Plugin - это механизм в Argo CD, который позволяет расширять его возможности: генерировать Kubernetes-манифесты из источников, не поддерживаемых «из коробки» (Helm, Jsonnet, Kustomize). С его помощью можно интегрировать любые инструменты для работы с конфигурацией. Я прикрепил ниже скриншот с офф. сайта. Если так посмотреть, можно подумать что это очередной Custom Resource Definition(CRD) .

Но это не так, на самом деле такого CRD нет, если ввести kubectl get configmanagementplugin -n argocd мы получим ошибку error: the server doesn’t have a resource type “configmanagementplugin”, на самом деле можно подумать что после установки argocd вы могли забыть активировать переменную в values.yaml и даже если открыть и сделать беглый поиск, мы увидим следующее у нас по умолчанию значение false, но даже если вы переведете значение в true и выполните helm upgrade --install argocd и повторно введете kubectl get configmanagementplugin -n argocd у Вас все равно будет ошибка, все потому что у нас есть простой комментарий ConfigMap for Config Management Plugins.

Но это не так. На самом деле если активируете в true такой CRD не появится. Ответ кроется в комментарии, это обычный ConfigMap где описываем сущность для ArgoCD, напоминает когда мы через ConfigMap монтируем например в nginx конфиг. Вот пример CMP для ArgoCD.

Приступим к установке ArgoCD. Установить его можно несколькими способами, я предпочитаю helm. Вот переменные с которыми я производил установку, подробнее о них я расскажу ниже.

helm repo add argo https://argoproj.github.io/argo-helm
helm upgrade --install argocd argo/argo-cd -n argocd --create-namespace -f argocd-custom-values.yaml

На что стоит обратить внимание в файле argocd-custom-values.yaml и чего там нет

initContainers
Используется для загрузки исполняемых файлов Helmfile и Helmwave в общую директорию /helm-bin, которая затем монтируется в основной и sidecar-контейнеры.
extraContainers (sidecar)
Добавляется дополнительный контейнер, запускающий argocd-cmp-server. Он эмулирует поведение основного repo-server и взаимодействует с ним по gRPC. Именно этот контейнер обрабатывает плагины, на которые ссылается поле plugin в объекте Application.
Логирование
На уровне global.logging установлен debug — для отладки, в проде следует выставить на свое усмотрение.
Лимиты ресурсов
Установите resources : падение по OOM предпочтительнее неконтролируемого потребления памяти.

Управление конфигурацией плагинов через ConfigMap

После применения Helm-чарта развёртывание argocd-repo-server не запустится, если отсутствует ConfigMap, на который мы ссылаемся в volumes. Я предпочитаю создавать ConfigMap с определением CMP отдельно, а не через values-файл. Причины:

Обновление плагина не требует переустановки/апгрейда Helm-чарта.
В пайплайнах CI/CD (например, GitLab) проще применить kubectl apply -f cmp-config.yaml и выполнить рестарт, чем пересобирать релиз Helm.
Откат изменений выполняется быстрее: достаточно восстановить предыдущую версию ConfigMap и перезапустить repo-server.

Важные нюансы при работе плагинов

При работе с CMP необходимо учитывать поведение repo-server:

Sidecar-контейнер генерирует манифесты, а основной repo-server выполняет их повторную валидацию.
Любые артефакты, попавшие в выходной поток (например, отладочные echo или комментарии), могут быть признаны невалидными и отклонены.
В процессе отладки часто приходится править скрипт генерации в ConfigMap и перезапускать repo-server.

Совет: всегда проверяйте выходные данные плагина на наличие лишних символов или строк, не соответствующих стандартному YAML-представлению Kubernetes-объектов.

Установка CMP

В репозитории представлены три варианта реализации CMP-плагинов, каждый из которых демонстрирует различные подходы к интеграции Helmfile и Helmwave с Argo CD. Рассмотрим их особенности, требования к безопасности и практические нюансы эксплуатации, вы можете применить любой из 3х. В первом код для плагинов helmfile-plugin и helmwave-plugin, тут важно обратить внимание, что для helmwave-plugin требуется еще создавать ClusterRole и используя ClusterRoleBinding привязать к SA который создается при установке ArgoCD. Второй и третий пример созданы для сравнения, какой из них применять решать вам, не забудьте только про rbac, его я в одном скрипте прописал. Дождитесь старта всех контейнеров.

Затем применяем последние команды

kubectl apply -f argocd-plugin/application.yaml

После того как вы залогинетесь в ArgoCD вы увидите, что оба плагина заработали и приложения были развернуты в k8s

Helmwave: идеология и применение

Почему для helmwave требуется rbac возможно у Вас возник вопрос, а все потому что продукт построен так, сравнивает что установлено в кластере и что мы собираемся установить из-за этого у меня возникало много проблем с этим пока не готовым для прода продуктом по моему мнению.

Практические проблемы при использовании Helmwave

В процессе эксплуатации Helmwave выявлены следующие ограничения, которые важно учитывать при выборе инструмента:

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

В исходном чарте отсутствовали обязательные метки, необходимые для отслеживания состояния
Изменения требуют модификации ресурсов, которые Helmwave не может корректно обработать из-за отсутствия аннотаций управления

2. Чувствительность к состоянию кластера
Поскольку Helmwave сравнивает желаемую конфигурацию с фактическим состоянием в кластере, любой неконтролируемый change (например, ручное редактирование ресурсов) может привести к:

Некорректному определению изменений
Пропуску обновлений
Конфликтам при применении манифестов

Рекомендации по выбору

Рассмотрите Helmwave, если:

Проводите эксперименты и исследование новых подходов
Требуется интеграция с существующими helmwave.yml
Готовы мириться с потенциальными проблемами и участвовать в развитии инструмента

Helmfile: идеология и применение

Как ArgoCD нивелирует проблемы Helmfile

1. Без ArgoCD: Helmfile не видит ручных изменений в кластере, что приводит к дрейфу конфигурации. ArgoCD постоянно сравнивает желаемое состояние (из Git) с фактическим состоянием в кластере и автоматически исправляет дрейф.

Выбирайте Helmfile, если:

Требуется стабильное решение для production
Предпочитаете декларативный подход без привязки к состоянию кластера
Работаете с несколькими окружениями и нуждаетесь в гибком управлении конфигурациями
Используете стандартные подходы GitOps без необходимости чтения состояния из кластера
Множество примеров в интернете

Полезные команды для отладки

kubectl rollout restart deployment argocd-repo-server -n argocd
#Посмотреть какой скрипт в контейнере
kubectl exec -n argocd deployment/argocd-repo-server -c helmwave-cmp -- sh -c "cat /home/argocd/cmp-server/config/plugin.yaml"
kubectl exec -n argocd deployment/argocd-repo-server -c helmfile-cmp -- sh -c "cat /home/argocd/cmp-server/config/plugin.yaml"

# Проверка логов контейнера или конкретного sidecar контейнера
kubectl logs -n argocd deployment/argocd-repo-server
kubectl logs -n argocd deployment/argocd-repo-server -с helmfile-cmp
kubectl logs -n argocd deployment/argocd-repo-server -c helmwave-cmp

Ну и еще раз ссылка на репозиторий, там содержатся values с которыми производить установку или upgrade argocd, отдельные команды для регистрации CMP, а так же 2 разных helm chart и к ним по одному примеру helmfile.yaml и helmwave.yml.

Обратите внимание и разберите

values, необходимо понимать почему именно так например в CMP назван plugin, какой версии скачиваются пакеты или какой образ используется и как запускается дополнительный контейнер.
Скрипты с CMP, какой использовать, поэкспериментируйте и найдите тот что будет вам удобен и вы сможете понимать логи, потому как логи идут сплошным текстом, красивого yaml вы не увидите.
Пообновляйте образ или параметры в Helm Chart, в том же Helmwave вы сможете получить ошибки которые помогут возможно писать более правильные Helm Chart Вам.
Попробуйте теперь настроить ArgoCD с Vault если давно хотели подключить.
Попробуйте настроить Nelm от зарекомендовавшей себя на рынке компании Флант, инструмент похож на Helmfile и проблем с адаптацией возникнуть не должно.

Расширяем границы ArgoCD: Использование Helmfile и Helmwave