Image-Updates

Composia erkennt neue Image-Tags und kann Updates automatisch anwenden. Image-Check-Aufgaben laufen auf dem Agenten und melden die Ergebnisse an den Controller.

Wie es funktioniert

Der Controller plant regelmäßige image_check-Aufgaben gemäß der Update-Konfiguration des Dienstes. Jede Prüfung:

Der Agent lädt das Dienstpaket herunter.
Liest docker compose config --format json, um laufende Images zu erkennen.
Meldet lokale und entfernte Digests für jedes Image.
Für Images, die in update.images konfiguriert sind, prüft es auf neue Kandidaten-Tags unter Verwendung der konfigurierten Erkennungsquellen.
Meldet die Ergebnisse an den Controller. Der Controller zeichnet verfügbare Updates auf und kann sie automatisch anwenden.

Controller-Standardwerte

Globale Standardwerte werden in der Controller-Konfiguration gesetzt:

controller:
  updates:
    default_check_schedule: "0 */6 * * *"
    auto_apply: false
    backup_before_update: true
    digest_pin: false
    semver:
      default_allow:
        - patch
        - minor
    forge_auth:
      github:
        url: "https://github.com"
        token: "REPLACE"
        api_url: "https://api.github.com"

Der dienstspezifische update-Abschnitt überschreibt diese Standardwerte.

Dienstkonfiguration

update:
  enabled: true
  auto_apply: false
  check_schedule: "0 */6 * * *"
  backup_before_update: true
  digest_pin: false
  backup_data:
    - name: db
      enabled: true
  discovery_sources:
    upstream-gh:
      sources:
        - type: github
          repo: owner/repo
      combine: first_success
      include_prerelease: false
  images:
    api:
      image: ghcr.io/example/api
      current:
        env:
          file: .env
          key: API_VERSION
      discovery: upstream-gh
      filter:
        type: semver
        allow:
          - patch
          - minor

`update` oberste Ebene

Schlüssel	Typ	Beschreibung
`enabled`	`bool`	Aktiviert Update-Prüfungen für diesen Dienst.
`auto_apply`	`bool`	Wendet erkannte Updates automatisch an.
`check_schedule`	`string`	Cron-Zeitplan für Update-Prüfungen.
`backup_before_update`	`bool`	Führt ein Backup vor dem Anwenden eines Updates aus.
`backup_data`	`[]object`	Geschützte Datenelemente, die vor dem Update gesichert werden sollen. Jedes Element hat einen `name` und optional `enabled`.
`digest_pin`	`bool`	Fixiert Images per Digest für Reproduzierbarkeit.
`discovery_sources`	`map[string]object`	Benannte wiederverwendbare Erkennungskonfigurationen.
`images`	`map[string]object`	Update-Konfiguration pro Image. Schlüssel sind beliebige Namen, die den zu prüfenden Images entsprechen.

`images.<name>`

Schlüssel	Typ	Erforderlich	Beschreibung
`image`	`string`	Ja	Vollständige Image-Referenz, zum Beispiel `ghcr.io/example/api`.
`auto_apply`	`bool`	Nein	Per-Image-Override für automatisches Anwenden.
`check_schedule`	`string`	Nein	Per-Image-Prüfzeitplan.
`backup_before_update`	`bool`	Nein	Per-Image-Backup-Umschalter.
`digest_pin`	`bool`	Nein	Per-Image-Digest-Pin-Umschalter.
`current`	`object`	Ja	Wie die aktuell deployte Version gefunden wird.
`discovery`	`object` oder `string`	Ja	Erkennungskonfiguration oder Verweis auf einen benannten `discovery_sources`-Eintrag.
`filter`	`object`	Bed.	Versionsfilter. Erforderlich, es sei denn, der Erkennungsmodus ist `digest`.

`current`

Genau eine dieser Quellen muss angegeben werden:

Statischer Tag:

current:
  tag: "v1.2.3"

Umgebungsdatei:

current:
  env:
    file: .env
    key: APP_VERSION

Der file-Pfad ist relativ zum Dienstverzeichnis. Composia liest die Datei, sucht nach SCHLÜSSEL=WERT-Zeilen und extrahiert den Wert.

YAML-Datei:

current:
  yaml:
    file: values.yaml
    path: app.image.tag

Der path ist ein durch Punkte getrennter Pfad in den YAML-Dokumentbaum. Der Wert an diesem Pfad muss ein Skalar sein.

Erkennung

Erkennungsquellen können sein:

Benannte Referenz auf einen discovery_sources-Eintrag:

discovery: upstream-gh

Inline-Definition:

discovery:
  sources:
    - type: probe
  combine: first_success
  include_prerelease: false

Erkennungsquellentypen:

Typ	Erforderliche Schlüssel	Verhalten
`probe`	Keine	Semver-Sondierung: Sucht nach höheren Versionen durch Sondieren von Registry-Manifesten. Erfordert einen `semver`-Filter.
`registry`	Keine	Listet alle Tags aus der Image-Registry auf.
`auto`	Keine (optional `repo_url`)	Versucht `probe`, dann `registry` als zusammengeführte Erkennung. Muss die einzige Quelle in einer Erkennungskonfiguration sein.
`digest`	Keine	Vergleicht nur den entfernten Digest mit dem lokalen Digest. Kein Tag-Vergleich. `filter` muss weggelassen werden. Muss die einzige Quelle sein.
`github`	`repo` (`owner/repo`)	Fragt GitHub-Releases ab. Wird auf der Controller-Seite verarbeitet.
`gitlab`	`project`	Fragt GitLab-Releases ab. Wird auf der Controller-Seite verarbeitet.
`forgejo`	`repo` (`owner/repo`)	Fragt Forgejo-Releases ab. Wird auf der Controller-Seite verarbeitet.

combine akzeptiert merge (Vereinigung aller Quellergebnisse) oder first_success (erste Quelle, die Ergebnisse liefert, gewinnt).

include_prerelease schließt Vorabversionen in GitHub-, GitLab- und Forgejo-Release-Abfragen ein.

Filter

Typ	Erforderliche Schlüssel	Verhalten
`semver`	Keine	Filtert nach semantischer Version. `allow` kann `patch`, `minor`, `major` enthalten.
`date`	`format`	Parst Tags als Daten mit dem angegebenen Format.
`regex`	`pattern`, `order`	Filtert nach Regex. Order muss `numeric` oder `lexicographic` sein.
`latest`	Keine	Nimmt den neuesten Tag ohne Filterung.

Semver-Sondierung

Mit type: probe und einem semver-Filter sucht Composia nach Kandidaten-Tags, indem es Versionsnummern konstruiert und prüft, ob das entsprechende Registry-Manifest existiert. Es sondiert Patch-, Minor- und Major-Sprünge gemäß der allow-Liste unter Verwendung einer exponentiellen Suche mit binärer Verfeinerung, um die höchste verfügbare Version zu finden.

Digest-Modus

Wenn alle Erkennungsquellen in einer Konfiguration type: digest haben, wird kein Tag-Vergleich durchgeführt. Composia vergleicht nur den entfernten Image-Digest mit dem lokalen Digest:

discovery:
  sources:
    - type: digest

Wenn digest als Erkennungsmodus gesetzt ist, muss filter weggelassen werden. Wenn ein Digest abweicht, wird ein Update als verfügbar betrachtet.

Image-Beobachtungen

Während Deploy- und Update-Aufgaben sammelt der Agent auch Image-Beobachtungen für alle Compose-Dienste. Diese umfassen lokale und entfernte Digests, die unabhängig davon an den Controller gemeldet werden, ob update.images konfiguriert ist. Dies bietet Einblick in den Image-Zustand in der Web-UI und CLI.

Zuletzt aktualisiert am Juli 16, 2026 • Renovate Bot

Secrets Benachrichtigungen