kas-container: allow to select specific image distribution

With the recent publishing of per-distro container builds (e.g.
bookworm, trixie), we also allow the user to select the specific
distro version. For that, we introduce the environment variable
KAS_CONTAINER_IMAGE_DISTRO, which results in appending "-<distro>"
to the image tag. If unset, the most recent version is choosen (i.e.
nothing is appended to the tag).

Signed-off-by: Felix Moessbauer <[email protected]>
Signed-off-by: Jan Kiszka <[email protected]>

Author: fmoessbauer

docs/command-line/environment-variables.inc

@@ -193,6 +193,11 @@ overwritten using the ``env`` section of the config file.
 | ``KAS_IMAGE_VERSION`` (C)| Select the version of the (official) kas         |
 |                          | container (e.g. 4.5).                            |
 +--------------------------+--------------------------------------------------+
+| |container-distro| (C)   | Select the base distro and its release of the    |
+|                          | container image (e.g. ``debian-bookworm``).      |
+|                          | If not specified, the default (most-recent       |
+|                          | supported) distro version is used.               |
++--------------------------+--------------------------------------------------+
 | ``KAS_CONTAINER_IMAGE``  | Select the container image (full OCI path        |
 | (C)                      | including tag).                                  |
 +--------------------------+--------------------------------------------------+
@@ -221,6 +226,7 @@ overwritten using the ``env`` section of the config file.
                               ``CI_SERVER_PROTOCOL``
                               ``CI_SERVER_SHELL_SSH_HOST``
                               ``CI_SERVER_SHELL_SSH_PORT``
+.. |container-distro| replace:: ``KAS_CONTAINER_IMAGE_DISTRO``
 
 .. only:: html
 

docs/userguide/getting-started.rst

@@ -30,8 +30,8 @@ There are (at least) three options for using kas:
   use it in place of the ``kas`` command.
   The script version corresponds to the kas tool and the kas image version.
 - Use the container image in CI. Specify
-  ``ghcr.io/siemens/kas/kas[-isar][:<x.y>][-<distro-release>]`` in your CI script
-  that requests a container image as runtime environment.
+  ``ghcr.io/siemens/kas/kas[-isar][:<x.y>][-<distro-release>]`` in your CI
+  script that requests a container image as runtime environment.
 
 Start build::
 

docs/userguide/kas-container-description.inc

@@ -17,6 +17,15 @@ from ``kas-container`` and the versions do not match, a warning is emitted. This
 limitation might be lessened in the future, once a stable interface between
 ``kas-container`` and kas is introduced.
 
+From version ``5.0`` onward, kas offers images built on several base
+distributions. Select a distribution by setting the environment variable
+``KAS_CONTAINER_IMAGE_DISTRO`` to the desired value (e.g. ``debian-bookworm``
+or ``debian-trixie``). The corresponding image tags follow the pattern
+``:<version>-<base-distro>`` (e.g. ``:5.0-debian-bookworm``).
+Alternatively, you can adjust ``KAS_CONTAINER_IMAGE_DISTRO_DEFAULT`` in the
+``kas-container`` script if you copy this into your downstream layer already
+for encoding the supported kas version.
+
 As container backends, Docker and
 Podman are supported. To force the use of podman over docker, set
 ``KAS_CONTAINER_ENGINE=podman``. For details, see :ref:`env-vars-label`.

kas-container

@@ -29,6 +29,7 @@ set -e
 
 KAS_CONTAINER_SCRIPT_VERSION="4.8.2"
 KAS_IMAGE_VERSION_DEFAULT="${KAS_CONTAINER_SCRIPT_VERSION}"
+KAS_CONTAINER_IMAGE_DISTRO_DEFAULT=""
 KAS_CONTAINER_IMAGE_PATH_DEFAULT="ghcr.io/siemens/kas"
 KAS_CONTAINER_IMAGE_NAME_DEFAULT="kas"
 KAS_CONTAINER_SELF_NAME="$(basename "$0")"
@@ -290,10 +291,14 @@ trap kas_container_cleanup EXIT INT TERM
 set_container_image_var()
 {
 	KAS_IMAGE_VERSION="${KAS_IMAGE_VERSION:-${KAS_IMAGE_VERSION_DEFAULT}}"
+	KAS_CONTAINER_IMAGE_DISTRO="${KAS_CONTAINER_IMAGE_DISTRO:-${KAS_CONTAINER_IMAGE_DISTRO_DEFAULT}}"
 	KAS_CONTAINER_IMAGE_NAME="${KAS_CONTAINER_IMAGE_NAME:-${KAS_CONTAINER_IMAGE_NAME_DEFAULT}}"
 	KAS_CONTAINER_IMAGE_PATH="${KAS_CONTAINER_IMAGE_PATH:-${KAS_CONTAINER_IMAGE_PATH_DEFAULT}}"
 	KAS_CONTAINER_IMAGE_DEFAULT="${KAS_CONTAINER_IMAGE_PATH}/${KAS_CONTAINER_IMAGE_NAME}:${KAS_IMAGE_VERSION}"
 	KAS_CONTAINER_IMAGE="${KAS_CONTAINER_IMAGE:-${KAS_CONTAINER_IMAGE_DEFAULT}}"
+	if [ -n "${KAS_CONTAINER_IMAGE_DISTRO}" ]; then
+		KAS_CONTAINER_IMAGE="${KAS_CONTAINER_IMAGE}-${KAS_CONTAINER_IMAGE_DISTRO}"
+	fi
 }
 
 # SC2034: DIR appears unused (ignore, as they are used inside eval)