Building in a Container

The kas-container script is a wrapper to run kas inside a build container. It gives fine grained control over the data that is mapped into the build and decouples the build environment from the host system. For details, see Environment Variables. The wrapper also takes care of mounting the necessary directories and setting up the environment variables inside the container.

Note

The kas-container script has limited support for Git worktrees. Regular Git operations on the checked-out repository are supported. However, executing any git worktree ... command inside the container is not allowed.

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 kas-container script version should match the kas version inside the container. If kas detects that is was called 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 Environment Variables.

Running under docker in rootless mode 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.

Synopsis

kas-container [OPTIONS] { build | shell } [KASOPTIONS] [KASFILE]
kas-container [OPTIONS] { checkout | dump | lock } [KASOPTIONS] [KASFILE]
kas-container [OPTIONS] { diff } [KASOPTIONS] config1 config2
kas-container [OPTIONS] for-all-repos [KASOPTIONS] [KASFILE] COMMAND
kas-container [OPTIONS] { clean | cleansstate | cleanall | purge} [KASFILE]
kas-container [OPTIONS] menu [KCONFIG]

kas-container Commands

build

Check out repositories and build target.

checkout

Check out repositories but do not build.

diff

Compare two kas configurations.

dump

Check out repositories and write flat version of config to stdout.

lock

Create and update kas project lockfiles.

shell

Run a shell in the build environment.

for-all-repos

Run specified command in each repository.

clean

Clean build artifacts, keep sstate cache and downloads.

cleansstate

Clean build artifacts and sstate cache, keep downloads.

cleanall

Clean build artifacts, sstate cache and downloads.

purge

Remove all data managed by kas. Run with ‘–dry-run’ to check what would be removed.

menu

Provide configuration menu and trigger configured build.

Options

--isar-privileged

Run an Isar build in privileged mode. To force the use

--isar-rootless

Run an Isar build in rootless mode.

--runtime-args

Additional arguments to pass to the container runtime.

-l, --log-level

Set log level (default=info).

--version

Print program version.

--ssh-dir

Directory containing SSH configurations.

--ssh-agent

Forward ssh-agent socket to the container.

--aws-dir

Directory containing AWScli configuration.

--git-credential-store

File path to the git credential store.

--git-credential-socket

Path to the git credential cache socket.

--no-proxy-from-env

Do not inherit proxy settings from environment.

--repo-ro

Mount current repository read-only

--repo-rw

Mount current repository writable

-h, --help

Show this help message and exit.

Note

When using --aws-dir ~/.aws the entire content of ~/.aws/sso/cache directory is copied into the kas workspace. This might expose all active user sessions, including those not defined in the AWS_CONFIG_FILE. To mitigate security risks, log out of unnecessary profiles before starting a build or use a separate system account to run the build.