sync

La section sync définit la liste des images upstream à miroir.

Structure

sync:
  hooks:
    post_sync:
      - cmd: notify-team.sh
        timeout: 30s
        continue_on_error: true

  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      keep_last: 3
      target: registry.example.com/mirrors/alpine
      lifecycle:
        product: alpine
        track: minor

Champs de niveau supérieur

Champ	Type	Requis	Défaut	Description
hooks.post_sync	[]Hook	non	—	Commandes à exécuter après la complétion de toutes les entrées sync
platforms	[]string	non	—	Plateformes par défaut à miroir pour chaque entrée (surchargeable par entrée)

Champs d’entrée

Champ	Type	Requis	Description
source	string	oui	Référence de l’image upstream (ex. docker.io/library/alpine)
target	string	oui	Référence de destination dans votre registry
tag	string	l’un ou l’autre tag/tag_regex	Synchroniser un seul tag fixe
tag_regex	string	l’un ou l’autre tag/tag_regex	Synchroniser tous les tags correspondant à ce regex
keep_last	integer	non	Conserver uniquement les N tags correspondants les plus récents
os_normalize	bool	non	Renommer les tags de variante OS (ex. alpine3.21 → 1.22-alpine3.21)
check_digest	bool	non	Re-synchroniser même si le tag existe déjà (vérification digest)
platforms	[]string	non	Restreindre les plateformes à miroir (surcharge sync.platforms)
lifecycle	Lifecycle	non	Suivi EOL pour cette image
hooks	Hooks	non	Hooks par entrée

Note

tag et tag_regex sont mutuellement exclusifs. Utilisez tag pour une version unique épinglée ; utilisez tag_regex pour une plage.

Sélection des tags

Tag fixe

- source: docker.io/library/alpine
  tag: "3.21.3"
  target: registry.example.com/mirrors/alpine

Synchronise exactement un tag. Utile quand vous souhaitez épingler à une version connue.

Regex de tag

- source: docker.io/library/alpine
  tag_regex: '^3\.\d+\.\d+$'
  keep_last: 3
  target: registry.example.com/mirrors/alpine

imglife interroge Docker Hub pour tous les tags correspondant au regex, les trie par version (fallback par date pour les tags non-semver) et synchronise les keep_last plus récents. Pour les images Docker Hub, les dates sont récupérées en un seul appel API.

Patterns regex courants

Pattern	Correspond à
^3\.\d+\.\d+$	3.21.3, 3.20.6 — Alpine 3.x
^1\.\d+\.\d+-alpine3\.\d+$	1.22.3-alpine3.21 — Go sur Alpine
^\d+\.\d+$	22.04, 24.04 — Ubuntu LTS
^\d+\.\d+\.\d+$	Tout semver

Lignes de version

Plusieurs entrées peuvent partager le même target. Chacune est alors une ligne de version indépendante, identifiée par son tag / tag_regex :

- source: docker.io/library/python
  tag_regex: '^3\.12\.\d+-bookworm$'
  target: registry.example.com/mirrors/python
  keep_last: 2
  lifecycle: { product: python, track: minor }

- source: docker.io/library/python
  tag_regex: '^3\.13\.\d+-bookworm$'
  target: registry.example.com/mirrors/python
  keep_last: 1
  lifecycle: { product: python, track: minor }

sync, status, cleanup, check, images et eol résolvent tous les tags ligne par ligne — le motif est ancré (^(?:…)$) sur le tag de destination, après normalisation si os_normalize est actif. Le tag affiché, le cycle EOL et keep_last ne fuient jamais d’une ligne à l’autre : cleanup conserve keep_last tags par ligne, la ligne 3.13 n’évince donc plus la ligne 3.12. Les tags d’un dépôt miroir ne correspondant à aucune ligne restent classés ensemble sous retention.keep_last.

Les regex sont compilées au chargement du fichier de configuration — un motif invalide fait échouer la commande au lieu de ne rien matcher silencieusement.

Le même principe s’applique aux blocs build.images partageant un folder.

Suivi du cycle de vie

Ajoutez le suivi du cycle de vie pour connecter les données EOL à une entrée sync :

- source: docker.io/library/alpine
  tag_regex: '^3\.\d+\.\d+$'
  target: registry.example.com/mirrors/alpine
  lifecycle:
    product: alpine # slug produit sur endoflife.date
    track: minor  # comment dériver le cycle depuis le tag

Valeur track	Tag exemple	Cycle résolu
minor	3.21.3	3.21
major	22.04	22

Re-synchronisation par digest

Par défaut, imglife ignore les tags qui existent déjà dans le registry cible. Activez check_digest: true pour re-synchroniser si le digest upstream a changé (ex. un tag mutable comme latest) :

- source: docker.io/library/alpine
  tag: latest
  target: registry.example.com/mirrors/alpine
  check_digest: true

Sélection des plateformes

Par défaut, imglife copie l’image upstream telle quelle, en préservant les manifest lists multi-arch (OCI image index). Définissez platforms pour ne miroir qu’un sous-ensemble. La liste est résolue par entrée : le platforms d’entrée surcharge le défaut global sync.platforms ; une liste vide copie tout.

sync:
  platforms:
    - linux/amd64 # défaut global pour chaque entrée
  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      target: registry.example.com/mirrors/alpine
    - source: docker.io/library/node
      tag: "22-alpine"
      target: registry.example.com/mirrors/node
      platforms: # surcharge par entrée
        - linux/amd64
        - linux/arm64

Comportement selon la taille de la liste :

Plateformes	Résultat
vide	Copie complète — préserve la manifest list / image source telle quelle
une plateforme	Une image mono-plateforme (pas d’index)
plusieurs	Un index réduit à ce sous-ensemble

Astuce

Certaines UI de registry (ex. GitLab Container Registry) affichent un tag de type manifest list avec Invalid tag: missing manifest digest. 0 B — c’est cosmétique, l’image se pull et se build sans problème. Miroir d’une seule plateforme produit une image simple avec un digest et une taille corrects, qui s’affiche proprement.

Hooks

sync:
  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$'
      target: registry.example.com/mirrors/alpine
      hooks:
        post_sync:
          - cmd: curl -s https://hooks.slack.com/... -d '{"text":"alpine synchronisé"}'
            timeout: 10s
            continue_on_error: true

Les hooks sont aussi disponibles au niveau supérieur de sync: et s’exécutent après la complétion de toutes les entrées. Voir la référence des variables d’environnement pour les variables injectées.

Parallélisme

Contrôlez le nombre d’entrées sync exécutées en parallèle :

export IMGLIFE_SYNC_PARALLELISM=4   # défaut : 4

Registries source privés

Pour les sources nécessitant une authentification, fournissez les credentials via des variables d’environnement en utilisant le nom d’hôte normalisé :

quay.io/prometheus/prometheus

export IMGLIFE_QUAY_IO_TOKEN=mytoken

# Source : ghcr.io/owner/image
export IMGLIFE_GHCR_IO_USERNAME=myuser
export IMGLIFE_GHCR_IO_PASSWORD=mytoken

Voir Credentials pour la convention complète.