Garden Linux

Garden Linux is a Debian GNU/Linux derivate that aims to provide small, auditable Linux images for most cloud providers (e.g. AWS, Azure, GCP etc.) and bare-metal machines. Garden Linux is the best Linux for Gardener nodes. Garden Linux provides great possibilities for customizing that is made by a highly customizable feature set to fit your needs.

Table of Contents

• Garden Linux
• Features
• Build
  • Build Requirements
  • Parallel Builds
  • Cross Architecture Builds
  • SELinux
  • Secureboot
  • Maintained Images
• Building 934
• Tests
• Deploying
• Release
• Documentation
  • Continuous Integration
  • Integration Tests
• Contributing
• Community

Features

• Easy to use build system
• Repeatable and auditable builds
• Small footprint
• Purely systemd based (network, fstab etc.)
• Initramfs is dracut generated
• Running latest LTS Kernel
• MIT license
• Security
  • Fully immutable image(s) (optional)
  • OpenSSL 3.0 (default)
  • CIS Framework (optional)
• Testing
  • Unit tests (Created image testing)
  • Integration tests (Image integration tests in all supported platforms)
  • License violations (Testing for any license violations)
  • Outdated software versions (Testing for outdated software)
• Supporting major platforms out-of-the-box
  • Major cloud providers AWS, Azure, Google, Alicloud
  • Major virtualizer VMware, OpenStack, KVM
  • Bare-metal systems

Build

The build system utilises the gardenlinux/builder to create customized Linux distributions. gardenlinux/gardenlinux is maintained by the Garden Linux team, highlighting specialized "features" available for other projects.

To initiate a build, use the command:

./build ${platform}-${feature}_${modifier}

Where:

• ${platform} denotes the desired platform (e.g., kvm, metal, aws).
• ${feature} represents a specific feature from the features/ folder.
• ${modifier} is an optional modifier from the features/ folder, prefixed with an underscore "_".

You can combine multiple platforms, features, and modifiers as needed.

Example:

./build kvm-python_dev

The build script fetches the required builder container and manages all internal build steps. By default, it uses rootless podman, but you can switch to another container engine with the --container-engine flag.

Build Requirements

• Memory: The build process may require up to 8GiB of memory, depending on the selected targets. If your system has insufficient RAM, configure swap space accordingly.
• Container Engine: The Builder has minimal dependencies and only requires a working container engine. You have two options:
  • Rootless Podman: It's recommended to use rootless Podman. Please refer to the Podman rootless setup guide for instructions on setting it up.
  • Sudo Podman: Alternatively, you can use Podman with sudo for elevated privileges.

To ensure a successful build, please refer to the Build Requirements section in the gardenlinux/builder repository.

Parallel Builds

For efficient parallel builds of multiple targets, use the -j ${number_of_threads} option in the build script. However, note the following:

• Building in parallel significantly increases memory usage.
• There are no mechanisms in place to handle memory exhaustion gracefully.
• This feature is only recommended for users with large build machines, ideally with 8GiB of RAM per builder thread. It may work with 4GiB per thread due to spikes in memory usage being only intermittent during the build, but your milage may vary.

Cross Architecture Builds

By default, the build targets the native architecture of the build system. However, cross-building for other architectures is simple.

Append the target architecture to the target name in the build command, like so: ./build ${target}-${arch}. For example, to build for both amd64 and arm64 architectures:

./build kvm-amd64 kvm-arm64

This requires setting up binfmt_misc handlers for the target architecture, allowing the system to execute foreign binaries.

On most distributions, you can install QEMU user static to set up binfmt_misc handlers. For example, on Debian, use the command apt install qemu-user-static.

SELinux

If you intend to build targets with the _selinux feature, some additional requirements apply to the build machine.

Building the _selinux feature will not work on machines running in SELinux enforcing mode. Ideally, you should build on a machine with SELinux disabled. However, if you want to build with SELinux in permissive mode, this can be achieved by running the build as root with the --privileged flag.

i.e.: sudo ./build --privileged ${target}

SELinux Workaround for Podman:

⚠️ Note: Podman Desktop and Podman on macOS have by default SELinux enabled in their VMs. This may cause issues when building the _selinux feature. See issue #16 for details.

If you're using Podman on macOS, follow these steps to disable SELinux in the podman VM:

1. SSH into the Podman VM: podman machine ssh
2. Run the following command to disable SELinux: echo SELINUX=disabled | sudo tee /etc/selinux/config
3. Exit the SSH connection.
4. Restart the Podman VM: podman machine stop && podman machine start

Secureboot

If you intend to build targets with the _secureboot feature, you must first build the secureboot certificates. Run the command ./cert/build to generate the secureboot certificates.

By default, the command uses local files as the private key storage. However, you can configure it to use the AWS KMS key store by using the --kms flag. Note that valid AWS credentials need to be configured using the standard AWS environment variables.

Maintained Images

Garden Linux offers a range of official images tailored for various architectures and platforms. Instead of listing all the specific image variants here, you can find the most up-to-date list of maintained images on the Garden Linux releases page on GitHub.

Supported Architectures:

• arm64
• amd64

Supported Platforms:

Name	Identifier
Ali	ali
AWS	aws
Azure	azure
GCP	gcp
KVM	kvm
Metal	metal
OpenStack	openstack
VMware	vmware

To understand the build process for these images, refer to the build action. For details on the publishing process, check out the upload action and the gardenlinux/glci repository.

Building 934

For the sake of reproducibility, the earlier versions like 934 use the old Garden Linux builder.

Here's a quick guide on building the 934 image:

git checkout rel-934
# Ensure you're working in a clean environment (optional but recommended)
make clean
make aws-prod

If you encounter any issues specifically with the 934 build, please open an issue on our GitHub repository. Make sure to mention that your issue pertains to the 934 build for clarity.

Tests

To run unit tests for a specific target, use the command ./test ${target}.

Deploying

Deploying on common cloud platforms requires additional packages. The following overview gives a short quick start to run cloud platform deployments. Currently, all modules are based on Python. Therefore, please make sure to have Python installed.

Platform	Module
Alicloud	Aliyun CLI
AWS	AWS CLI
Azure	Azure CLI
GCP	Cloud SDK, gsutil
OpenStack	OpenStackCLI

Release

Garden Linux frequently publishes snapshot releases. These are available as machine images in most major cloud providers as well as file-system images for manual import. See the releases page for more info.

Documentation

Garden Linux provides a great documentation for build options, customizing, configuration, tests and pipeline integrations. The documentation can be found within the project's docs/ path or by clicking here. Next to this, you may find a corresponding README.md in each directory explaining some more details. Below, you may find some important documentations for continuous integration and integration tests.

Continuous Integration

Garden Linux can build in an automated way for continuous integration. See .github/workflows/README.md for details.

Integration Tests

While it may be confusing for beginners we highlight this chapter for integration tests here. Garden Linux supports integration testing on all major cloud platforms (Alicloud, AWS, Azure, GCP). To allow testing even without access to any cloud platform we created an universal kvm platform that may run locally and is accessed in the same way via a ssh client object as any other cloud platform. Therefore, you do not need to adjust tests to perform local integration tests. Just to mention here that there is another platform called chroot. This platform is used to perform unit tests and will run as a local integration test. More details can be found within the documentation in tests/README.md.

Contributing

Feel free to add further documentation, to adjust already existing one or to contribute with code. Please take care about our style guide and naming conventions. More information are available in in CONTRIBUTING.md and our docs/. Be aware that this repository leverages the gardenlinux/builder for creating customized Linux distributions. While gardenlinux/gardenlinux is a representation of one such distribution.

Community

Garden Linux has a large grown community. If you need further assistance, have any issues or just want to get in touch with other Garden Linux users feel free to join our public chat room on Gitter.

Link: https://gitter.im/gardenlinux/community