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 not compatible with rootless execution. By that, we fall back to the system docker or podman instance.
Synopsis
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
Use kas-isar container to build Isar image. To force the use of run0 over sudo, set KAS_SUDO_CMD=run0.
- --with-loop-dev
Pass a loop device to the container. Only required if loop-mounting is used by recipes.
- --runtime-args
Additional arguments to pass to the container runtime for running the build.
- -l, --log-level
Set log level (default=info).
- --version
print program version.
- --ssh-dir
Directory containing SSH configurations. Avoid $HOME/.ssh unless you fully trust the container.
- --ssh-agent
Forward ssh-agent socket to the container.
- --aws-dir
Directory containing AWScli configuration. Avoid $HOME/.aws unless you fully trust the container.
- --git-credential-store
File path to the git credential store
- --no-proxy-from-env
Do not inherit proxy settings from environment.
- --repo-ro
Mount current repository read-only (default for build command)
- --repo-rw
Mount current repository writable (default for shell command)
- -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.