[PATCH] docs: Improve setup description for kas-container

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

There are multiple combinations possible with Docker, Podman, rootless
etc. Describe them in more details, guiding users towards unprivileged
Podman where possible.

Move this part up the section as it is more important than customizing
the container images.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---
docs/userguide/kas-container-description.inc | 48 ++++++++++++--------
1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/docs/userguide/kas-container-description.inc b/docs/userguide/kas-container-description.inc
index 62a7932..2414940 100644
--- a/docs/userguide/kas-container-description.inc
+++ b/docs/userguide/kas-container-description.inc
@@ -11,6 +11,35 @@ container.
executing any ``git worktree ...`` command inside the container is not
allowed.

+As container backends, Docker and Podman are supported. If both backends are
+installed, Docker is preferred, except when the build system is
+`isar-rootless`, in which case Podman is the default. To force the use of a
+specific backend, set, e.g., ``KAS_CONTAINER_ENGINE=podman``. See
+:ref:`env-vars-label` for details.
+
+The simplest and therefore recommended setup for secure rootless operation is
+via Podman. Running under docker in
+`rootless mode <https://docs.docker.com/engine/security/rootless/>`_ is
+partially supported. For rootless Docker, it is recommended to use a distinct
+``KAS_WORK_DIR`` outside of the calling directory (repo-dir), as kas
+temporarily changes the ownership of the working directory during its
+operation. All files managed by kas (including the repos) must not be written
+to from the host. To completely remove all data managed by kas, use
+``kas-container purge``. This also restores the directory owners of the dirs
+passed to kas, so they can be removed from the host.
+
+If you need to use Docker in system mode instead, make sure that the invoking
+user is part of the respective group. System Podman will be invoked via `sudo`
+by `kas-container`, and you will have to configure the system accordingly so
+that this path is permitted. However, be warned about the security
+implications of both of these setups as they are granting root permissions to
+the build jobs.
+
+.. note::
+ The ISAR build system is compatible with rootless execution in
+ ``isar-rootless`` mode only. The ``isar`` and ``isar-privileged`` modes
+ fall back to the system Docker or Podman instance.
+
By default ``kas-container`` uses the official images provided by the kas
project: ``ghcr.io/siemens/kas/kas[-isar]:<version>``. To specify your own
image set the ``KAS_CONTAINER_IMAGE`` environment variable. The
@@ -28,22 +57,3 @@ or ``debian-trixie``). The corresponding image tags follow the pattern
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`.
-
-Running under docker in
-`rootless mode <https://docs.docker.com/engine/security/rootless/>`_ is
-partially supported. It is recommended to use a distinct ``KAS_WORK_DIR``
-outside of the calling directory (repo-dir), as kas temporarily changes the
-ownership of the working directory during its operation. All files managed by
-kas (including the repos) must not be written to from the host. To completely
-remove all data managed by kas, use ``kas-container purge``. This also restores
-the directory owners of the dirs passed to kas, so they can be removed from the
-host.
-
-.. note::
- The ISAR build system is compatible with rootless execution in
- ``isar-rootless`` mode only. The ``isar`` and ``isar-privileged`` modes
- fall back to the system docker or podman instance.
--
2.47.3

[Jan Kiszka]

From: Jan Kiszka <jan.k...@siemens.com>

There are multiple combinations possible with Docker, Podman, rootless
etc. Describe them in more details, guiding users towards unprivileged
Podman where possible.

Move this part up the section as it is more important than customizing
the container images.

Signed-off-by: Jan Kiszka <jan.k...@siemens.com>
---

Changes in v2:
- fix wrong single-tick usage

docs/userguide/kas-container-description.inc | 48 ++++++++++++--------
1 file changed, 29 insertions(+), 19 deletions(-)

diff --git a/docs/userguide/kas-container-description.inc b/docs/userguide/kas-container-description.inc

index 62a7932..74459fb 100644

--- a/docs/userguide/kas-container-description.inc
+++ b/docs/userguide/kas-container-description.inc
@@ -11,6 +11,35 @@ container.
executing any ``git worktree ...`` command inside the container is not
allowed.

+As container backends, Docker and Podman are supported. If both backends are
+installed, Docker is preferred, except when the build system is
+``isar-rootless``, in which case Podman is the default. To force the use of a
+specific backend, set, e.g., ``KAS_CONTAINER_ENGINE=podman``. See
+:ref:`env-vars-label` for details.
+
+The simplest and therefore recommended setup for secure rootless operation is
+via Podman. Running under docker in
+`rootless mode <https://docs.docker.com/engine/security/rootless/>`_ is
+partially supported. For rootless Docker, it is recommended to use a distinct
+``KAS_WORK_DIR`` outside of the calling directory (repo-dir), as kas
+temporarily changes the ownership of the working directory during its
+operation. All files managed by kas (including the repos) must not be written
+to from the host. To completely remove all data managed by kas, use
+``kas-container purge``. This also restores the directory owners of the dirs
+passed to kas, so they can be removed from the host.
+
+If you need to use Docker in system mode instead, make sure that the invoking
+user is part of the respective group. System Podman will be invoked via

+``sudo`` by ``kas-container``, and you will have to configure the system
+accordingly so that this path is permitted. However, be warned about the
+security implications of both of these setups as they are granting root
+permissions to the build jobs.