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

Обзор

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

Предварительные требования

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

---

Конфигурация

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

Всегда настраивайте ArgoCD Image Updater с DNS-именем хоста, никогда не с IP-адресом.

Правильная конфигурация

# argocd-image-updater-config ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
  name: argocd-image-updater-config
  namespace: argocd
data:
  registries.conf: |
    registries:
      - name: nora
        api_url: https://nora.example.com      # ✅ Use hostname
        prefix: nora.example.com               # ✅ Use hostname
        insecure: no
        default: yes

Неправильная конфигурация

# DO NOT USE IP ADDRESS
registries:
  - name: nora
    api_url: https://10.0.202.20    # ❌ IP address causes issues
    prefix: 10.0.202.20             # ❌ Will create .meta tags

Почему это важно: Использование 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.example.com
        prefix: nora.example.com
        insecure: no
        default: yes

  log.level: debug  # Optional: for troubleshooting

Применение:

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.example.com/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. Проверка конфигурации

# Check Image Updater logs
kubectl logs -n argocd -l app.kubernetes.io/name=argocd-image-updater -f

# Expected output:
# level=info msg="Initialized registry endpoint https://nora.example.com"

---

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

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

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

registries:
  - name: nora
    api_url: https://nora.example.com
    prefix: nora.example.com
    insecure: no
    # No credentials needed

Вариант 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=<your-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-адресом вместо имени хоста. При использовании IP-адресов Image Updater не может корректно сопоставлять метаданные образов и создаёт рекурсивные теги отслеживания.

Решение:

1. Обновите ConfigMap, используя имя хоста:

registries:
  - name: nora
    api_url: https://nora.example.com  # Change from IP to hostname
    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"

# Get all .meta tags
META_TAGS=$(curl -s "${REGISTRY}/v2/${REPO}/tags/list" | \
  jq -r '.tags[] | select(contains(".meta"))')

# Delete each .meta tag
for TAG in $META_TAGS; do
  # Get manifest digest
  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')

  # Delete manifest
  curl -X DELETE "${REGISTRY}/v2/${REPO}/manifests/${DIGEST}"
  echo "Deleted ${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. Проверьте доступ к реестру из пода Image Updater:

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

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

---

Проблема: ошибки 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. Смонтируйте в Deployment 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. Перезапустите Deployment:

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. Тестируйте в staging — проверьте конфигурацию перед продакшен-развёртыванием

---

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

Конфигурация NORA

# Docker run command
docker run -d --name nora \
  --restart unless-stopped \
  -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 or DNS server
10.0.202.20  nora.example.com

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

nora.example.com:443 {
    tls /etc/ssl/certs/nora.crt /etc/ssl/private/nora.key
    reverse_proxy localhost:4000
}

Конфигурация 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.example.com
        prefix: nora.example.com
        insecure: no
        default: yes

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

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

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

---

Смотрите также

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