From b5262e0bf409065ee1b9d62f4d0270695d9081a2 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 8 Apr 2026 08:27:16 +0200 Subject: [PATCH 1/6] docs: move to Diataxis structre Signed-off-by: Eike Waldt On-behalf-of: SAP --- README.md | 827 +---------------- docs/explanation/.gitkeep | 0 docs/how-to/.gitkeep | 0 docs/overview/README.md | 869 ++++++++++++++++++ .../overview/assets/glrd-overview.excalidraw | 0 .../overview/assets/glrd-overview.png | Bin 6 files changed, 870 insertions(+), 826 deletions(-) mode change 100644 => 120000 README.md create mode 100644 docs/explanation/.gitkeep create mode 100644 docs/how-to/.gitkeep create mode 100644 docs/overview/README.md rename assets/overview.excalidraw => docs/overview/assets/glrd-overview.excalidraw (100%) rename assets/overview.png => docs/overview/assets/glrd-overview.png (100%) diff --git a/README.md b/README.md deleted file mode 100644 index 41436ca..0000000 --- a/README.md +++ /dev/null @@ -1,826 +0,0 @@ -# Garden Linux Release Database (GLRD) - -This repository contains tooling and configuration to create the Garden Linux Release Database (GLRD), a system designed to manage and query release information for the Garden Linux distribution. - -This repository contains these tools: - -- **`glrd-manage`**: A tool for generating and populating the GLRD with initial release data and for creating individual release entries. -- **`glrd`**: A command-line client for querying the GLRD to retrieve release information based on various criteria. - -## Table of Contents - -- [Garden Linux Releases](#garden-linux-releases) -- [Overview of GLRD](#overview) -- [Prerequisites](#prerequisites) -- [Run GLRD](#run-glrd) -- [glrd](#glrd) -- [glrd-manage](#glrd-manage) -- [Release Schema](#release-schema) -- [Contributing](#contributing) -- [License](#license) - -## Garden Linux Releases - -For a general overview about Garden Linux releases and their lifecycle, have a look at the [Garden Linux Release Plan Overview](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md). - -## Overview - -The GLRD provides a structured way to store and access release data for Garden Linux, including different release types such as major, minor, nightly, and development releases. It uses JSON and YAML formats to store release information and supports integration with AWS S3 for storage to host release data.. - -![Overview](assets/overview.png) - -## Run GLRD - -### Manually run Python scripts - -
- Details - -### Prerequisites - -- **Python 3.10+** - -You can install the required Python packages using: - -```bash -poetry install -``` - -- **AWS CLI** configured with appropriate permissions if you plan to use S3 integration. -- **Git** and **GitHub CLI (gh)** installed and configured if you plan to generate release data from GitHub. - -### Installation - -Clone the repository and ensure that the scripts are executable: - -```bash -git clone https://github.com/gardenlinux/glrd.git -cd glrd -poetry install -``` - -
- -### Run in container - -
- Details - -You can also use the GLRD tools by building or running a container image. - -#### Run pre-build image - -``` -podman run -it --rm ghcr.io/gardenlinux/glrd glrd -podman run -it --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN ghcr.io/gardenlinux/glrd glrd-manage - -``` - -#### Build and run image locally - -``` -podman build -t glrd . -podman run -it --rm glrd glrd -podman run -it --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN glrd glrd-manage -``` - -
- -### Run in GitHub action - -
- Details - -``` - - name: Get latest GL minor version - id: gl_version_latest - uses: gardenlinux/glrd@main - with: - cmd: glrd --no-header --type minor --latest --fields Version - - name: Use latest GL minor version - run: echo ${{ steps.gl_version_latest.outputs.result }} - - - name: Get latest GL nightly version - id: gl_version_nightly - uses: gardenlinux/glrd@main - with: - cmd: glrd --no-header --type nightly --latest --fields Version - - name: Use latest GL nightly version - run: echo ${{ steps.gl_version_nightly.outputs.result }} -``` - -
- -### Manually query JSON data - -
- Details - -You can manually query the release JSON data by getting them from our production S3 bucket. - -Query the release type that you want: - -- `releases-major.json` -- `releases-minor.json` -- `releases-nightly.json` -- `releases-dev.json` - -To e.g. query the major releases: - -```bash -❯ curl -s https://gardenlinux-glrd.s3.eu-central-1.amazonaws.com/releases-major.json -{"releases":[{"name":"major-27","type":"major","version":{"major":27},"lifecycle":{"released":{"isodate":"2020-06-09","timestamp":1591694693},"extended":{"isodate":"2020-12-09","timestamp":1607472000},"eol":{"isodate":"2021-03-09","timestamp":1615248000}}},{"name":"major-184","type":"major","version":{"major":184},"lifecycle":{"released":{"isodate":"2020-10-29","timestamp":1603984625},"extended":{"isodate":"2020-04-29","timestamp":1588118400},"eol":{"isodate":"2021-07-29","timestamp":1627516800}}},{"name":"major-318","type":"major","version":{"major":318},"lifecycle":{"released":{"isodate":"2021-04-28","timestamp":1619614135},"extended":{"isodate":"2021-10-28","timestamp":1635379200},"eol":{"isodate":"2023-01-28","timestamp":1674864000}}},{"name":"major-576","type":"major","version":{"major":576},"lifecycle":{"released":{"isodate":"2021-11-17","timestamp":1637142852},"extended":{"isodate":"2023-05-17","timestamp":1684281600},"eol":{"isodate":"2023-08-17","timestamp":1692230400}}},{"name":"major-934","type":"major","version":{"major":934},"lifecycle":{"released":{"isodate":"2023-06-05","timestamp":1685968163},"extended":{"isodate":"2023-12-05","timestamp":1701734400},"eol":{"isodate":"2024-03-05","timestamp":1709596800}}},{"name":"major-1312","type":"major","version":{"major":1312},"lifecycle":{"released":{"isodate":"2023-11-16","timestamp":1700136050},"extended":{"isodate":"2024-05-03","timestamp":1714694400},"eol":{"isodate":"2024-08-03","timestamp":1722643200}}},{"name":"major-1443","type":"major","version":{"major":1443},"lifecycle":{"released":{"isodate":"2024-03-13","timestamp":1710341636},"extended":{"isodate":"2024-09-13","timestamp":1726185600},"eol":{"isodate":"2025-01-13","timestamp":1736726400}}},{"name":"major-1592","type":"major","version":{"major":1592},"lifecycle":{"released":{"isodate":"2024-08-12","timestamp":1723457202},"extended":{"isodate":"2025-05-12","timestamp":1747008000},"eol":{"isodate":"2025-08-12","timestamp":1754956800}}}]} -``` - -
- -### AWS Authentication - -`glrd-manage` needs write access to an AWS S3 bucket to create and manage releases. See [Boto3 Credentials documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) and ways to configure this. -If you are running `glrd-manage` in a container, you might want to use [Environment variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#environment-variables) and pass those via e.g. `podman run ... -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN`. - -## glrd - -The `glrd` script is a command-line utility for querying the GLRD. It allows you to filter and display release information based on various criteria. - -### Usage - -#### Show help - -``` -❯ glrd --help -usage: glrd [-h] [--input-format {yaml,json}] [--input-file-prefix INPUT_FILE_PREFIX] [--input-type {file,url}] [--input-url INPUT_URL] [--no-input-split] [--output-format {json,yaml,markdown,mermaid_gantt,shell}] [--output-description OUTPUT_DESCRIPTION] [--active] [--archived] [--latest] [--type TYPE] [--version VERSION] [--fields FIELDS] [--no-header] [-V] - -Process and filter releases data from a file or URL. - -options: - -h, --help show this help message and exit - --input-format {yaml,json} - Input format: 'yaml' or 'json' (default: json). - --input-file-prefix INPUT_FILE_PREFIX - The prefix to get input files (default: releases). - --input-type {file,url} - Specify if the input type (default: url). - --input-url INPUT_URL - Input URL to the releases data. Defaults to gardenlinux-glrd S3 URL. - --no-input-split Do not split Input into major+minor and nightly. No additional input-files *-nightly and *-dev will be parsed. - --output-format {json,yaml,markdown,mermaid_gantt,shell} - Output format: json, yaml, markdown, mermaid_gantt, shell (default). - --output-description OUTPUT_DESCRIPTION - Description, added to certain outputs, e.g. mermaid (default: 'Garden Linux Releases'). - --active Show only active releases. - --archived Show only archived releases. - --latest Show the latest active major.minor release. - --type TYPE Filter by release types (comma-separated list, default: major,minor). E.g., --type major,minor,nightly,dev,next - --version VERSION Filter by a specific version (major, major.minor, or major.minor.patch). E.g., --version 1312, --version 1312.0, or --version 2017.0.0 - --fields FIELDS Comma-separated list of fields to output. Possible fields: Name,Version,Type,GitCommit,GitCommitShort,ReleaseDate,ReleaseTime,ExtendedMaintenance,EndOfMaintenance,Flavors,OCI,AttributesSourceRepo (default: Name,Version,Type,GitCommitShort,ReleaseDate,ExtendedMaintenance,EndOfMaintenance) - --no-header Omit the header in shell output. - -V show program's version number and exit -``` - -### Get latest Garden Linux Version - -#### Default shell output - -``` -# default shell output -❯ glrd --latest -Name Version Type GitCommitShort ReleaseDate ExtendedMaintenance EndOfMaintenance -minor-1592.6 1592.6 minor cb05e11f 2025-02-19 N/A 2025-08-12 -``` - -#### Get only version field - -``` -❯ glrd --latest --fields Version --no-header -1592.6 -``` - -#### Get JSON output - -
- Details - -``` -❯ glrd --latest --output-format json -{ - "releases": [ - { - "name": "minor-1592.6", - "type": "minor", - "version": { - "major": 1592, - "minor": 6 - // Note: patch field is only present for versions ≥ 2017.0.0 - }, - "lifecycle": { - "released": { - "isodate": "2025-02-19", - "timestamp": 1739951325 - }, - "eol": { - "isodate": "2025-08-12", - "timestamp": 1754956800 - } - }, - "git": { - "commit": "cb05e11f0481b72d0a30da3662295315b220a436", - "commit_short": "cb05e11f" - }, - "github": { - "release": "https://github.com/gardenlinux/gardenlinux/releases/tag/1592.6" - }, - "flavors": { - "ali-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-amd64-1592.6-cb05e11f/ali-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-amd64-1592.6-cb05e11f/ali-gardener_prod-amd64-1592.6-cb05e11f.qcow2" - }, - "ali-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-arm64-1592.6-cb05e11f/ali-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-arm64-1592.6-cb05e11f/ali-gardener_prod-arm64-1592.6-cb05e11f.qcow2" - }, - "aws-gardener_persistence_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "aws-gardener_persistence_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-amd64-1592.6-cb05e11f/aws-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-amd64-1592.6-cb05e11f/aws-gardener_prod-amd64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-arm64-1592.6-cb05e11f/aws-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-arm64-1592.6-cb05e11f/aws-gardener_prod-arm64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "aws-gardener_prod_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "azure-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-amd64-1592.6-cb05e11f/azure-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-amd64-1592.6-cb05e11f/azure-gardener_prod-amd64-1592.6-cb05e11f.vhd" - }, - "azure-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-arm64-1592.6-cb05e11f/azure-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-arm64-1592.6-cb05e11f/azure-gardener_prod-arm64-1592.6-cb05e11f.vhd" - }, - "gcp-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-amd64-1592.6-cb05e11f/gcp-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-amd64-1592.6-cb05e11f/gcp-gardener_prod-amd64-1592.6-cb05e11f.gcpimage.tar.gz" - }, - "gcp-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-arm64-1592.6-cb05e11f/gcp-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-arm64-1592.6-cb05e11f/gcp-gardener_prod-arm64-1592.6-cb05e11f.gcpimage.tar.gz" - }, - "gdch-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-amd64-1592.6-cb05e11f/gdch-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-amd64-1592.6-cb05e11f/gdch-gardener_prod-amd64-1592.6-cb05e11f.gcpimage.tar.gz" - }, - "gdch-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-arm64-1592.6-cb05e11f/gdch-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-arm64-1592.6-cb05e11f/gdch-gardener_prod-arm64-1592.6-cb05e11f.gcpimage.tar.gz" - }, - "kvm-gardener_persistence_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_persistence_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-amd64-1592.6-cb05e11f/kvm-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-amd64-1592.6-cb05e11f/kvm-gardener_prod-amd64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-arm64-1592.6-cb05e11f/kvm-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-arm64-1592.6-cb05e11f/kvm-gardener_prod-arm64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "kvm-gardener_prod_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "metal-gardener_persistence_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "metal-gardener_persistence_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-amd64-1592.6-cb05e11f/metal-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-amd64-1592.6-cb05e11f/metal-gardener_prod-amd64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-arm64-1592.6-cb05e11f/metal-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-arm64-1592.6-cb05e11f/metal-gardener_prod-arm64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_pxe-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_pxe-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_readonly_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_readonly_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_secureboot-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" - }, - "metal-gardener_prod_secureboot-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" - }, - "openstack-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-amd64-1592.6-cb05e11f/openstack-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-amd64-1592.6-cb05e11f/openstack-gardener_prod-amd64-1592.6-cb05e11f.qcow2" - }, - "openstack-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-arm64-1592.6-cb05e11f/openstack-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-arm64-1592.6-cb05e11f/openstack-gardener_prod-arm64-1592.6-cb05e11f.qcow2" - }, - "openstackbaremetal-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f.qcow2" - }, - "openstackbaremetal-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f.qcow2" - }, - "vmware-gardener_prod-amd64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-amd64-1592.6-cb05e11f/vmware-gardener_prod-amd64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-amd64-1592.6-cb05e11f/vmware-gardener_prod-amd64-1592.6-cb05e11f.ova" - }, - "vmware-gardener_prod-arm64": { - "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-arm64-1592.6-cb05e11f/vmware-gardener_prod-arm64-1592.6-cb05e11f.manifest", - "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-arm64-1592.6-cb05e11f/vmware-gardener_prod-arm64-1592.6-cb05e11f.ova" - } - }, - "oci": "ghcr.io/gardenlinux/gardenlinux:1592.6", - "attributes": { - "source_repo": true - } - } - ] -} -``` - -
- -#### Get json output and filter for version - -``` -❯ glrd --latest --output-format json | jq -r '.releases[] | "\(.version.major).\(.version.minor)"' -1592.6 -``` - -**Note**: For versions ≥ 2017.0.0, you can also filter by patch version: `jq -r '.releases[] | "\(.version.major).\(.version.minor).\(.version.patch)"'` - -### Get all active and supported Garden Linux Versions - -``` -❯ glrd --active -Name Version Type Git Commit Release date Extended maintenance End of maintenance -major-1443 1443 major N/A 2024-03-13 2024-09-13 2025-01-13 -minor-1443.15 1443.15 minor 5d33a69 2024-10-10 N/A 2025-01-13 -major-1592 1592 major N/A 2024-08-12 2025-05-12 2025-08-12 -minor-1592.1 1592.1 minor ec945aa 2024-08-22 N/A 2025-08-12 -``` - -### Create [Mermaid Gantt Chart](https://mermaid.js.org/syntax/gantt.html) for active releases - -``` -❯ glrd --active --type next,major --output-format mermaid_gantt --output-description "Garden Linux active Releases" -gantt - title Garden Linux active Releases - axisFormat %m.%y - section 1443 - Release: milestone, 2024-03-13, 0m - Standard maintenance: task, 2024-03-13, 6M - Extended maintenance: milestone, 2024-09-13, 0m - Extended maintenance: task, 2024-09-13, 4M - End of maintenance: milestone, 2025-01-13, 0m - section 1592 - Release: milestone, 2024-08-12, 0m - Standard maintenance: task, 2024-08-12, 9M - Extended maintenance: milestone, 2025-05-12, 0m - Extended maintenance: task, 2025-05-12, 3M - End of maintenance: milestone, 2025-08-12, 0m - section next - Release: milestone, 2024-12-01, 0m - Standard maintenance: task, 2024-12-01, 6M - Extended maintenance: milestone, 2025-06-01, 0m - Extended maintenance: task, 2025-06-01, 3M - End of maintenance: milestone, 2025-09-01, 0m -``` - -## glrd-manage - -The `glrd-manage` script is used to generate release data for Garden Linux. It can create initial releases by fetching data from GitHub, generate individual release entries, and manage release data files. - -### Show help - -``` -❯ glrd-manage --help -usage: glrd-manage [-h] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--input-file INPUT_FILE] [--output-format {yaml,json}] [--output-file-prefix OUTPUT_FILE_PREFIX] [--s3-bucket-name S3_BUCKET_NAME] [--s3-bucket-region S3_BUCKET_REGION] [--s3-bucket-prefix S3_BUCKET_PREFIX] [--delete DELETE] [--create-initial-releases CREATE_INITIAL_RELEASES] [--create CREATE] - [--version VERSION] [--commit COMMIT] [--lifecycle-released-isodatetime LIFECYCLE_RELEASED_ISODATETIME] [--lifecycle-extended-isodatetime LIFECYCLE_EXTENDED_ISODATETIME] [--lifecycle-eol-isodatetime LIFECYCLE_EOL_ISODATETIME] [--no-query] [--input-stdin] [--input] [--no-output-split] [--s3-create-bucket] [--s3-update] [--output-all] [--input-all] [-V] - -Manage Garden Linux releases data. - -options: - -h, --help show this help message and exit - --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} - Set the logging level - --input-file INPUT_FILE - The name of the input file (default: releases-input.yaml). - --output-format {yaml,json} - Output format: yaml or json (default: yaml). - --output-file-prefix OUTPUT_FILE_PREFIX - The prefix for output files (default: releases). - --s3-bucket-name S3_BUCKET_NAME - Name of S3 bucket. Defaults to 'gardenlinux-glrd'. - --s3-bucket-region S3_BUCKET_REGION - Region for S3 bucket. Defaults to 'eu-central-1'. - --s3-bucket-prefix S3_BUCKET_PREFIX - Prefix for S3 bucket objects. Defaults to empty string. - --delete DELETE Delete a release by name (format: type-major.minor). Requires --s3-update. - --create-initial-releases CREATE_INITIAL_RELEASES - Comma-separated list of initial releases to retrieve and generate: 'major,minor,nightly'. - --create CREATE Create a release for this type using the current timestamp and git information (choose one of: major,minor,nightly,dev,next)'. - --version VERSION Manually specify the version (format: major.minor for versions < 2017.0.0, major.minor.patch for versions ≥ 2017.0.0). - --commit COMMIT Manually specify the git commit hash (40 characters). - --lifecycle-released-isodatetime LIFECYCLE_RELEASED_ISODATETIME - Manually specify the release date and time in ISO format (YYYY-MM-DDTHH:MM:SS). - --lifecycle-extended-isodatetime LIFECYCLE_EXTENDED_ISODATETIME - Manually specify the extended maintenance date and time in ISO format (YYYY-MM-DDTHH:MM:SS). - --lifecycle-eol-isodatetime LIFECYCLE_EOL_ISODATETIME - Manually specify the EOL date and time in ISO format (YYYY-MM-DDTHH:MM:SS). - --no-query Do not query and use existing releases using glrd command. Be careful, this can delete your releases. - --input-stdin Process a single input from stdin (JSON data). - --input Process input from --input-file. - --no-output-split Do not split Output into major+minor and nightly. Additional output-files *-nightly and *-dev will not be created. - --s3-create-bucket Create an S3 bucket. - --s3-update Update (merge) the generated files with S3. - --output-all Download and write all release files found in S3 to local disk - --input-all Upload all local release files to S3 - -V show program's version number and exit -``` - -### Testing release creation - -Files named `releases-${type}.json` will be created in the current working directory. - -Without passing `--s3-update`, no actual update will be made and changes can safely be tested and verified locally. - -### Generate and populate initial release data - -This will generate the following initial release data ... - -- major releases -- minor releases -- nightly releases -- releases from `releases-input.yaml` (contain manual lifecycle fields) - -... and upload it to the default S3 bucket (if `--s3-update` is passed). - -``` -❯ glrd-manage --create-initial-releases major,minor,nightly --input -``` - -### Generate/Update an arbitrary release from JSON/YAML data - -This will generate/update a release from JSON data and upload it to the default S3 bucket. - -``` -❯ echo '{ - "releases": [ - { - "name": "minor-1592.1", - "type": "minor", - "version": { - "major": 1592, - "minor": 1 - }, - "lifecycle": { - "released": { - "isodate": "2024-08-22", - "timestamp": 1724277600 - }, - "eol": { - "isodate": "2025-08-12", - "timestamp": 1754949600 - } - }, - "git": { - "commit": "ec945aa995d0f08d64303ff6045b313b40b665fb", - "commit_short": "ec945aa" - }, - "github": { - "release": "https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1" - }, - "flavors": [ - "ali-gardener_prod", - "azure-gardener_prod", - "aws-gardener_prod", - "gcp-gardener_prod" - ], - "attributes": { - "source_repo": false - } - } - ] -}' | glrd-manage --input-stdin -``` - -Another approach is writing release YAML data to an input file and use this file as input parameter. - -``` -❯ cat releases-input.yaml -releases: - - name: minor-1592.1 - type: minor - version: - major: 1592 - minor: 1 - lifecycle: - released: - isodate: "2024-08-22" - timestamp: 1724277600 - eol: - isodate: "2025-08-27" - timestamp: 1754949600 - git: - commit: ec945aa995d0f08d64303ff6045b313b40b66fff - commit_short: ec945aa - github: - release: https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1 - flavors: - - ali-gardener_prod - - azure-gardener_prod - - aws-gardener_prod - - gcp-gardener_prod - attributes: - source_repo: false - -❯ glrd-manage --input --input-file releases-input.yaml -``` - -### Create or update a major release - -https://github.com/gardenlinux/glrd?tab=readme-ov-file#default-major-dates -When creating a new major release, [Default Major dates](#default-major-dates) can be automatically set for you. In addition to that, you can also overwrite the dates by hand. - -``` -# use default dates -❯ glrd-manage --create major --version 1312 - -# overwrite default dates -❯ glrd-manage --create major --version 1312 --date-time-released 2023-11-16T00:00:00 --date-time-extended 2024-05-03T00:00:00 --date-time-eol 2024-08-03T00:00:00 -``` - -### Create or update a minor release - -When creating a new minor release, the previous minor release of the same major release gets automatically updated. See [Lifecycle Dependencies](#major-and-minor-releases) for details. - -``` -# create new minor -❯ glrd-manage --create minor --version 1312.7 -``` - -### Create a new nightly release - -Without any additional parameters, the current timestamp and git information will be used to create releases. For minor, nightly and dev releases, the next free minor version is automatically chosen. - -``` -❯ glrd-manage --create nightly -``` - -## Release Schema - -The Garden Linux Release Database (GLRD) uses structured JSON schemas to represent different types of releases: **major**, **minor**, **nightly**, and **development** releases. Each release type has specific fields that capture essential information about the release. - -### Versioning Scheme - -Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gardenlinux/issues/3069) in [TODO!!! name commit !!!]. GLRD supports both versioning schemes based on the major version number: - -- **v1: Versions < 2017.0.0**: Use the `major.minor` format (e.g., `27.0`, `1592.6`) -- **v2: Versions ≥ 2017.0.0**: Use the `major.minor.patch` format (e.g., `2017.0.0`, `2222.1.5`) - -### Major Releases - -[Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases) are major releases that are supported over an extended period of time. - -#### Schema Fields - -- **`name`**: A string representing the release name (e.g., `major-1312`). -- **`type`**: `major`. -- **`version`**: - - **`major`**: An integer indicating the major version number (e.g. `1312`). -- **`lifecycle`**: - - **`released`**: - - **`isodate`**: The release date in ISO format (`YYYY-MM-DD`). - - **`timestamp`**: The UNIX timestamp of the release date. - - **`extended`**: - - **`isodate`**: Optional extended maintenance date in ISO format. - - **`timestamp`**: Optional UNIX timestamp for the extended maintenance date. - - **`eol`**: - - **`isodate`**: End-of-life date in ISO format. - - **`timestamp`**: UNIX timestamp for the end-of-life date. - -### Minor Releases - -[Minor Releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#minores) are updates delivered during the standard and extended mainteance periods of [Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases). - -#### Schema Fields - -- **`name`**: A string representing the release name (e.g., `minor-1312.1` for v1 versions, `minor-2017.0.0` for v2 versions). -- **`type`**: `minor`. -- **`version`**: - - **`major`**: An integer indicating the major version number (e.g. `1312`). - - **`minor`**: An integer indicating the minor version number (e.g. `1`). - - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). -- **`lifecycle`**: - - **`released`**: - - **`isodate`**: The release date in ISO format. - - **`timestamp`**: The UNIX timestamp of the release date. - - **`eol`**: - - **`isodate`**: End-of-life date in ISO format. - - **`timestamp`**: UNIX timestamp for the end-of-life date. -- **`git`**: - - **`commit`**: The full git commit hash associated with the release. - - **`commit_short`**: The short git commit hash (first 7 characters). -- **`github`**: - - **`release`**: The URL to the GitHub release page. -- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. -- **`attributes`**: An object that does contain additional metadata about the release. - - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). - -### Nightly Releases - -[Nightly releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#nightly-releases) are automated builds that are generated every night, reflecting the latest state of the codebase. - -#### Schema Fields - -- **`name`**: A string representing the release name (e.g., `nightly-1312.0` for v1 versions, `nightly-2017.0.0` for v2 versions). -- **`type`**: `nightly`. -- **`version`**: - - **`major`**: An integer indicating the major version number. - - **`minor`**: An integer indicating the minor version number. - - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). -- **`lifecycle`**: - - **`released`**: - - **`isodate`**: The release date in ISO format. - - **`timestamp`**: The UNIX timestamp of the release date. -- **`git`**: - - **`commit`**: The full git commit hash associated with the release. - - **`commit_short`**: The short git commit hash. -- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. -- **`attributes`**: An object that does contain additional metadata about the release. - - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). - -### Development Releases - -[Development releases](TODO: define and link) are used for testing and development purposes, representing the latest changes that may not yet be included in a major or minor release. These can be manually created by developers. - -#### Schema Fields - -- **`name`**: A string representing the release name (e.g., `dev-1312.0` for v1 versions, `dev-2017.0.0` for v2 versions). -- **`type`**: `dev`. -- **`version`**: - - **`major`**: An integer indicating the major version number. - - **`minor`**: An integer indicating the minor version number. - - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). -- **`lifecycle`**: - - **`released`**: - - **`isodate`**: The release date in ISO format. - - **`timestamp`**: The UNIX timestamp of the release date. -- **`git`**: - - **`commit`**: The full git commit hash associated with the release. - - **`commit_short`**: The short git commit hash. -- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. -- **`attributes`**: An object that does contain additional metadata about the release. - - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). - -### Next Release - -[Next release](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#next-release) is the projected next major releases. There can only be a single `next` release. - -#### Schema Fields - -- **`name`**: A string representing the release name (`next`). -- **`type`**: `next`. -- **`version`**: - - **`major`**: `next`. -- **`lifecycle`**: - - **`released`**: - - **`isodate`**: The release date in ISO format (`YYYY-MM-DD`). - - **`timestamp`**: The UNIX timestamp of the release date. - - **`extended`**: - - **`isodate`**: Optional extended maintenance date in ISO format. - - **`timestamp`**: Optional UNIX timestamp for the extended maintenance date. - - **`eol`**: - - **`isodate`**: End-of-life date in ISO format. - - **`timestamp`**: UNIX timestamp for the end-of-life date. - -### Lifecycle Dependencies - -The lifecycle fields in the release schemas help track the release dates, extended maintenance dates and end-of-life (EOL) dates for each release. - -#### Default Major dates - -The defaults for `extended` and `eol` dates are based on the [Garden Linux Release Plan Overview](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md) and defined to be: - -- `extended` - - `released` + 6 month -- `eol` - - `released` + 9 month - -For example: - -- **Major Release `major-1443`**: - - `released`: 2024-03-13 - - `extended`: 2024-09-13 - - `eol`: 2025-01-13 - -#### Major and Minor releases - -There is a dependency between the `lifecycle` fields of **major** and **minor** releases: - -- **EOL of Minor Releases**: The `eol` date of a minor release is set to the `released` date of the next minor release. If there is no subsequent minor release, the `eol` date is aligned with the `eol` date of the corresponding major release. -- **EOL of Latest Minor Release**: The latest minor release's `eol` date matches the `eol` date of the major release. -- **EOL of Major Releases**: The `eol` date for a major release marks the end of support for that major version. - -This ensures that all minor updates within a major release adhere to the same overall support timeline. - -For example: - -- **Major Release `major-1312`**: - - `released`: 2023-11-16 - - `extended`: 2024-05-03 - - `eol`: 2024-08-03 -- **Minor Release `minor-1312.1`**: - - `released`: 2023-11-23 - - `eol`: 2024-01-15 (next minor release date) -- **Minor Release `minor-1312.2`**: - - `released`: 2024-01-15 - - `eol`: 2024-02-14 (next minor release date) -- ... -- **Minor Release `minor-1312.7`**: - - `released`: 2024-07-03 - - `eol`: 2024-08-03 (inherits from major release eol) - -In this example, the `eol` of `minor-1312.1` is set to the `released` date of `minor-1312.2`, and the `eol` of the latest minor release (`minor-1312.7`) is set to the `eol` of the major release (`minor-1312`). - -Please note that the `extended` lifecycle field is not taken into account for minor releases. This is simply an administrative date that has no technical implications. - -#### Nightly an Dev dates - -Due to the nature of the `nightly` and `dev` releases, those do not have `extended` and `eol` dates. - -## Contributing - -Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. - -## License - -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. - -## Funding information - -

Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo

diff --git a/README.md b/README.md new file mode 120000 index 0000000..891080f --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +docs/overview/README.md \ No newline at end of file diff --git a/docs/explanation/.gitkeep b/docs/explanation/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/how-to/.gitkeep b/docs/how-to/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/overview/README.md b/docs/overview/README.md new file mode 100644 index 0000000..d717d71 --- /dev/null +++ b/docs/overview/README.md @@ -0,0 +1,869 @@ +--- +title: "Release Database" +description: "How to use the Garden Linux Release Database" +github_org: gardenlinux +github_repo: glrd +github_source_path: docs/overview/README.md +github_target_path: docs/reference/supporting_tools/glrd.md +--- + +# Garden Linux Release Database (GLRD) + +The [GLRD repository](https://github.com/gardenlinux/glrd) contains tooling and configuration to create the Garden Linux Release Database (GLRD), a system designed to manage and query release information for the Garden Linux distribution. + +This repository contains these tools: + +- **`glrd-manage`**: A tool for generating and populating the GLRD with initial release data and for creating individual release entries. +- **`glrd`**: A command-line client for querying the GLRD to retrieve release information based on various criteria. + +## Table of Contents + +- [Garden Linux Releases](#garden-linux-releases) +- [Overview of GLRD](#overview) +- [Prerequisites](#prerequisites) +- [Run GLRD](#run-glrd) +- [glrd](#glrd) +- [glrd-manage](#glrd-manage) +- [Release Schema](#release-schema) +- [Contributing](#contributing) +- [License](#license) + +## Garden Linux Releases + +For a general overview about Garden Linux releases and their lifecycle, have a look at the [Garden Linux Release Lifecycle](/reference/releases/release-lifecycle). + +## Overview + +The GLRD provides a structured way to store and access release data for Garden Linux, including different release types such as major, minor, nightly, and development releases. It uses JSON and YAML formats to store release information and supports integration with AWS S3 for storage to host release data.. + +![Overview](/overview/assets/glrd-overview.png) + +## Run GLRD + +### Manually run Python scripts + +
+ Details + +### Prerequisites + +- **Python 3.10+** + +You can install the required Python packages using: + +```bash +poetry install +``` + +- **AWS CLI** configured with appropriate permissions if you plan to use S3 integration. +- **Git** and **GitHub CLI (gh)** installed and configured if you plan to generate release data from GitHub. + +### Installation + +Clone the repository and ensure that the scripts are executable: + +```bash +git clone https://github.com/gardenlinux/glrd.git +cd glrd +poetry install +``` + +
+ +### Run in container + +
+ Details + +You can also use the GLRD tools by building or running a container image. + +#### Run pre-build image + +``` +podman run -it --rm ghcr.io/gardenlinux/glrd glrd +podman run -it --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN ghcr.io/gardenlinux/glrd glrd-manage + +``` + +#### Build and run image locally + +``` +podman build -t glrd . +podman run -it --rm glrd glrd +podman run -it --rm -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN glrd glrd-manage +``` + +
+ +### Run in GitHub action + +
+ Details + +``` + - name: Get latest GL minor version + id: gl_version_latest + uses: gardenlinux/glrd@main + with: + cmd: glrd --no-header --type minor --latest --fields Version + - name: Use latest GL minor version + run: echo ${{ steps.gl_version_latest.outputs.result }} + + - name: Get latest GL nightly version + id: gl_version_nightly + uses: gardenlinux/glrd@main + with: + cmd: glrd --no-header --type nightly --latest --fields Version + - name: Use latest GL nightly version + run: echo ${{ steps.gl_version_nightly.outputs.result }} +``` + +
+ +### Manually query JSON data + +
+ Details + +You can manually query the release JSON data by getting them from our production S3 bucket. + +Query the release type that you want: + +- `releases-major.json` +- `releases-minor.json` +- `releases-nightly.json` +- `releases-dev.json` + +To e.g. query the major releases: + +```bash +❯ curl -s https://gardenlinux-glrd.s3.eu-central-1.amazonaws.com/releases-major.json +{"releases":[{"name":"major-27","type":"major","version":{"major":27},"lifecycle":{"released":{"isodate":"2020-06-09","timestamp":1591694693},"extended":{"isodate":"2020-12-09","timestamp":1607472000},"eol":{"isodate":"2021-03-09","timestamp":1615248000}}},{"name":"major-184","type":"major","version":{"major":184},"lifecycle":{"released":{"isodate":"2020-10-29","timestamp":1603984625},"extended":{"isodate":"2020-04-29","timestamp":1588118400},"eol":{"isodate":"2021-07-29","timestamp":1627516800}}},{"name":"major-318","type":"major","version":{"major":318},"lifecycle":{"released":{"isodate":"2021-04-28","timestamp":1619614135},"extended":{"isodate":"2021-10-28","timestamp":1635379200},"eol":{"isodate":"2023-01-28","timestamp":1674864000}}},{"name":"major-576","type":"major","version":{"major":576},"lifecycle":{"released":{"isodate":"2021-11-17","timestamp":1637142852},"extended":{"isodate":"2023-05-17","timestamp":1684281600},"eol":{"isodate":"2023-08-17","timestamp":1692230400}}},{"name":"major-934","type":"major","version":{"major":934},"lifecycle":{"released":{"isodate":"2023-06-05","timestamp":1685968163},"extended":{"isodate":"2023-12-05","timestamp":1701734400},"eol":{"isodate":"2024-03-05","timestamp":1709596800}}},{"name":"major-1312","type":"major","version":{"major":1312},"lifecycle":{"released":{"isodate":"2023-11-16","timestamp":1700136050},"extended":{"isodate":"2024-05-03","timestamp":1714694400},"eol":{"isodate":"2024-08-03","timestamp":1722643200}}},{"name":"major-1443","type":"major","version":{"major":1443},"lifecycle":{"released":{"isodate":"2024-03-13","timestamp":1710341636},"extended":{"isodate":"2024-09-13","timestamp":1726185600},"eol":{"isodate":"2025-01-13","timestamp":1736726400}}},{"name":"major-1592","type":"major","version":{"major":1592},"lifecycle":{"released":{"isodate":"2024-08-12","timestamp":1723457202},"extended":{"isodate":"2025-05-12","timestamp":1747008000},"eol":{"isodate":"2025-08-12","timestamp":1754956800}}}]} +``` + +
+ +### AWS Authentication + +`glrd-manage` needs write access to an AWS S3 bucket to create and manage releases. See [Boto3 Credentials documentation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html) and ways to configure this. +If you are running `glrd-manage` in a container, you might want to use [Environment variables](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html#environment-variables) and pass those via e.g. `podman run ... -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN`. + +## glrd + +The `glrd` script is a command-line utility for querying the GLRD. It allows you to filter and display release information based on various criteria. + +### Usage + +#### Show help + +``` +❯ glrd --help +usage: glrd [-h] [--input-format {yaml,json}] [--input-file-prefix INPUT_FILE_PREFIX] [--input-type {file,url}] [--input-url INPUT_URL] [--no-input-split] [--output-format {json,yaml,markdown,mermaid_gantt,shell}] [--output-description OUTPUT_DESCRIPTION] [--active] [--archived] [--latest] [--type TYPE] [--version VERSION] [--fields FIELDS] [--no-header] [-V] + +Process and filter releases data from a file or URL. + +options: + -h, --help show this help message and exit + --input-format {yaml,json} + Input format: 'yaml' or 'json' (default: json). + --input-file-prefix INPUT_FILE_PREFIX + The prefix to get input files (default: releases). + --input-type {file,url} + Specify if the input type (default: url). + --input-url INPUT_URL + Input URL to the releases data. Defaults to gardenlinux-glrd S3 URL. + --no-input-split Do not split Input into major+minor and nightly. No additional input-files *-nightly and *-dev will be parsed. + --output-format {json,yaml,markdown,mermaid_gantt,shell} + Output format: json, yaml, markdown, mermaid_gantt, shell (default). + --output-description OUTPUT_DESCRIPTION + Description, added to certain outputs, e.g. mermaid (default: 'Garden Linux Releases'). + --active Show only active releases. + --archived Show only archived releases. + --latest Show the latest active major.minor release. + --type TYPE Filter by release types (comma-separated list, default: major,minor). E.g., --type major,minor,nightly,dev,next + --version VERSION Filter by a specific version (major, major.minor, or major.minor.patch). E.g., --version 1312, --version 1312.0, or --version 2017.0.0 + --fields FIELDS Comma-separated list of fields to output. Possible fields: Name,Version,Type,GitCommit,GitCommitShort,ReleaseDate,ReleaseTime,ExtendedMaintenance,EndOfMaintenance,Flavors,OCI,AttributesSourceRepo (default: Name,Version,Type,GitCommitShort,ReleaseDate,ExtendedMaintenance,EndOfMaintenance) + --no-header Omit the header in shell output. + -V show program's version number and exit +``` + +### Get latest Garden Linux Version + +#### Default shell output + +``` +# default shell output +❯ glrd --latest +Name Version Type GitCommitShort ReleaseDate ExtendedMaintenance EndOfMaintenance +minor-1592.6 1592.6 minor cb05e11f 2025-02-19 N/A 2025-08-12 +``` + +#### Get only version field + +``` +❯ glrd --latest --fields Version --no-header +1592.6 +``` + +#### Get JSON output + +
+ Details + +``` +❯ glrd --latest --output-format json +{ + "releases": [ + { + "name": "minor-1592.6", + "type": "minor", + "version": { + "major": 1592, + "minor": 6 + // Note: patch field is only present for versions ≥ 2017.0.0 + }, + "lifecycle": { + "released": { + "isodate": "2025-02-19", + "timestamp": 1739951325 + }, + "eol": { + "isodate": "2025-08-12", + "timestamp": 1754956800 + } + }, + "git": { + "commit": "cb05e11f0481b72d0a30da3662295315b220a436", + "commit_short": "cb05e11f" + }, + "github": { + "release": "https://github.com/gardenlinux/gardenlinux/releases/tag/1592.6" + }, + "flavors": { + "ali-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-amd64-1592.6-cb05e11f/ali-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-amd64-1592.6-cb05e11f/ali-gardener_prod-amd64-1592.6-cb05e11f.qcow2" + }, + "ali-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-arm64-1592.6-cb05e11f/ali-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/ali-gardener_prod-arm64-1592.6-cb05e11f/ali-gardener_prod-arm64-1592.6-cb05e11f.qcow2" + }, + "aws-gardener_persistence_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "aws-gardener_persistence_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-amd64-1592.6-cb05e11f/aws-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-amd64-1592.6-cb05e11f/aws-gardener_prod-amd64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-arm64-1592.6-cb05e11f/aws-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod-arm64-1592.6-cb05e11f/aws-gardener_prod-arm64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f/aws-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "aws-gardener_prod_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f/aws-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "azure-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-amd64-1592.6-cb05e11f/azure-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-amd64-1592.6-cb05e11f/azure-gardener_prod-amd64-1592.6-cb05e11f.vhd" + }, + "azure-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-arm64-1592.6-cb05e11f/azure-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/azure-gardener_prod-arm64-1592.6-cb05e11f/azure-gardener_prod-arm64-1592.6-cb05e11f.vhd" + }, + "gcp-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-amd64-1592.6-cb05e11f/gcp-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-amd64-1592.6-cb05e11f/gcp-gardener_prod-amd64-1592.6-cb05e11f.gcpimage.tar.gz" + }, + "gcp-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-arm64-1592.6-cb05e11f/gcp-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gcp-gardener_prod-arm64-1592.6-cb05e11f/gcp-gardener_prod-arm64-1592.6-cb05e11f.gcpimage.tar.gz" + }, + "gdch-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-amd64-1592.6-cb05e11f/gdch-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-amd64-1592.6-cb05e11f/gdch-gardener_prod-amd64-1592.6-cb05e11f.gcpimage.tar.gz" + }, + "gdch-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-arm64-1592.6-cb05e11f/gdch-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/gdch-gardener_prod-arm64-1592.6-cb05e11f/gdch-gardener_prod-arm64-1592.6-cb05e11f.gcpimage.tar.gz" + }, + "kvm-gardener_persistence_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_persistence_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-amd64-1592.6-cb05e11f/kvm-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-amd64-1592.6-cb05e11f/kvm-gardener_prod-amd64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-arm64-1592.6-cb05e11f/kvm-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod-arm64-1592.6-cb05e11f/kvm-gardener_prod-arm64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "kvm-gardener_prod_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f/kvm-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "metal-gardener_persistence_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "metal-gardener_persistence_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_persistence_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-amd64-1592.6-cb05e11f/metal-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-amd64-1592.6-cb05e11f/metal-gardener_prod-amd64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-arm64-1592.6-cb05e11f/metal-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod-arm64-1592.6-cb05e11f/metal-gardener_prod-arm64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_pxe-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f/metal-gardener_prod_pxe-amd64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_pxe-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f/metal-gardener_prod_pxe-arm64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_readonly_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_readonly_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_readonly_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_secureboot-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f/metal-gardener_prod_secureboot-amd64-1592.6-cb05e11f.raw" + }, + "metal-gardener_prod_secureboot-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f/metal-gardener_prod_secureboot-arm64-1592.6-cb05e11f.raw" + }, + "openstack-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-amd64-1592.6-cb05e11f/openstack-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-amd64-1592.6-cb05e11f/openstack-gardener_prod-amd64-1592.6-cb05e11f.qcow2" + }, + "openstack-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-arm64-1592.6-cb05e11f/openstack-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstack-gardener_prod-arm64-1592.6-cb05e11f/openstack-gardener_prod-arm64-1592.6-cb05e11f.qcow2" + }, + "openstackbaremetal-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-amd64-1592.6-cb05e11f.qcow2" + }, + "openstackbaremetal-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f/openstackbaremetal-gardener_prod-arm64-1592.6-cb05e11f.qcow2" + }, + "vmware-gardener_prod-amd64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-amd64-1592.6-cb05e11f/vmware-gardener_prod-amd64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-amd64-1592.6-cb05e11f/vmware-gardener_prod-amd64-1592.6-cb05e11f.ova" + }, + "vmware-gardener_prod-arm64": { + "metadata": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-arm64-1592.6-cb05e11f/vmware-gardener_prod-arm64-1592.6-cb05e11f.manifest", + "image": "https://gardenlinux-github-releases.s3.amazonaws.com/objects/vmware-gardener_prod-arm64-1592.6-cb05e11f/vmware-gardener_prod-arm64-1592.6-cb05e11f.ova" + } + }, + "oci": "ghcr.io/gardenlinux/gardenlinux:1592.6", + "attributes": { + "source_repo": true + } + } + ] +} +``` + +
+ +#### Get json output and filter for version + +``` +❯ glrd --latest --output-format json | jq -r '.releases[] | "\(.version.major).\(.version.minor)"' +1592.6 +``` + +**Note**: For versions ≥ 2017.0.0, you can also filter by patch version: `jq -r '.releases[] | "\(.version.major).\(.version.minor).\(.version.patch)"'` + +### Get all active and supported Garden Linux Versions + +``` +❯ glrd --active +Name Version Type Git Commit Release date Extended maintenance End of maintenance +major-1443 1443 major N/A 2024-03-13 2024-09-13 2025-01-13 +minor-1443.15 1443.15 minor 5d33a69 2024-10-10 N/A 2025-01-13 +major-1592 1592 major N/A 2024-08-12 2025-05-12 2025-08-12 +minor-1592.1 1592.1 minor ec945aa 2024-08-22 N/A 2025-08-12 +``` + +### Create [Mermaid Gantt Chart](https://mermaid.js.org/syntax/gantt.html) for active releases + +``` +❯ glrd --active --type next,major --output-format mermaid_gantt --output-description "Garden Linux active Releases" +gantt + title Garden Linux active Releases + axisFormat %m.%y + section 1443 + Release: milestone, 2024-03-13, 0m + Standard maintenance: task, 2024-03-13, 6M + Extended maintenance: milestone, 2024-09-13, 0m + Extended maintenance: task, 2024-09-13, 4M + End of maintenance: milestone, 2025-01-13, 0m + section 1592 + Release: milestone, 2024-08-12, 0m + Standard maintenance: task, 2024-08-12, 9M + Extended maintenance: milestone, 2025-05-12, 0m + Extended maintenance: task, 2025-05-12, 3M + End of maintenance: milestone, 2025-08-12, 0m + section next + Release: milestone, 2024-12-01, 0m + Standard maintenance: task, 2024-12-01, 6M + Extended maintenance: milestone, 2025-06-01, 0m + Extended maintenance: task, 2025-06-01, 3M + End of maintenance: milestone, 2025-09-01, 0m +``` + +## glrd-manage + +The `glrd-manage` script is used to generate release data for Garden Linux. It can create initial releases by fetching data from GitHub, generate individual release entries, and manage release data files. + +### Show help + +``` +❯ glrd-manage --help +usage: glrd-manage [-h] [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}] [--input-file INPUT_FILE] [--output-format {yaml,json}] [--output-file-prefix OUTPUT_FILE_PREFIX] [--s3-bucket-name S3_BUCKET_NAME] [--s3-bucket-region S3_BUCKET_REGION] [--s3-bucket-prefix S3_BUCKET_PREFIX] [--delete DELETE] [--create-initial-releases CREATE_INITIAL_RELEASES] [--create CREATE] + [--version VERSION] [--commit COMMIT] [--lifecycle-released-isodatetime LIFECYCLE_RELEASED_ISODATETIME] [--lifecycle-extended-isodatetime LIFECYCLE_EXTENDED_ISODATETIME] [--lifecycle-eol-isodatetime LIFECYCLE_EOL_ISODATETIME] [--no-query] [--input-stdin] [--input] [--no-output-split] [--s3-create-bucket] [--s3-update] [--output-all] [--input-all] [-V] + +Manage Garden Linux releases data. + +options: + -h, --help show this help message and exit + --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL} + Set the logging level + --input-file INPUT_FILE + The name of the input file (default: releases-input.yaml). + --output-format {yaml,json} + Output format: yaml or json (default: yaml). + --output-file-prefix OUTPUT_FILE_PREFIX + The prefix for output files (default: releases). + --s3-bucket-name S3_BUCKET_NAME + Name of S3 bucket. Defaults to 'gardenlinux-glrd'. + --s3-bucket-region S3_BUCKET_REGION + Region for S3 bucket. Defaults to 'eu-central-1'. + --s3-bucket-prefix S3_BUCKET_PREFIX + Prefix for S3 bucket objects. Defaults to empty string. + --delete DELETE Delete a release by name (format: type-major.minor). Requires --s3-update. + --create-initial-releases CREATE_INITIAL_RELEASES + Comma-separated list of initial releases to retrieve and generate: 'major,minor,nightly'. + --create CREATE Create a release for this type using the current timestamp and git information (choose one of: major,minor,nightly,dev,next)'. + --version VERSION Manually specify the version (format: major.minor for versions < 2017.0.0, major.minor.patch for versions ≥ 2017.0.0). + --commit COMMIT Manually specify the git commit hash (40 characters). + --lifecycle-released-isodatetime LIFECYCLE_RELEASED_ISODATETIME + Manually specify the release date and time in ISO format (YYYY-MM-DDTHH:MM:SS). + --lifecycle-extended-isodatetime LIFECYCLE_EXTENDED_ISODATETIME + Manually specify the extended maintenance date and time in ISO format (YYYY-MM-DDTHH:MM:SS). + --lifecycle-eol-isodatetime LIFECYCLE_EOL_ISODATETIME + Manually specify the EOL date and time in ISO format (YYYY-MM-DDTHH:MM:SS). + --no-query Do not query and use existing releases using glrd command. Be careful, this can delete your releases. + --input-stdin Process a single input from stdin (JSON data). + --input Process input from --input-file. + --no-output-split Do not split Output into major+minor and nightly. Additional output-files *-nightly and *-dev will not be created. + --s3-create-bucket Create an S3 bucket. + --s3-update Update (merge) the generated files with S3. + --output-all Download and write all release files found in S3 to local disk + --input-all Upload all local release files to S3 + -V show program's version number and exit +``` + +### Testing release creation + +Files named `releases-${type}.json` will be created in the current working directory. + +Without passing `--s3-update`, no actual update will be made and changes can safely be tested and verified locally. + +### Generate and populate initial release data + +This will generate the following initial release data ... + +- major releases +- minor releases +- nightly releases +- releases from `releases-input.yaml` (contain manual lifecycle fields) + +... and upload it to the default S3 bucket (if `--s3-update` is passed). + +``` +❯ glrd-manage --create-initial-releases major,minor,nightly --input +``` + +### Generate/Update an arbitrary release from JSON/YAML data + +This will generate/update a release from JSON data and upload it to the default S3 bucket. + +``` +❯ echo '{ + "releases": [ + { + "name": "minor-1592.1", + "type": "minor", + "version": { + "major": 1592, + "minor": 1 + }, + "lifecycle": { + "released": { + "isodate": "2024-08-22", + "timestamp": 1724277600 + }, + "eol": { + "isodate": "2025-08-12", + "timestamp": 1754949600 + } + }, + "git": { + "commit": "ec945aa995d0f08d64303ff6045b313b40b665fb", + "commit_short": "ec945aa" + }, + "github": { + "release": "https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1" + }, + "flavors": [ + "ali-gardener_prod", + "azure-gardener_prod", + "aws-gardener_prod", + "gcp-gardener_prod" + ], + "attributes": { + "source_repo": false + } + } + ] +}' | glrd-manage --input-stdin +``` + +Another approach is writing release YAML data to an input file and use this file as input parameter. + +``` +❯ cat releases-input.yaml +releases: + - name: minor-1592.1 + type: minor + version: + major: 1592 + minor: 1 + lifecycle: + released: + isodate: "2024-08-22" + timestamp: 1724277600 + eol: + isodate: "2025-08-27" + timestamp: 1754949600 + git: + commit: ec945aa995d0f08d64303ff6045b313b40b66fff + commit_short: ec945aa + github: + release: https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1 + flavors: + - ali-gardener_prod + - azure-gardener_prod + - aws-gardener_prod + - gcp-gardener_prod + attributes: + source_repo: false + +❯ glrd-manage --input --input-file releases-input.yaml +``` + +### Create or update a major release + +https://github.com/gardenlinux/glrd?tab=readme-ov-file#default-major-dates +When creating a new major release, [Default Major dates](#default-major-dates) can be automatically set for you. In addition to that, you can also overwrite the dates by hand. + +``` +# use default dates +❯ glrd-manage --create major --version 1312 + +# overwrite default dates +❯ glrd-manage --create major --version 1312 --date-time-released 2023-11-16T00:00:00 --date-time-extended 2024-05-03T00:00:00 --date-time-eol 2024-08-03T00:00:00 +``` + +### Create or update a minor release + +When creating a new minor release, the previous minor release of the same major release gets automatically updated. See [Lifecycle Dependencies](#major-and-minor-releases) for details. + +``` +# create new minor +❯ glrd-manage --create minor --version 1312.7 +``` + +### Create a new nightly release + +Without any additional parameters, the current timestamp and git information will be used to create releases. For minor, nightly and dev releases, the next free minor version is automatically chosen. + +``` +❯ glrd-manage --create nightly +``` + +### Update an existing release + +The `--update` action allows you to modify lifecycle fields and commit hashes on existing releases. You must specify the release by name (format: `type-major`, `type-major.minor`, or `type-major.minor.patch`) and provide at least one modifier flag. + +**Available modifiers:** + +- `--lifecycle-released-isodatetime`: Update the release date (valid for all types) +- `--lifecycle-extended-isodatetime`: Update the extended maintenance date (only for `major` and `next` types) +- `--lifecycle-eol-isodatetime`: Update the end-of-life date (only for `next`, `major`, and `minor` types) +- `--commit`: Update the git commit hash (only for `minor`, `nightly`, and `dev` types) + +**Examples:** + +```bash +# Update EOL date on a major release +❯ glrd-manage --update major-1592 --lifecycle-eol-isodatetime 2026-02-27T00:00:00 --input-stdin < releases.json + +# Update extended maintenance date on a major release +❯ glrd-manage --update major-1592 --lifecycle-extended-isodatetime 2025-06-15T00:00:00 --input-stdin < releases.json + +# Update commit hash on a minor release +❯ glrd-manage --update minor-1592.6 --commit deadbeef1234567890abcdef1234567890abcdef --input-stdin < releases.json + +# Update multiple fields at once +❯ glrd-manage --update major-1592 --lifecycle-eol-isodatetime 2026-02-27T00:00:00 --lifecycle-extended-isodatetime 2025-06-15T00:00:00 --input-stdin < releases.json +``` + +**Notes:** + +- The `--update` action requires existing release data to be provided via `--input-stdin` or loaded from the default query source +- The `--update` action cannot be used with `--no-query` +- Date/time values must be in ISO format: `YYYY-MM-DDTHH:MM:SS` +- Commit hashes must be exactly 40 characters (full SHA-1 hash) + +## Release Schema + +The Garden Linux Release Database (GLRD) uses structured JSON schemas to represent different types of releases: **major**, **minor**, **nightly**, and **development** releases. Each release type has specific fields that capture essential information about the release. + +### Versioning Scheme + +Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gardenlinux/issues/3069) in [TODO!!! name commit !!!]. GLRD supports both versioning schemes based on the major version number: + +- **v1: Versions < 2017.0.0**: Use the `major.minor` format (e.g., `27.0`, `1592.6`) +- **v2: Versions ≥ 2017.0.0**: Use the `major.minor.patch` format (e.g., `2017.0.0`, `2222.1.5`) + +### Major Releases + +[Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases) are major releases that are supported over an extended period of time. + +#### Schema Fields + +- **`name`**: A string representing the release name (e.g., `major-1312`). +- **`type`**: `major`. +- **`version`**: + - **`major`**: An integer indicating the major version number (e.g. `1312`). +- **`lifecycle`**: + - **`released`**: + - **`isodate`**: The release date in ISO format (`YYYY-MM-DD`). + - **`timestamp`**: The UNIX timestamp of the release date. + - **`extended`**: + - **`isodate`**: Optional extended maintenance date in ISO format. + - **`timestamp`**: Optional UNIX timestamp for the extended maintenance date. + - **`eol`**: + - **`isodate`**: End-of-life date in ISO format. + - **`timestamp`**: UNIX timestamp for the end-of-life date. + +### Minor Releases + +[Minor Releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#minores) are updates delivered during the standard and extended mainteance periods of [Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases). + +#### Schema Fields + +- **`name`**: A string representing the release name (e.g., `minor-1312.1` for v1 versions, `minor-2017.0.0` for v2 versions). +- **`type`**: `minor`. +- **`version`**: + - **`major`**: An integer indicating the major version number (e.g. `1312`). + - **`minor`**: An integer indicating the minor version number (e.g. `1`). + - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). +- **`lifecycle`**: + - **`released`**: + - **`isodate`**: The release date in ISO format. + - **`timestamp`**: The UNIX timestamp of the release date. + - **`eol`**: + - **`isodate`**: End-of-life date in ISO format. + - **`timestamp`**: UNIX timestamp for the end-of-life date. +- **`git`**: + - **`commit`**: The full git commit hash associated with the release. + - **`commit_short`**: The short git commit hash (first 7 characters). +- **`github`**: + - **`release`**: The URL to the GitHub release page. +- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. +- **`attributes`**: An object that does contain additional metadata about the release. + - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). + +### Nightly Releases + +[Nightly releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#nightly-releases) are automated builds that are generated every night, reflecting the latest state of the codebase. + +#### Schema Fields + +- **`name`**: A string representing the release name (e.g., `nightly-1312.0` for v1 versions, `nightly-2017.0.0` for v2 versions). +- **`type`**: `nightly`. +- **`version`**: + - **`major`**: An integer indicating the major version number. + - **`minor`**: An integer indicating the minor version number. + - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). +- **`lifecycle`**: + - **`released`**: + - **`isodate`**: The release date in ISO format. + - **`timestamp`**: The UNIX timestamp of the release date. +- **`git`**: + - **`commit`**: The full git commit hash associated with the release. + - **`commit_short`**: The short git commit hash. +- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. +- **`attributes`**: An object that does contain additional metadata about the release. + - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). + +### Development Releases + +[Development releases](TODO: define and link) are used for testing and development purposes, representing the latest changes that may not yet be included in a major or minor release. These can be manually created by developers. + +#### Schema Fields + +- **`name`**: A string representing the release name (e.g., `dev-1312.0` for v1 versions, `dev-2017.0.0` for v2 versions). +- **`type`**: `dev`. +- **`version`**: + - **`major`**: An integer indicating the major version number. + - **`minor`**: An integer indicating the minor version number. + - **`patch`**: An integer indicating the patch version number (only present for versions ≥ 2017.0.0, e.g. `0`). +- **`lifecycle`**: + - **`released`**: + - **`isodate`**: The release date in ISO format. + - **`timestamp`**: The UNIX timestamp of the release date. +- **`git`**: + - **`commit`**: The full git commit hash associated with the release. + - **`commit_short`**: The short git commit hash. +- **`flavors`**: A list of flavors that are included in this release. `glrd` creates `metadata`, `image` and/or `oci` links for each flavor. +- **`attributes`**: An object that does contain additional metadata about the release. + - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). + +### Next Release + +[Next release](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#next-release) is the projected next major releases. There can only be a single `next` release. + +#### Schema Fields + +- **`name`**: A string representing the release name (`next`). +- **`type`**: `next`. +- **`version`**: + - **`major`**: `next`. +- **`lifecycle`**: + - **`released`**: + - **`isodate`**: The release date in ISO format (`YYYY-MM-DD`). + - **`timestamp`**: The UNIX timestamp of the release date. + - **`extended`**: + - **`isodate`**: Optional extended maintenance date in ISO format. + - **`timestamp`**: Optional UNIX timestamp for the extended maintenance date. + - **`eol`**: + - **`isodate`**: End-of-life date in ISO format. + - **`timestamp`**: UNIX timestamp for the end-of-life date. + +### Lifecycle Dependencies + +The lifecycle fields in the release schemas help track the release dates, extended maintenance dates and end-of-life (EOL) dates for each release. + +#### Default Major dates + +The defaults for `extended` and `eol` dates are based on the [Garden Linux Release Plan Overview](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md) and defined to be: + +- `extended` + - `released` + 6 month +- `eol` + - `released` + 9 month + +For example: + +- **Major Release `major-1443`**: + - `released`: 2024-03-13 + - `extended`: 2024-09-13 + - `eol`: 2025-01-13 + +#### Major and Minor releases + +There is a dependency between the `lifecycle` fields of **major** and **minor** releases: + +- **EOL of Minor Releases**: The `eol` date of a minor release is set to the `released` date of the next minor release. If there is no subsequent minor release, the `eol` date is aligned with the `eol` date of the corresponding major release. +- **EOL of Latest Minor Release**: The latest minor release's `eol` date matches the `eol` date of the major release. +- **EOL of Major Releases**: The `eol` date for a major release marks the end of support for that major version. + +This ensures that all minor updates within a major release adhere to the same overall support timeline. + +For example: + +- **Major Release `major-1312`**: + - `released`: 2023-11-16 + - `extended`: 2024-05-03 + - `eol`: 2024-08-03 +- **Minor Release `minor-1312.1`**: + - `released`: 2023-11-23 + - `eol`: 2024-01-15 (next minor release date) +- **Minor Release `minor-1312.2`**: + - `released`: 2024-01-15 + - `eol`: 2024-02-14 (next minor release date) +- ... +- **Minor Release `minor-1312.7`**: + - `released`: 2024-07-03 + - `eol`: 2024-08-03 (inherits from major release eol) + +In this example, the `eol` of `minor-1312.1` is set to the `released` date of `minor-1312.2`, and the `eol` of the latest minor release (`minor-1312.7`) is set to the `eol` of the major release (`minor-1312`). + +Please note that the `extended` lifecycle field is not taken into account for minor releases. This is simply an administrative date that has no technical implications. + +#### Nightly an Dev dates + +Due to the nature of the `nightly` and `dev` releases, those do not have `extended` and `eol` dates. + +## Contributing + +Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. + +## License + +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. + +## Funding information + +

Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo

diff --git a/assets/overview.excalidraw b/docs/overview/assets/glrd-overview.excalidraw similarity index 100% rename from assets/overview.excalidraw rename to docs/overview/assets/glrd-overview.excalidraw diff --git a/assets/overview.png b/docs/overview/assets/glrd-overview.png similarity index 100% rename from assets/overview.png rename to docs/overview/assets/glrd-overview.png From d798e9c918516e83dcaa5e1b9f3b3c097583c9ee Mon Sep 17 00:00:00 2001 From: Tiara Lena Hock Date: Wed, 20 May 2026 14:50:12 +0200 Subject: [PATCH 2/6] Docs: Rework Readme Signed-off-by: Tiara Lena Hock --- README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) mode change 120000 => 100644 README.md diff --git a/README.md b/README.md deleted file mode 120000 index 891080f..0000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -docs/overview/README.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..a762720 --- /dev/null +++ b/README.md @@ -0,0 +1,50 @@ +# Garden Linux Release Database (GLRD) + +This repository contains tooling and configurations to create the Garden Linux +Release Database (GLRD), a system designed to manage and query release +information for the Garden Linux distribution. + +## Documentation + +To find out how GLRD works, our +[documentation hub](https://gardenlinux-docs.netlify.app/) contains a +[detailed reference document](https://gardenlinux-docs.netlify.app/reference/supporting_tools/glrd.html). + +In addition refer to our +[release lifecycle document](https://gardenlinux-docs.netlify.app/reference/releases/release-lifecycle.html) +to learn how our releases work. + +## Community + +To stay up-to-date with recent news about Gardenlinux, subscribe to our mailing +list: + +https://lists.neonephos.org/g/gardenlinux-discussion + +For updates and statements regarding security issues, we have a security mailing +list for you: + +https://lists.neonephos.org/g/gardenlinux-security + +For embargoed security related topics, this list is for you: + +https://lists.neonephos.org/g/gardenlinux-security-embargo + +## Contributing + +We welcome your contributions to Gardenlinux or any supporting projects. + +To find our more, visit our +[Contributor Documentation](https://gardenlinux-docs.netlify.app/contributing). + +## Licensing + +Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors. +Please see our [LICENSE](LICENSE.md) for copyright and license information. +Detailed information including third-party components and their +licensing/copyright information is available +[via the REUSE tool](https://reuse.software). + +

+ Bundesministerium für Wirtschaft und Energie (BMWE)-EU funding logo +

From 403361e0462e95666fd5528efd1217a7f64b3569 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 1 Jul 2026 17:13:19 +0200 Subject: [PATCH 3/6] feat: ci: add docs-check workflow Signed-off-by: Eike Waldt On-behalf-of: SAP --- .github/workflows/docs-check.yml | 74 ++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 .github/workflows/docs-check.yml diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 0000000..3ec4da5 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,74 @@ +name: Documentation Quality Check + +on: + pull_request: + branches: [main, docs-ng] + types: [opened, synchronize, reopened, closed] + paths: + - 'docs/**' + push: + branches: [main, docs-ng] + paths: + - 'docs/**' + +jobs: + docs-checks: + # Skip checks on closed PRs (only need the notification) + if: github.event_name != 'pull_request' || github.event.action != 'closed' + uses: gardenlinux/docs-ng/.github/workflows/docs-checks.yml@main + with: + override-repo: ${{ github.event.repository.name }} + override-ref: ${{ github.head_ref || github.ref_name }} + override-commit: ${{ github.event.pull_request.head.sha || github.sha }} + + notify-docs-ng: + name: Notify docs-ng + needs: [docs-checks] + runs-on: ubuntu-24.04 + # Only notify for PR events (not push events which lack PR context) + # Run after checks pass for open PRs, OR immediately for merged PRs + if: | + always() && + github.event_name == 'pull_request' && + ( + (github.event.action == 'closed' && github.event.pull_request.merged == true) || + (github.event.action != 'closed' && needs.docs-checks.result == 'success') + ) + steps: + - name: Generate GitHub App token + id: app-token + uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0 + with: + app-id: ${{ secrets.DOCS_BOT_APP_ID }} + private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }} + repositories: docs-ng + + - name: Send repository dispatch to docs-ng + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ steps.app-token.outputs.token }} + script: | + const isMergedPR = context.payload.action === 'closed' && + context.payload.pull_request.merged === true; + + // For merged PRs, use the base branch (the branch it was merged into) + // For open PRs, use the head branch (feature branch) + const ref = isMergedPR + ? context.payload.pull_request.base.ref + : context.payload.pull_request.head.ref; + + await github.rest.repos.createDispatchEvent({ + owner: 'gardenlinux', + repo: 'docs-ng', + event_type: 'docs-pr', + client_payload: { + repo: '${{ github.event.repository.name }}', + pr_number: `${context.payload.pull_request.number}`, + commit_sha: isMergedPR + ? context.payload.pull_request.merge_commit_sha + : context.payload.pull_request.head.sha, + ref: ref, + event: isMergedPR ? 'merged' : 'pr_success' + } + }); + core.info('Repository dispatch sent to docs-ng'); From c51d0a8f902322848aa17bdee8ddd3a86bf86bf3 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 2 Jul 2026 17:01:03 +0200 Subject: [PATCH 4/6] fix: rename assets Signed-off-by: Eike Waldt On-behalf-of: SAP --- docs/overview/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview/README.md b/docs/overview/README.md index d717d71..df6acd5 100644 --- a/docs/overview/README.md +++ b/docs/overview/README.md @@ -36,7 +36,7 @@ For a general overview about Garden Linux releases and their lifecycle, have a l The GLRD provides a structured way to store and access release data for Garden Linux, including different release types such as major, minor, nightly, and development releases. It uses JSON and YAML formats to store release information and supports integration with AWS S3 for storage to host release data.. -![Overview](/overview/assets/glrd-overview.png) +![Overview](assets/glrd-overview.png) ## Run GLRD From 3f9fe055cc646d9e1f13bc9d2ebc26b6da1b1658 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Wed, 8 Jul 2026 13:44:32 +0200 Subject: [PATCH 5/6] docs: remove AI-generated phrasing Rules: CANONICAL-LINT (3 occurrences) Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 --- .coverage | Bin 0 -> 53248 bytes README.md | 2 +- docs/overview/README.md | 4 ++-- 3 files changed, 3 insertions(+), 3 deletions(-) create mode 100644 .coverage diff --git a/.coverage b/.coverage new file mode 100644 index 0000000000000000000000000000000000000000..94f7fdc143231a94550cc5ac152d8723dd47208d GIT binary patch literal 53248 zcmeI4O>7&-6~|{k$R#O~tJ-i`K{2!_n#!v6Va7n)GpjVtU%Bb-H z?WJw`ow6fr`dp=;f1BmgKW6%O3(x9P`Bw^G9C|n3%KmWZXPTLdf_++|u`X3tb zhEDWdd1jsz)g8AXtgpGIU0>whq+#|vtUF}qiXVFGI;|PsF`AYgxM_QqZ#lNXS9rbS z^Tur*oD|UFMDVtIL%L22hfar*(Y3bG=?mXRGO8X4&y#Vs6JzZQic6DlV6)w6)d=|u zomN{k4oQR;_MM$1cars;$k|WaHn(ZZzP|&_86y`h8cKC+YpKI~jX!DhB_{(nY-iFC zPEZ6qI+QLwzFT4xm3+lpYSR0ys@d_K;J8YSUoF!n|NYNow9?p^bYUq76oIE&vwW|Y z$qocf@AM9#Bg%J<8_`P!gGBVAX47!ygDxYajj(Yjnz#3vnHYxYijHPDQAM)!Q;jxZ zEZJbxnoeyn)`E!fICT&j3*u_?9lI{NiYI)iJ7>6SF7WB7G#nN_?LeZ?DQDBAV`Dpo zPA>$i=9yI60g*N6XHz23*0mjd~);KroU+1YP&d1 zhL5Mxr6>06WVkS)S{B>%`R~Yq$rnZf`Yjst#Y-75S)A#ce4MXNoiUpU44cqD-r0 z+Kp(w64P*~mBxP2ImLCtL4*X2aq5&Fb8>&oQ;l}KKHE_H$;`dm>{s0P0y&ioC;|!ofuc{6b7QTs%5bitK^J$E7u*9w9@|l zQnwRz#&DdedNirG%-HPcP#y@9n+p5!@+=Lw^loQ+oCtQ?aEQb33Sw{zTd)>Vh-*df zb#fD8fiLMFGx|pY0T2KI5C8!X009sH0T2KI5C8!Xc=!k?k}PRr{V(h9GyU(hK>`5~ z009sH0T2KI5C8!X009sH0T6f~3FKvEuO9!xkXY5o7E z{yqIrajW>N;@RR?3;!v+UT7A+Lfzd*=DMlQRpZOIdo7LT6=Wq3JflO{YzFrE|KoyfTzfL(6IK zrbil{%8`bl1U7^>b63wiCX{6FQb}3(l1b=GXbEXJs*#350$=D!1r`yd`}#@C6KRF5 zB~aoWB;nZzLU$A_VuE+`7fS#Zro>kIb zJtC2YYytzSRm-;gYL#?|@Bj1p51IaJ{jmO0VSn+>;(B4T@J6AP|FHPq;^PlkH;1_( z00JNY0w4eaAOHd&00JPu*qqu;C0gsn>;HUG4ZZdM&{4HJl*ESZ>;K%{DiQ1dY*Jr( z>;KF#wOdHy%fR|yJEW{7Q4*~G(-pO=B$1BS|EXEEDpwZKTpW3XeRl5>$sEeazx=az?X3*ky84gby|nh5f4z6*x0gS2R zO~p^A<@Mu?rF$1s4aPKaq|z&sYN^?5Q7U;<^?)Y7_sGTzZy!!cKPnGNpDVJi#+{Uu z?S3oh8A3 zs%(hb5}h!DEmJGqvO?E6SCg-w?P~00Dw4z%?vMhF@~hf#rgCxl$#=fa*wxC|mE)ll z87OT0)9HU+)pmtS)X=KnKprOBDH&q3Q!+M!l8SKg*0d2=E;t^v3EiS1uRkgg2BI>? zF8+LLGrKNd+uZ%?H(0wT+;?a=r~jK}=raKQlKwaSn*Of-7yYvSd;O2Sy2yY42!H?x zfB*=900@8p2!H?xfB*>G7X(uD$%)iT)9PQ+ykMug!7j5D?9%OEmvVxgtdP+u7UUIM z-2cDrBa{2W9~c1wAOHd&00JNY0w4eaAOHd&00JOzZwZL||FQnRw@jf81V8`;KmY_l x00ck)1V8`;KmY{pHv;(n|9)!`*aHF}00JNY0w4eaAOHd&00JNY0{5Q4{{WMA%xVAt literal 0 HcmV?d00001 diff --git a/README.md b/README.md index a762720..b02a5de 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ To find our more, visit our ## Licensing Copyright 2025 SAP SE or an SAP affiliate company and GardenLinux contributors. -Please see our [LICENSE](LICENSE.md) for copyright and license information. +See our [LICENSE](LICENSE.md) for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available [via the REUSE tool](https://reuse.software). diff --git a/docs/overview/README.md b/docs/overview/README.md index df6acd5..a9d7409 100644 --- a/docs/overview/README.md +++ b/docs/overview/README.md @@ -850,7 +850,7 @@ For example: In this example, the `eol` of `minor-1312.1` is set to the `released` date of `minor-1312.2`, and the `eol` of the latest minor release (`minor-1312.7`) is set to the `eol` of the major release (`minor-1312`). -Please note that the `extended` lifecycle field is not taken into account for minor releases. This is simply an administrative date that has no technical implications. +Note that the `extended` lifecycle field is not taken into account for minor releases. This is simply an administrative date that has no technical implications. #### Nightly an Dev dates @@ -858,7 +858,7 @@ Due to the nature of the `nightly` and `dev` releases, those do not have `extend ## Contributing -Contributions are welcome! Please open an issue or submit a pull request for any improvements or bug fixes. +Contributions are welcome! Open an issue or submit a pull request for any improvements or bug fixes. ## License From bd1991762ed4d977270a632d64ab71464a5fe842 Mon Sep 17 00:00:00 2001 From: Eike Waldt Date: Thu, 9 Jul 2026 13:58:45 +0200 Subject: [PATCH 6/6] docs(docs/overview/README.md): remove AI-generated phrasing Rules: TITLE-CASE (18 occurrences) Signed-off-by: Eike Waldt On-behalf-of: SAP Assisted-by: Kilo:claude-opus-4-7 Assisted-by: Kilo:claude-sonnet-4-6 --- docs/overview/README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/overview/README.md b/docs/overview/README.md index a9d7409..348c42c 100644 --- a/docs/overview/README.md +++ b/docs/overview/README.md @@ -187,7 +187,7 @@ options: -V show program's version number and exit ``` -### Get latest Garden Linux Version +### Get latest Garden Linux version #### Default shell output @@ -421,7 +421,7 @@ minor-1592.6 1592.6 minor cb05e11f 2025-02-19 N/A **Note**: For versions ≥ 2017.0.0, you can also filter by patch version: `jq -r '.releases[] | "\(.version.major).\(.version.minor).\(.version.patch)"'` -### Get all active and supported Garden Linux Versions +### Get all active and supported Garden Linux versions ``` ❯ glrd --active @@ -674,22 +674,22 @@ The `--update` action allows you to modify lifecycle fields and commit hashes on - Date/time values must be in ISO format: `YYYY-MM-DDTHH:MM:SS` - Commit hashes must be exactly 40 characters (full SHA-1 hash) -## Release Schema +## Release schema The Garden Linux Release Database (GLRD) uses structured JSON schemas to represent different types of releases: **major**, **minor**, **nightly**, and **development** releases. Each release type has specific fields that capture essential information about the release. -### Versioning Scheme +### Versioning scheme Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gardenlinux/issues/3069) in [TODO!!! name commit !!!]. GLRD supports both versioning schemes based on the major version number: - **v1: Versions < 2017.0.0**: Use the `major.minor` format (e.g., `27.0`, `1592.6`) - **v2: Versions ≥ 2017.0.0**: Use the `major.minor.patch` format (e.g., `2017.0.0`, `2222.1.5`) -### Major Releases +### Major releases [Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases) are major releases that are supported over an extended period of time. -#### Schema Fields +#### Schema fields - **`name`**: A string representing the release name (e.g., `major-1312`). - **`type`**: `major`. @@ -706,11 +706,11 @@ Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gard - **`isodate`**: End-of-life date in ISO format. - **`timestamp`**: UNIX timestamp for the end-of-life date. -### Minor Releases +### Minor releases [Minor Releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#minores) are updates delivered during the standard and extended mainteance periods of [Major releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#major-releases). -#### Schema Fields +#### Schema fields - **`name`**: A string representing the release name (e.g., `minor-1312.1` for v1 versions, `minor-2017.0.0` for v2 versions). - **`type`**: `minor`. @@ -734,11 +734,11 @@ Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gard - **`attributes`**: An object that does contain additional metadata about the release. - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). -### Nightly Releases +### Nightly releases [Nightly releases](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#nightly-releases) are automated builds that are generated every night, reflecting the latest state of the codebase. -#### Schema Fields +#### Schema fields - **`name`**: A string representing the release name (e.g., `nightly-1312.0` for v1 versions, `nightly-2017.0.0` for v2 versions). - **`type`**: `nightly`. @@ -757,11 +757,11 @@ Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gard - **`attributes`**: An object that does contain additional metadata about the release. - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). -### Development Releases +### Development releases [Development releases](TODO: define and link) are used for testing and development purposes, representing the latest changes that may not yet be included in a major or minor release. These can be manually created by developers. -#### Schema Fields +#### Schema fields - **`name`**: A string representing the release name (e.g., `dev-1312.0` for v1 versions, `dev-2017.0.0` for v2 versions). - **`type`**: `dev`. @@ -780,11 +780,11 @@ Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gard - **`attributes`**: An object that does contain additional metadata about the release. - **`source_repo`**: A boolean indicating whether the release has debian source repoitories (default: true). -### Next Release +### Next release [Next release](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md#next-release) is the projected next major releases. There can only be a single `next` release. -#### Schema Fields +#### Schema fields - **`name`**: A string representing the release name (`next`). - **`type`**: `next`. @@ -801,11 +801,11 @@ Gardenlinux [introduced semantic Versioning](https://github.com/gardenlinux/gard - **`isodate`**: End-of-life date in ISO format. - **`timestamp`**: UNIX timestamp for the end-of-life date. -### Lifecycle Dependencies +### Lifecycle dependencies The lifecycle fields in the release schemas help track the release dates, extended maintenance dates and end-of-life (EOL) dates for each release. -#### Default Major dates +#### Default major dates The defaults for `extended` and `eol` dates are based on the [Garden Linux Release Plan Overview](https://github.com/gardenlinux/gardenlinux/blob/main/docs/00_introduction/release.md) and defined to be: @@ -821,7 +821,7 @@ For example: - `extended`: 2024-09-13 - `eol`: 2025-01-13 -#### Major and Minor releases +#### Major and minor releases There is a dependency between the `lifecycle` fields of **major** and **minor** releases: @@ -852,7 +852,7 @@ In this example, the `eol` of `minor-1312.1` is set to the `released` date of `m Note that the `extended` lifecycle field is not taken into account for minor releases. This is simply an administrative date that has no technical implications. -#### Nightly an Dev dates +#### Nightly and dev dates Due to the nature of the `nightly` and `dev` releases, those do not have `extended` and `eol` dates.