How gardenlinux/gardenlinux works
Project type and purpose
• This is an open-source operating-system image build toolkit (“Garden Linux”) rather than a traditional web or microservice application.
• It orchestrates assembling a custom Linux root filesystem and initramfs by combining:
• A minimal “base” OS package set and dracut + kernel configuration
• A set of modular “features” (each in its own directory under features/)
• Flavor definitions (bare_flavors/ and flavors.yaml) for different target runtimes (bare‐metal containers, Python, Node.js, cloud images, etc.)
• It produces outputs such as OCI container images, cloud disk images (AWS AMIs, Azure VHDs, OpenStack QCOW2), ISO/ PXE images, and signed artifacts.
File structure
• Top‐level orchestration:
• Makefile, VERSION files, bin/ (shell and Python scripts to drive builds), hack/ (helper scripts), tools/
• .github/workflows/ (CI definitions for build, test, nightly, release, S3/OCI publishing)
• Core modules and inputs:
• features/ – each subdirectory is a self-contained plugin defining file.include/exclude, package lists, dracut modules, tests, and metadata (info.yaml)
• bare_flavors/ – minimal rootfs definitions per language/runtime
• flavors.yaml – maps flavor names to features & bare_flavors sets
• Build artifacts and outputs:
• build/ and build_bare_flavors/ (intermediate)
• cert/ for signing keys and configs
• images/ (Containerfiles for kmodbuild image)
• Testing:
• tests/, tests/images/, tests/platformSetup/ – PyTest suites, chroot/container harnesses, Terraform modules for platform integration tests
README for additional insights
• (No content provided, but typical sections would describe the build pipeline, plugin system, CI flow, and publish targets.)
a. Main components
• Developer / GitHub (source code, PRs)
• CI Orchestrator (GitHub Actions workflows)
• Build Engine (Docker/Podman on CI runners or local make)
• Core Build Orchestrator Scripts (Makefile, bin/, hack/)
• Plugin Registry (features/)
• Flavor Definitions (bare_flavors/, flavors.yaml)
• Signing Subsystem (cert/)
• Test Harness (tests/, platformSetup/)
• Artifact Store(s)
– OCI registry (publish_oci_containers.yml)
– S3 buckets (publish_s3.yml)
– AMI registries (AWS, GCP, Azure pipelines)
b. Relationships / data flows
1. Developer merges code → triggers GitHub Actions
2. CI runner checks out code → invokes build workflows:
– Lint / shellcheck / static checks
– Build bare_flavors (docker build of minimal images)
– Combine bare_flavors + features → Containerfile dracut build → produce rootfs + initramfs
– Package and sign with cert/
3. Run tests in containers or chroots (tests/platformSetup or Terraform)
4. Publish artifacts to external stores (OCI registry, S3, AMI catalogs)
c. Architectural patterns / principles
• Modular plugin architecture: each feature encapsulates its files, config, and tests.
• Convention-over-configuration: features follow a uniform layout; flavors.yaml drives composition.
• CI-driven reproducibility: workflows define matrix builds for each flavor/platform.
• Separation of concerns:
– Orchestrator scripts (bin/, hack/) vs. plugin code (features/) vs. test code (tests/)
d. Key technologies / frameworks
• Docker/Podman + Containerfile-based builds
• dracut for generating initramfs
• GitHub Actions for CI/CD
• Bash, Python (bin/*.py, tests in pytest)
• Terraform modules (tests/platformSetup/tofu) for integration tests
Elements
• Clear labels for each component (e.g., “Feature Plugin”, “Flavor Definition”, “CI Runner”, “OCI Registry”).
– Trigger flow (Dev → GitHub Actions → Build Engine)
– Data flow (features + flavors → rootfs image → signed artifact → external store)
– Test invocation flows (test harness → container or chroot)
– Green for CI/CD pipelines (GitHub Actions workflows)
– Yellow for external services (Docker Engine, S3, OCI Registry, Cloud APIs)
– Gray for artifacts (images/, build/)