build

La section build définit comment imglife génère des Dockerfiles à partir de templates et pousse les images de base vers votre registry.

Structure

build:
  core_version: "1.0.0"
  registry: registry.example.com/bases
  builder: imglife-builder # nom du builder buildx (optionnel)
  platforms: [linux/amd64, linux/arm64]
  sbom: true
  tag_format: "{registry}/{folder}:{mirror-tag}-{build_name}"

  hooks:
    post_image_build:
      - cmd: cosign sign --yes {image}
        timeout: 120s

  images:
    - name: alpine
      folder: images/alpine
      type: core
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3"
      version: "3.21.3"

Champs de niveau supérieur

Champ	Type	Requis	Défaut	Description
core_version	string	oui	—	Version de build de l’organisation ; incrémentée quand les templates/config changent
registry	string	oui	—	Chemin de base où les images construites sont poussées
builder	string	non	—	Nom de l’instance docker buildx ; omettre pour utiliser le défaut
platforms	[]string	non	[linux/amd64]	Plateformes cibles par défaut
sbom	bool	non	false	Attacher une attestation SBOM (nécessite buildx)
tag_format	string	non	{registry}/{folder}:{mirror-tag}-{build_name}	Template à tokens pour la référence complète de l’image (voir Format de tag)
hooks.post_image_build	[]Hook	non	—	Commandes à exécuter après la construction et le push de chaque image

Champs d’image

Champ	Type	Requis	Défaut	Description
name	string	oui	—	Nom de l’image (utilisé dans les logs et le token {build_name})
folder	string	oui	—	Sous-chemin registry de l’image construite (token {folder}), ex. images/alpine
type	string	oui	—	core, spe ou spe-dev (affecte la vérification EOL)
mirror_image	string	oui	—	Image miroir utilisée comme FROM (ne doit pas inclure de tag)
mirror_tag	string	non	dernier tag résolu	Épingle un tag miroir précis ; omettre pour résoudre le dernier automatiquement
mirror_tag_regex	string	non	—	Restreint la résolution automatique du dernier tag aux tags miroir qui matchent cette regex ancrée (validée au chargement de la config). Mutuellement exclusif avec mirror_tag. Voir Lignes de version.
version	string	conditionnel	—	Requis pour spe/spe-dev ; interdit pour core (qui utilise core_version)
tmpl	string	conditionnel	templates/core.tmpl	Chemin du template ; requis pour spe/spe-dev, interdit pour core
args	map[string]string	non	—	Valeurs --build-arg supplémentaires
os_family	string	non	auto-détectée	Force la famille d’OS pour les templates ({{.OSFamily}}). Valeurs connues : alpine, debian, ubuntu, rhel ; valeur libre en minuscules acceptée pour les templates personnalisés.
platforms	[]string	non	hérite du niveau supérieur	Surcharge de plateforme par image
sbom	bool	non	hérite du niveau supérieur	Surcharge SBOM par image
hooks	Hooks	non	—	Hooks par image

Types d’images

Type	Description	EOL vérifiée	Apparaît dans status
core	Image de base de production	Oui	Oui
spe	Variante à usage spécifique	Oui	Oui
spe-dev	Variante de développement	Non	Non

Lignes de version

Plusieurs blocs build.images peuvent partager le même folder (et souvent le même mirror_image). Chaque bloc est alors une ligne de version indépendante, identifiée par son mirror_tag ou son mirror_tag_regex :

images:
  - name: jdk-core-8
    folder: jdk
    type: core
    mirror_image: registry.example.com/mirrors/jdk
    mirror_tag_regex: ^8-jdk-alpine.*$

  - name: jdk-core-25
    folder: jdk
    type: core
    mirror_image: registry.example.com/mirrors/jdk
    mirror_tag_regex: ^25-jdk-alpine.*$

Toutes les commandes raisonnent par ligne, et non par dépôt :

Commande	Comportement par ligne
build	Résout le dernier tag miroir de la ligne uniquement
status	Une ligne de tableau par bloc, avec son propre tag, sa date de build, son cycle EOL et sa définition de lien Markdown ([base-<nom-image>])
cleanup	keep_last est appliqué par ligne — une ligne ancienne (JDK 8) n’est plus évincée par une ligne plus récente (JDK 25) du même dépôt
check	Le latest_tag proposé et le cycle EOL restent dans la ligne du tag utilisé
eol	Les alertes et les cycles endoflife.date sont résolus depuis la ligne du tag

Le même principe s’applique aux entrées sync partageant un target, où la ligne est définie par tag / tag_regex.

Attention

Un tag de base dont la ligne a été retirée de la configuration n’est plus protégé par keep_last : il devient un type-orphan et cleanup le supprime dès qu’il dépasse retention.max_age_days.

Templates Dockerfile

imglife rend Dockerfile.tmpl avec le moteur text/template de Go. Les variables suivantes sont disponibles :

Variable	Exemple	Description
{{.MirrorImage}}	registry.example.com/mirrors/alpine:3.21.3	Référence miroir pleinement résolue (tag déjà ajouté)
{{.CoreVersion}}	1.0.0	Version core de l’organisation (build.core_version)
{{.Version}}	3.21.3	core_version pour les images core, sinon le version de l’image
{{.Name}}	alpine	Nom de l’image
{{.Type}}	core	Type d’image (core, spe, spe-dev)
{{.OSFamily}}	alpine	Famille d’OS de l’image miroir (voir Résolution de la famille d’OS)
{{.Args}}	{KEY: value}	Map des args de l’image

Fonctions utilitaires de template

Fonction	Exemple	Description
bool	{{ if bool (index .Args "FLAG") }}	Convertit une valeur Args en booléen (accepte true/True/TRUE, false/False/FALSE, 1/0, t/f, insensible à la casse — contrairement à une comparaison brute sur le texte YAML). Clé absente/valeur vide → false sans erreur ; valeur invalide → erreur de build.
int	{{ if gt (int (index .Args "RETRY_COUNT")) 5 }}	Convertit une valeur Args en entier pour les comparaisons numériques (ex. gt, lt, eq). Clé absente/valeur vide → 0 sans erreur ; valeur invalide → erreur de build.
float	{{ if ge (float (index .Args "THRESHOLD")) 1.5 }}	Convertit une valeur Args en nombre décimal pour les comparaisons numériques. Clé absente/valeur vide → 0 sans erreur ; valeur invalide → erreur de build.

Résolution de la famille d’OS

{{.OSFamily}} est résolue par une cascade à trois niveaux ; le premier niveau qui donne un résultat l’emporte :

1. os_family dans la config — override explicite par image, sans appel réseau.
2. Inspection de /etc/os-release — les layers de l’image miroir sont lus depuis le registry et les champs ID / ID_LIKE sont mappés vers une famille (ex. les images UBI déclarent ID_LIKE="rhel fedora" → rhel). Couvre les images dont le nom ne porte aucun indice d’OS, comme python:3.13.
3. Heuristique sur le nom — mots-clés recherchés dans la référence de l’image miroir (alpine, debian et ses codenames, ubuntu et ses codenames, ubi/rhel/redhat/centos/rockylinux/almalinux).

Valeurs possibles : alpine, debian, ubuntu, rhel, un ID d’os-release non mappé transmis tel quel (ex. wolfi), ou unknown. Quand la résolution aboutit à unknown, un warning est logué au moment du build suggérant de définir os_family explicitement :

images:
  - name: ubi
    folder: images/ubi
    type: core
    mirror_image: registry.example.com/mirrors/ubi9
    os_family: rhel # override explicite — court-circuite la détection

Exemple de Dockerfile.tmpl :

FROM {{ .MirrorImage }}

RUN apk add --no-cache \
    ca-certificates \
    tzdata \
    curl

# Les labels OCI sont injectés automatiquement par imglife

imglife injecte ces labels OCI à chaque build :

org.opencontainers.image.created   = <horodatage de build>
org.opencontainers.image.revision  = <SHA git>
org.opencontainers.image.source    = <URL du projet>
org.opencontainers.image.base.name = <image miroir>
org.opencontainers.image.base.digest = <digest miroir>

Format de tag

tag_format est rendu avec des tokens entre accolades simples (pas des templates Go). Le défaut est {registry}/{folder}:{mirror-tag}-{build_name}, qui produit la référence de destination complète. Vous pouvez le personnaliser :

build:
  tag_format: "{registry}/{folder}:{mirror-tag}-org{version}"
  # Produit : registry.example.com/bases/images/alpine:3.21.3-org1.0.0

Tokens disponibles :

Token	Correspond à	Exemple
{registry}	build.registry	registry.example.com/bases
{folder}	le folder de l’image	images/alpine
{type}	le type de l’image	core
{version}	core_version pour core, sinon le version de l’image	1.0.0
{build_name}	{type}{version}	core1.0.0
{mirror-tag}	le tag miroir résolu	3.21.3

Règles de validation : les tokens inconnus sont rejetés, {registry} est obligatoire, et au moins un parmi {build_name}, {type} ou {version} doit être présent.

Builds multi-architecture

build:
  platforms: [linux/amd64, linux/arm64]
  builder: imglife-builder # le builder buildx doit supporter le multi-arch

Quand platforms contient plus d’une entrée, imglife utilise docker buildx build avec --push pour publier un manifest multi-arch. Un builder avec le driver docker-container est requis.

Astuce

Pour les builds rootless (GitLab CI sans runners privilégiés), configurez builder avec un builder BuildKit rootless. Voir Images de base — GitLab CI pour une configuration complète.

Mode output-dir

Au lieu de construire et pousser, imglife peut écrire les contextes de build Docker dans un répertoire local pour une consommation par des builders externes (Kaniko, Buildah) :

imglife build --output-dir /tmp/imglife-contexts

Chaque répertoire de contexte contient un Dockerfile, un manifeste build.json et les fichiers nécessaires. Voir imglife build pour la référence complète.

Hooks

build:
  hooks:
    post_image_build:
      - cmd: cosign sign --yes {image}
        timeout: 120s
        continue_on_error: false

Dans les commandes de hooks, le placeholder littéral {image} est remplacé par la référence complète de l’image incluant le tag. C’est la seule substitution disponible ; la commande est exécutée via sh -c.

Chaque hook accepte cmd (requis), timeout (durée Go optionnelle, ex. 120s) et continue_on_error (booléen optionnel).