Argo CD: GitOps для Kubernetes 2026

Пошаговое руководство по развёртыванию Argo CD 2.8.0 (2026) и организации GitOps-пайплайна для Kubernetes. Примерное время выполнения: 60–90 минут.

GitOps — это модель операционной практики, в которой Git служит единственным источником правды для декларативных конфигураций инфраструктуры и приложений. При GitOps изменения в кластере инициируются синхронизацией состояния кластера с тем, что хранится в репозитории Git: мерж в main/master триггерит автоматическую доставку.

Ключевые элементы: декларативные манифесты (Helm, Kustomize, plain YAML), контроллер синхронизации (в нашем случае Argo CD 2.8.0, выпущенный в 2026), и аудит через Git. Типичная выгода — воспроизводимость, откаты через Git revert и прозрачность изменений для команд.

Шаг 1: установка Argo CD

Команда. Установите Argo CD 2.8.0 в namespace argocd с помощью официального манифеста и проверкой состояний. Это займёт 3–7 минут при хорошем соединении (обычно ~40–120 МБ скачиваемых образов).

kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/v2.8.0/manifests/install.yaml

Объяснение. Первый вызов создаёт пространство имён, второй — разворачивает контроллеры, server, repo-server, redis и redis HA. Образы Argo CD версии 2.8.0 занимают ~200–300 МБ суммарно на нодах при скачивании.

Ожидаемый вывод (успех):

namespace/argocd created
secret/argocd-secret created
serviceaccount/argocd-server created
deployment.apps/argocd-server created
... (другие ресурсы)

Типичная ошибка и её фикс:

Ошибка: ErrImagePull / ImagePullBackOff
Причина: ноды не имеют доступа к реестру образов или нет разрешений.
Фикс: проверьте интернет/registry credentials, выполните на ноде:
  docker pull argoproj/argocd:v2.8.0
  kubectl describe pod -n argocd <имя-pod>
Если используется приватный реестр — добавьте imagePullSecrets в ServiceAccount.

Доступ к UI и argocd CLI

Команда. Пробросьте порт и получите пароль администратора (initial admin password хранится в secret argocd-initial-admin-secret):

kubectl -n argocd port-forward svc/argocd-server 8080:443 &
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 --decode

Ожидаемый вывод (успех):

Forwarding from 127.0.0.1:8080 -> 443
admin
# пароль: примерная строка base64 декодированная

Типичная ошибка: порт занят или base64 недоступен.

Error: address already in use
Фикс: закройте приложение, слушающее порт 8080, или используйте другой порт: 8443:443
  kubectl -n argocd port-forward svc/argocd-server 8443:443 &

Шаг 2: application manifests

Команда. Создайте базовую структуру репозитория и manifest для приложения. Мы используем Helm chart для сервиса и plain YAML для Deployment. В репозитории создайте каталог apps/my-service с двумя файлами: Chart.yaml и values.yaml, а также base/deployment.yaml.

mkdir -p repo/apps/my-service
cat > repo/apps/my-service/Chart.yaml <<'EOF'
apiVersion: v2
name: my-service
version: 0.1.0
EOF

cat > repo/apps/my-service/values.yaml <<'EOF'
image:
  repository: myregistry/my-service
  tag: v1.0.0
replicaCount: 2
EOF

mkdir -p repo/base
cat > repo/base/deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-service
spec:
  replicas: 2
  selector:
    matchLabels:
      app: my-service
  template:
    metadata:
      labels:
        app: my-service
    spec:
      containers:
      - name: my-service
        image: myregistry/my-service:v1.0.0
        ports:
        - containerPort: 8080
EOF

Объяснение. Репозиторий содержит Helm chart и базовый Deployment. Argo CD поддерживает синхронизацию из Git по пути в репо. Рекомендуется хранить окружения в отдельных директориях (prod, staging) и использовать Kustomize или Helm values для различий.

Ожидаемый вывод (успех): файлы созданы и готовы к коммиту.

git init
git add .
git commit -m "initial: add my-service manifests"
git remote add origin git@github.com:example/argocd-repo.git
git push -u origin main

Типичная ошибка и её исправление:

Ошибка: git push — permission denied (publickey)
Причина: SSH-ключ не добавлен в аккаунт GitHub/GitLab.
Фикс: добавьте ваш публичный ключ в настройки аккаунта или используйте HTTPS remote:
  git remote set-url origin https://github.com/your/repo.git

Создание Application в Argo CD

Команда. Создайте Application, указывая репозиторий, путь и targetCluster (локальный кубер):

cat > app.yaml <<'EOF'
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-service
  namespace: argocd
spec:
  project: default
  source:
    repoURL: 'https://github.com/your/repo.git'
    path: 'base'
    targetRevision: main
  destination:
    server: 'https://kubernetes.default.svc'
    namespace: default
  syncPolicy: {}
EOF

kubectl apply -f app.yaml

Ожидаемый вывод (успех):

application.argoproj.io/my-service created

Типичная ошибка и fix:

Ошибка: repository not reachable / unauthorized
Причина: репозиторий приватный или URL указан неверно.
Фикс: добавьте репозиторий через Argo CD CLI или UI с credentials:
  argocd repo add https://github.com/your/repo.git --username --password

Шаг 3: sync policies

Команда. Настройте политику синхронизации: сначала manual для контроля, затем automated с опциями prune и selfHeal. Пример для automated:

kubectl patch application my-service -n argocd --type='merge' -p '{"spec":{"syncPolicy":{"automated":{"prune":true,"selfHeal":true}}}}'

Объяснение. automated.prune=true удаляет ресурсы, которые удалены из Git; selfHeal=true автоматически возвращает расхождения в кластере к состоянию в Git. Эти опции ускоряют delivery, но требуют строгой политики доступа.

Ожидаемый вывод (успех):

application.argoproj.io/my-service patched

Проверка статуса синхронизации:

argocd app get my-service
Name:               my-service
Project:            default
Sync Policy:        Automated (Prune, SelfHeal)
Sync Status:        Synced to main (abc123)
Health Status:      Healthy

Типичная ошибка и её фикс:

Ошибка: sync failed — resources not found / invalid manifest
Причина: манифесты содержат синтаксические ошибки или ссылка на несуществующий CRD.
Фикс: проверьте манифесты локально:
  kubectl apply --dry-run=client -f base/deployment.yaml
  kubectl api-resources | grep Если CRD отсутствует — установите CRD в кластер до синка.

Шаг 4: RBAC и SSO

Команда. Настройте RBAC в Argo CD и интеграцию с SSO (OIDC) для безопасного доступа команд. Пример добавления role в ConfigMap argocd-rbac-cm:

kubectl -n argocd patch configmap argocd-rbac-cm -p '{"data":{"policy.csv":"g, dev-team, role:admin\