Skip to content
imglife

Configuration Overview

imglife is driven by a single YAML configuration file. By default it looks for imglife.yaml in the current directory. Override this with --config:

Terminal window
imglife --config /etc/imglife/config.yaml sync
imglife --check   # validate without running

The environment variable IMGLIFE_CONFIG is also supported:

Terminal window
export IMGLIFE_CONFIG=/etc/imglife/config.yaml

Top-level structure

Section titled “Top-level structure”
registry: {} # Package Registry connection (required)
sync: {} # Mirror images to sync (optional)
build: {} # Base images to build (optional)
retention: {} # Cleanup policy (optional, has defaults)
lifecycle: {} # EOL data source (optional, has defaults)
status: {} # Status report options (optional)

All sections except registry are optional. A minimal config that only syncs mirrors only needs registry and sync.

Annotated example

Section titled “Annotated example”

Below is a complete configuration demonstrating all features. Each subsection links to its detailed reference.

# ─── Package Registry ──────────────────────────────────────────────────────────
# Stores build records for applicative images.
# Credentials via environment variables — never in YAML.
registry:
  url: https://gitlab.example.com # GitLab self-hosted instance
  project_id: 42 # Settings > General > Project ID


# ─── Sync ──────────────────────────────────────────────────────────────────────
# Copies upstream public images to your private registry.
sync:
  hooks:
    post_sync:
      - cmd: echo "Sync complete"


  entries:
    - source: docker.io/library/alpine
      tag_regex: '^3\.\d+\.\d+$' # sync all 3.x.y tags
      keep_last: 3 # retain only the 3 most recent
      target: registry.example.com/mirrors/alpine
      lifecycle:
        product: alpine # EOL product key on endoflife.date
        track: minor # "3.21.3" → cycle "3.21"


    - source: docker.io/library/golang
      tag_regex: '^1\.\d+\.\d+-alpine3\.\d+$'
      keep_last: 2
      target: registry.example.com/mirrors/golang


# ─── Build ─────────────────────────────────────────────────────────────────────
# Generates Dockerfiles from templates and pushes base images.
build:
  core_version: "1.2.0" # bumped when org config changes
  registry: registry.example.com/bases # push destination
  platforms: [linux/amd64, linux/arm64] # default for all images
  sbom: true # SBOM attestation via buildx
  tag_format: "{registry}/{folder}:{mirror-tag}-{build_name}" # default tag format


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


    - name: alpine-dev
      folder: images/alpine-dev
      type: spe-dev # dev variant — not EOL-checked
      mirror_image: registry.example.com/mirrors/alpine
      mirror_tag: "3.21.3"
      version: "3.21.3"


    - name: golang
      folder: images/golang
      type: core
      mirror_image: registry.example.com/mirrors/golang
      mirror_tag: "1.22.3-alpine3.21"
      version: "1.22.3-alpine3.21"
      platforms: [linux/amd64] # override: single arch


# ─── Retention ─────────────────────────────────────────────────────────────────
# Cleanup policy applied by `imglife cleanup`.
retention:
  keep_last: 5 # keep 5 most recent tags per image
  max_age_days: 90 # delete tags older than 90 days
  exclude_tags:
    - latest
    - stable


  archive:
    enabled: true
    registry: registry.example.com/archive # separate registry path
    keep_days: 180 # keep archived tags for 180 days


# ─── Lifecycle ─────────────────────────────────────────────────────────────────
# EOL data source configuration.
lifecycle:
  eol_provider: endoflife # fetch from endoflife.date (default)
  eol_target: git # store cache in eol-data.yaml in git
  eol_data_file: eol-data.yaml


# ─── Status ────────────────────────────────────────────────────────────────────
# Options for the generated Markdown README.
status:
  client_zone: |
    ## Additional info
    Updated daily at 06:00 UTC by the base-images CI pipeline.
    Questions? Contact the platform team in #platform-images.

Provider-specific registry configs

Section titled “Provider-specific registry configs”
registry:
  url: https://gitlab.example.com
  project_id: 42

Section references

Section titled “Section references”
Section Purpose Required
registry Package Registry backend Yes
sync Mirror images No
build Base image builds No
retention Cleanup policy No (has defaults)
lifecycle EOL data source No (has defaults)
status README generation No