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>

README.md

@@ -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

README_en.md

@@ -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

scripts/cmk-manage.sh

@@ -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_IMAGE|text|VERWENDETES Image - setzt "image pull"||
-image|CMK_EDITION|choice|Edition fuer den Downloader|raw:community:free:cloud:managed:pro:ultimate:ultimatemt:enterprise|
+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 fuer den Downloader||
+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" \