Building Images
This guide walks you through building Garden Linux images locally. For conceptual background on how the build system works, see Builder Explanation.
Prerequisites
Provide at least 8 GiB of RAM to the container runtime or the
virtual machine hosting it (in Podman Desktop or Docker Desktop). The build may fail silently if memory is insufficient. :::
You need a working container engine. Three options are supported:
- Rootless Podman (recommended) — See the Podman rootless setup guide for setup instructions.
- Podman with
rootprivileges - Rooless Docker - See the Docker Rootless Mode Documentation
See Builder Command-Line Reference how to
pass the container engine. :::
Build an Image
Run the build script with the flavor ({cname}-{arch}):
./build ${platform}-${feature1}-${feature2}-${arch}Where:
${platform}— the target platform (e.g.kvm,metal,aws); must be the first component.${featureX}— one or more features from thefeatures/directory, separated by-(or_for features whose names begin with_).${arch}— optional target architecture (amd64orarm64); must be the last component. Defaults to the host architecture when omitted.
Partial arguments are accepted
You can pass any subset of the full naming hierarchy: a bare cname (e.g. aws-gardener_prod), a flavor (cname + arch, e.g. aws-gardener_prod-amd64), or a versioned flavor (flavor + version, e.g. aws-gardener_prod-amd64-1877.3). Any missing component is resolved automatically: architecture defaults to the host architecture, and version is read from the VERSION file via ./get_version.
Examples:
./build kvm-python_dev
./build aws-gardener_prod-amd64For a full list of build script options, see the Builder Command-Line Reference.
For help choosing a flavor, see Choosing Flavors.
Run Parallel Builds
To build multiple targets simultaneously, use the -j flag:
./build -j 4 kvm-amd64 kvm-arm64 aws-gardener_prod-amd64 aws-gardener_prod-arm64Parallel builds multiply memory usage. Allow at least **8 GiB per
thread**. There are no safeguards against memory exhaustion; builds may fail silently if memory runs out. :::
Build for a Different Architecture
Append the target architecture to the flavor name:
./build kvm-amd64 kvm-arm64INFO
Cross-architecture builds require binfmt_misc handlers and QEMU user-mode emulation (qemu-user-static) on the build host.
apt install qemu-user-staticBuild Secureboot, Trustedboot and TPM2 Images
Before building any image with the _tpm2 or _trustedboot feature, generate the signing certificates:
./cert/buildTIP
Do not use the Makefile in cert/ directly. Always use ./cert/build. If ./cert/build fails, try running ./cert/build clean first.
By default, private keys are stored locally in the cert/ directory. To use AWS Key Management Service instead, pass the --kms flag (valid AWS credentials must be configured via the standard AWS environment variables):
./cert/build --kmsAfter generating certificates, build the image as normal:
./build kvm-trustedboot
./build aws-trustedboot_tpm2For conceptual background on these features, see Boot Modes and Secure Boot and Trusted Boot. For cloud deployment steps, see Deploying Secure Boot Images.