CMK_IMAGE gegen CMK_EDITION/CMK_VERSION pruefen

Anlass war die Frage, wozu CMK_IMAGE neben Edition und Version ueberhaupt noch noetig ist. Antwort: es ist der einzige Wert, den compose und die systemd-Units lesen. Edition und Version sind reine Vorgaben fuer den Downloader und wirken erst ueber "image pull". Ableiten laesst sich CMK_IMAGE nicht, weil dieselbe Version je nach Bezugsweg voellig anders heisst - docker.io/..., registry.checkmk.com/... oder localhost/... bei einem aus dem Tarball geladenen Image. Daraus folgt eine Falle, die bisher nirgends auffiel: wer Edition auf "enterprise" stellt, CMK_IMAGE aber auf dem Raw-Image stehen laesst, betreibt weiter Raw. Genau dieser Zustand kam in der Praxis vor. image_consistency_check vergleicht deshalb Name und Tag von CMK_IMAGE mit Edition und Version und meldet Abweichungen - in "image status", im allgemeinen "status" und im Einstellungsmenue direkt nach dem Aendern von Edition oder Version, dort gleich mit dem Angebot, das Image zu holen. Aus Tarballs geladene Images (localhost/...) gelten als stimmig, solange Name und Tag passen; die Editionsaliase werden beruecksichtigt, "pro" passt also zu check-mk-enterprise. Die Beschriftungen in den Einstellungen sagen jetzt, wer was tut: CMK_IMAGE VERWENDETES Image - setzt "image pull" CMK_EDITION Edition (nur Vorgabe, wirkt ueber "image pull") CMK_VERSION Version (nur Vorgabe, wirkt ueber "image pull") Vier Faelle geprueft: abweichende Edition, abweichende Version, stimmiger Zustand und aus Tarball geladenes Image. Dokumentiert als Abschnitt 8.7 in beiden Sprachfassungen. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-09-20 15:58:39 +02:00
parent ed052cd62f
commit 7a93dd5dbf
3 changed files with 164 additions and 5 deletions
@@ -876,7 +876,54 @@ ihn als `CMK_IMAGE` in die `.env` ein. Danach:
 sudo ./scripts/cmk-manage.sh up
 ```

-### 8.7 Nachsehen, was gilt
+### 8.7 `CMK_IMAGE` gegenüber `CMK_EDITION`/`CMK_VERSION`
+
+Diese drei Werte haben unterschiedliche Aufgaben, und das ist eine häufige
+Verwechslung:
+
+| Wert | Wer liest ihn | Wozu |
+|---|---|---|
+| **`CMK_IMAGE`** | **compose und die systemd-Units** | das Image, das tatsächlich gestartet wird |
+| `CMK_EDITION` | nur `cmk-manage.sh image …` | Vorgabe für den Downloader |
+| `CMK_VERSION` | nur `cmk-manage.sh image …` | Vorgabe für den Downloader |
+
+`CMK_IMAGE` lässt sich **nicht** aus Edition und Version ableiten – je nach
+Bezugsweg sieht dieselbe Version völlig anders aus:
+
+```
+docker.io/checkmk/check-mk-raw:2.3.0-latest                 (Docker Hub)
+registry.checkmk.com/enterprise/check-mk-enterprise:2.3.0p9 (Registry)
+localhost/checkmk/check-mk-enterprise:2.3.0p9               (aus Tarball geladen)
+```
+
+Deshalb hält `CMK_IMAGE` fest, was **wirklich vorhanden ist**, und wird von
+`image pull`, `image download`, `image load` und `image use` gesetzt – von Hand
+muss man dort normalerweise nichts eintragen.
+
+> **Daraus folgt:** Edition oder Version zu ändern, startet **keine** andere
+> Ausgabe. Erst `image pull` (bzw. `download`/`load`) schreibt das Ergebnis
+> nach `CMK_IMAGE`, und erst `up` erstellt den Container neu.
+
+Damit das nicht unbemerkt auseinanderläuft, prüft das Skript die drei Werte
+gegeneinander – in `image status`, in `status` und im Einstellungsmenü direkt
+nach dem Ändern von Edition oder Version:
+
+```
+[ WARN ] CMK_IMAGE passt nicht zu den eingestellten Vorgaben.
+
+  verwendet wird : docker.io/checkmk/check-mk-raw:2.3.0-latest
+  Edition        : eingestellt "enterprise", im Image steckt "raw"
+
+Compose und die systemd-Units verwenden ausschliesslich CMK_IMAGE.
+...
+    ./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0-latest
+    ./scripts/cmk-manage.sh up
+```
+
+Aus einem Tarball geladene Images (`localhost/…`) gelten dabei als stimmig,
+solange Name und Tag passen.
+
+### 8.8 Nachsehen, was gilt

 ```bash
 ./scripts/cmk-manage.sh image status     # konfiguriertes + lokale Images
@@ -882,7 +882,53 @@ typically `localhost/checkmk/check-mk-enterprise:2.3.0p23`) and writes it to
 sudo ./scripts/cmk-manage.sh up
 ```

-### 8.7 Checking what is in effect
+### 8.7 `CMK_IMAGE` versus `CMK_EDITION`/`CMK_VERSION`
+
+These three values have different jobs, and confusing them is a common
+mistake:
+
+| Value | Who reads it | What for |
+|---|---|---|
+| **`CMK_IMAGE`** | **compose and the systemd units** | the image that actually starts |
+| `CMK_EDITION` | only `cmk-manage.sh image …` | input for the downloader |
+| `CMK_VERSION` | only `cmk-manage.sh image …` | input for the downloader |
+
+`CMK_IMAGE` can **not** be derived from edition and version – depending on how
+you obtained it, the very same version looks completely different:
+
+```
+docker.io/checkmk/check-mk-raw:2.3.0-latest                 (Docker Hub)
+registry.checkmk.com/enterprise/check-mk-enterprise:2.3.0p9 (registry)
+localhost/checkmk/check-mk-enterprise:2.3.0p9               (loaded from a tarball)
+```
+
+So `CMK_IMAGE` records what is **actually there**, and it is written by
+`image pull`, `image download`, `image load` and `image use` – you normally
+never have to type anything there by hand.
+
+> **Consequence:** changing the edition or version does **not** start a
+> different release. Only `image pull` (or `download`/`load`) writes the result
+> to `CMK_IMAGE`, and only `up` recreates the container.
+
+To stop these from drifting apart unnoticed, the script compares the three
+values – in `image status`, in `status`, and in the settings menu right after
+the edition or version is changed:
+
+```
+[ WARN ] CMK_IMAGE passt nicht zu den eingestellten Vorgaben.
+
+  verwendet wird : docker.io/checkmk/check-mk-raw:2.3.0-latest
+  Edition        : eingestellt "enterprise", im Image steckt "raw"
+...
+    ./scripts/cmk-manage.sh image pull --edition enterprise --version 2.3.0-latest
+    ./scripts/cmk-manage.sh up
+```
+
+("CMK_IMAGE does not match the configured defaults / in use / configured … but
+the image contains …".) Images loaded from a tarball (`localhost/…`) count as
+consistent as long as name and tag match.
+
+### 8.8 Checking what is in effect

 ```bash
 ./scripts/cmk-manage.sh image status     # configured image + local images
@@ -745,7 +745,51 @@ image_cmd_list() {
    return 0
 }

+# Passt CMK_IMAGE zu CMK_EDITION/CMK_VERSION?
+#
+# CMK_IMAGE ist der einzige Wert, den compose und die systemd-Units
+# verwenden. CMK_EDITION und CMK_VERSION sind nur Eingaben fuer den
+# Downloader. Wer sie aendert, ohne anschliessend ein Image zu holen,
+# betreibt weiter das alte - das faellt sonst nirgends auf.
+#
+# Rueckgabe: 0 = stimmig (oder nicht beurteilbar), 1 = Abweichung.
+# Die Erklaerung geht nach stdout.
+image_consistency_check() {
+    local img="${CMK_IMAGE:-}" ed="${CMK_EDITION:-}" ver="${CMK_VERSION:-}"
+    [ -n "$img" ] && [ -n "$ed" ] || return 0
+
+    local repo tag name
+    tag="${img##*:}"
+    repo="${img%:*}"
+    case "$repo" in */*) name="${repo##*/}" ;; *) name="$repo" ;; esac
+    # kein Tag angegeben -> nicht beurteilbar
+    [ "$tag" = "$img" ] && tag=""
+
+    local ed_ok="" a
+    for a in $(edition_aliases "$ed"); do
+        [ "$name" = "check-mk-$a" ] && ed_ok=1
+    done
+
+    local ver_ok=1
+    [ -n "$ver" ] && [ -n "$tag" ] && [ "$tag" != "$ver" ] && ver_ok=""
+
+    [ -n "$ed_ok" ] && [ -n "$ver_ok" ] && return 0
+
+    printf 'CMK_IMAGE passt nicht zu den eingestellten Vorgaben.\n\n'
+    printf '  verwendet wird : %s\n' "$img"
+    [ -z "$ed_ok" ]  && printf '  Edition        : eingestellt "%s", im Image steckt "%s"\n' \
+                               "$ed" "${name#check-mk-}"
+    [ -z "$ver_ok" ] && printf '  Version        : eingestellt "%s", im Image steckt "%s"\n' "$ver" "$tag"
+    printf '\nCompose und die systemd-Units verwenden ausschliesslich CMK_IMAGE.\n'
+    printf 'Edition und Version sind nur Vorgaben fuer den Downloader - sie\n'
+    printf 'wirken erst, wenn daraus ein Image geholt wird:\n\n'
+    printf '    %s image pull --edition %s --version %s\n' "$SELF" "$ed" "${ver:-<version>}"
+    printf '    %s up\n' "$SELF"
+    return 1
+}
+
 image_cmd_status() {
+    local msg
    printf '\n%sKonfiguriertes Image (.env: CMK_IMAGE)%s\n' "$C_BLD" "$C_RST"
    printf '  %s\n' "${CMK_IMAGE:-<nicht gesetzt>}"
    if [ -n "${CMK_IMAGE:-}" ]; then
@@ -758,6 +802,11 @@ image_cmd_status() {
            printf '  %sACHTUNG%s: kurzer Name ohne Registry - unter Podman fehleranfaellig.\n' "$C_RED" "$C_RST"
        fi
    fi
+    if ! msg="$(image_consistency_check)"; then
+        printf '\n'
+        warn "$msg"
+    fi
+
    printf '\n%sVorgaben fuer den Downloader%s\n' "$C_BLD" "$C_RST"
    printf '  Edition  : %s  ->  %s\n' "${CMK_EDITION:-raw}" "$(edition_repo "${CMK_EDITION:-raw}" 2>/dev/null || echo '?')"
    printf '  Version  : %s\n' "${CMK_VERSION:-<nicht gesetzt>}"
@@ -1314,10 +1363,16 @@ cmd_shell()   { require_cmk_running; $RUNTIME exec -it "$CMK_CONTAINER_NAME" bas
 cmd_omd()     { require_cmk_running; $RUNTIME exec -it "$CMK_CONTAINER_NAME" omd "$@"; }

 cmd_status() {
+    local cmsg
    printf '\n%sImage%s\n' "$C_BLD" "$C_RST"
    printf '  %-24s %s\n' "${CMK_IMAGE:-<nicht gesetzt>}" \
        "$(image_exists_local "${CMK_IMAGE:-}" && echo "lokal vorhanden" || echo "${C_YEL}nicht lokal vorhanden${C_RST}")"

+    if ! cmsg="$(image_consistency_check)"; then
+        printf '  %sAchtung%s: CMK_IMAGE passt nicht zu CMK_EDITION/CMK_VERSION.\n' "$C_YEL" "$C_RST"
+        printf '           Einzelheiten:  %s image status\n' "$SELF"
+    fi
+
    printf '\n%sContainer%s\n' "$C_BLD" "$C_RST"
    local c
    for c in "$CMK_CONTAINER_NAME" "$NPM_CONTAINER_NAME"; do
@@ -2404,9 +2459,9 @@ settings_defs() {
 cat <<'EOF'
 runtime|CMK_RUNTIME|choice|Container-Runtime|auto:docker:podman|1
 runtime|TZ|text|Zeitzone||
-image|CMK_IMAGE|text|Checkmk-Image (vollqualifiziert)||
-image|CMK_EDITION|choice|Edition fuer den Downloader|raw:community:free:cloud:managed:pro:ultimate:ultimatemt:enterprise|
-image|CMK_VERSION|text|Version fuer den Downloader||
+image|CMK_IMAGE|text|VERWENDETES Image - setzt "image pull"||
+image|CMK_EDITION|choice|Edition (nur Vorgabe, wirkt ueber "image pull")|raw:community:free:cloud:managed:pro:ultimate:ultimatemt:enterprise|
+image|CMK_VERSION|text|Version (nur Vorgabe, wirkt ueber "image pull")||
 image|CMK_REGISTRY|text|Registry fuer Enterprise||1
 image|CMK_REGISTRY_USER|text|Registry-Benutzer||1
 image|CMK_REGISTRY_PASSWORD|password|Registry-Kennwort||1
@@ -3539,6 +3594,17 @@ gui_settings_edit() {
        ui_msg "Gespeichert" "$key = $([ "$typ" = password ] && echo '********' || echo "${new:-<leer>}")$hint"
        # Zugangsdaten lassen sich sofort pruefen - das erspart den Umweg
        case "$key" in
+            CMK_EDITION|CMK_VERSION)
+                load_env "${ENV_FILE:-$PROJECT_DIR/.env}"
+                local cm
+                if ! cm="$(image_consistency_check)"; then
+                    if ui_yesno "Image passt nicht" \
+"$cm
+
+Image jetzt holen?"; then
+                        gui_image_pull || true
+                    fi
+                fi ;;
            CMK_REGISTRY_USER|CMK_REGISTRY_PASSWORD|CMK_DOWNLOAD_USER|CMK_DOWNLOAD_PASSWORD|CMK_REGISTRY|CMK_DOWNLOAD_BASEURL)
                load_env "${ENV_FILE:-$PROJECT_DIR/.env}"
                if ui_yesno "Zugangsdaten pruefen" \