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 / TPM2 Images
Before building any image with the _tpm2, _trustedboot, or _secureboot feature, generate the signing certificates:
./cert/buildDo 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.
Troubleshooting
If you encounter build failures, refer to the Garden Linux builder troubleshooting section.