Интеграция с ArgoCD Image Updater

Обзор

Данное руководство описывает интеграцию NORA с ArgoCD Image Updater для автоматического обновления образов в рамках GitOps-процессов.

Требования

• Реестр NORA доступен по HTTPS с действительным сертификатом
• ArgoCD Image Updater установлен в кластере
• Для NORA настроено DNS-имя (не просто IP-адрес)

---

Настройка

⚠️ Важно: используйте DNS-имя, а не IP-адрес

Всегда настраивайте ArgoCD Image Updater с DNS-именем, никогда не используйте IP-адрес.

✅ Правильная настройка

# ConfigMap для argocd-image-updater-config
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
      - name: nora
        api_url: https://nora.example.com      # ✅ Используйте DNS-имя
        prefix: nora.example.com               # ✅ Используйте DNS-имя
        insecure: no
        default: yes

❌ Неправильная настройка

# НЕ ИСПОЛЬЗУЙТЕ IP-АДРЕС
registries:
  - name: nora
    api_url: https://10.0.202.20    # ❌ IP-адрес приводит к проблемам
    prefix: 10.0.202.20             # ❌ Будут создаваться теги .meta

Почему это важно: использование IP-адресов приводит к тому, что ArgoCD Image Updater некорректно отслеживает метаданные образов, что вызывает рекурсивное создание тегов .meta (см. раздел «Известные проблемы» ниже).

---

Полный пример настройки

1. Создание ConfigMap

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
      - name: nora
        api_url: https://nora.devitacademy.lab
        prefix: nora.devitacademy.lab
        insecure: no
        default: yes

  log.level: debug  # Необязательно: для устранения неполадок

Применение:

kubectl apply -f argocd-image-updater-config.yaml

2. Настройка аннотаций приложения

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
  namespace: argocd
  annotations:
    argocd-image-updater.argoproj.io/image-list: myapp=nora.devitacademy.lab/myapp
    argocd-image-updater.argoproj.io/myapp.update-strategy: latest
    argocd-image-updater.argoproj.io/myapp.allow-tags: regexp:^[0-9a-f]{7}$
spec:
  source:
    repoURL: https://gitlab.example.com/myorg/myapp-infra.git
    path: overlays/prod

3. Перезапуск Image Updater

kubectl rollout restart deployment argocd-image-updater -n argocd

4. Проверка настройки

# Проверка логов Image Updater
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater -f

# Ожидаемый вывод:
# level=info msg="Initialized registry endpoint https://nora.devitacademy.lab"

---

Аутентификация

Вариант 1: Без аутентификации (внутренняя сеть)

Если NORA работает без аутентификации (только во внутренней сети):

registries:
  - name: nora
    api_url: https://nora.example.com
    prefix: nora.example.com
    insecure: no
    # Учётные данные не требуются

Вариант 2: Базовая аутентификация

Создание секрета:

kubectl create secret generic nora-creds \
  --namespace argocd \
  --from-literal=username=admin \
  --from-literal=password=secret

Ссылка в ConfigMap:

registries:
  - name: nora
    api_url: https://nora.example.com
    prefix: nora.example.com
    credentials: secret:argocd/nora-creds

Вариант 3: Аутентификация по токену

kubectl create secret generic nora-token \
  --namespace argocd \
  --from-literal=token=<ваш-токен>

registries:
  - name: nora
    api_url: https://nora.example.com
    prefix: nora.example.com
    credentials: secret:argocd/nora-token

---

Известные проблемы

Проблема: рекурсивные теги .meta

Симптом:

В реестре накапливаются теги вида:

latest
latest.meta
latest.meta.meta
latest.meta.meta.meta
...

Причина:

ArgoCD Image Updater был настроен с IP-адресом вместо DNS-имени. При использовании IP-адресов Image Updater не может корректно сопоставить метаданные образов и создаёт рекурсивные теги отслеживания.

Решение:

1. Обновите ConfigMap, указав DNS-имя:

registries:
  - name: nora
    api_url: https://nora.example.com  # Замените IP-адрес на DNS-имя
    prefix: nora.example.com

2. Перезапустите Image Updater:

kubectl delete pod -n argocd -l app.kubernetes.io/name=argocd-image-updater

3. Удалите существующие теги .meta:

#!/bin/bash
REGISTRY="https://nora.example.com"
REPO="myapp"

# Получить все теги .meta
META_TAGS=$(curl -s "${REGISTRY}/v2/${REPO}/tags/list" | \
  jq -r '.tags[] | select(contains(".meta"))')

# Удалить каждый тег .meta
for TAG in $META_TAGS; do
  # Получить дайджест манифеста
  DIGEST=$(curl -sI \
    -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
    "${REGISTRY}/v2/${REPO}/manifests/${TAG}" | \
    grep Docker-Content-Digest | awk '{print $2}' | tr -d '\r')

  # Удалить манифест
  curl -X DELETE "${REGISTRY}/v2/${REPO}/manifests/${DIGEST}"
  echo "Удалён ${TAG} (${DIGEST})"
done

Профилактика:

Всегда используйте DNS-имена в настройке ArgoCD Image Updater, никогда не используйте IP-адреса.

---

Устранение неполадок

Проблема: Image Updater не обнаруживает новые образы

Проверьте:

1. Убедитесь в правильности настройки реестра:

kubectl get cm argocd-image-updater-config -n argocd -o yaml

2. Проверьте логи Image Updater:

kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater | grep nora

3. Протестируйте доступ к реестру из Pod Image Updater:

kubectl exec -n argocd deployment/argocd-image-updater -- \
  wget -O- https://nora.example.com/v2/_catalog

Решение: убедитесь, что DNS-имя разрешается и сертификат является доверенным.

---

Проблема: ошибки TLS-сертификата

Ошибка:

x509: certificate signed by unknown authority

Решение:

Добавьте сертификат удостоверяющего центра в Image Updater:

1. Создайте ConfigMap с сертификатом УЦ:

kubectl create configmap nora-ca \
  --namespace argocd \
  --from-file=ca.crt=/path/to/ca.crt

2. Смонтируйте в развёртывание Image Updater:

spec:
  template:
    spec:
      containers:
      - name: argocd-image-updater
        volumeMounts:
        - name: nora-ca
          mountPath: /etc/ssl/certs/nora-ca.crt
          subPath: ca.crt
      volumes:
      - name: nora-ca
        configMap:
          name: nora-ca

3. Перезапустите развёртывание:

kubectl rollout restart deployment argocd-image-updater -n argocd

---

Проблема: ошибки ограничения частоты запросов

Ошибка:

429 Too Many Requests

Решение:

Увеличьте лимиты NORA (см. руководство по ограничениям запросов):

NORA_RATE_LIMIT_GENERAL_RPS=1000
NORA_RATE_LIMIT_GENERAL_BURST=2000

Image Updater часто опрашивает реестры; убедитесь, что общие лимиты это учитывают.

---

Рекомендации

1. Всегда используйте HTTPS — никогда не используйте незащищённые реестры в рабочей среде
2. Используйте DNS-имена — избегайте IP-адресов для предотвращения проблем с тегами .meta
3. Ограничьте частоту обновлений — настройте разумные интервалы опроса
4. Следите за логами — отслеживайте проблемы с аутентификацией и сетью
5. Паттерны тегов — используйте конкретные шаблоны тегов, чтобы избежать нежелательных обновлений
6. Тестируйте на стенде — проверяйте конфигурацию перед развёртыванием в рабочей среде

---

Пример: полная рабочая конфигурация

Настройка NORA

# Запуск через Docker
docker run -d --name nora \
  --restart unless-stopped \
  -p 5000:5000 -p 4000:4000 \
  -v /data/nora:/data \
  -e NORA_STORAGE_PATH=/data \
  -e NORA_RATE_LIMIT_GENERAL_RPS=1000 \
  -e NORA_RATE_LIMIT_GENERAL_BURST=2000 \
  ghcr.io/getnora-io/nora:latest serve

Настройка DNS

# /etc/hosts или DNS-сервер
10.0.202.20  nora.devitacademy.lab

Обратный прокси Caddy

nora.devitacademy.lab:443 {
    tls /etc/ssl/certs/nora.crt /etc/ssl/private/nora.key
    reverse_proxy localhost:5000
}

Конфигурация ArgoCD Image Updater

apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
      - name: nora
        api_url: https://nora.devitacademy.lab
        prefix: nora.devitacademy.lab
        insecure: no
        default: yes

Аннотации приложения

metadata:
  annotations:
    argocd-image-updater.argoproj.io/image-list: |
      backend=nora.devitacademy.lab/lms-backend:latest,
      frontend=nora.devitacademy.lab/lms-frontend:latest

Результат: Image Updater успешно обнаруживает новые образы и обновляет приложения без создания тегов .meta.

---

См. также

• Документация ArgoCD Image Updater
• Справочник по настройке NORA
• Руководство по ограничениям запросов
• Руководство по мониторингу