diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bea3741..706655f 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,6 +1,8 @@ name: Build Kernel on: push: + paths-ignore: + - 'docs/**' workflow_dispatch: schedule: - cron: '0 0 * * *' diff --git a/README.md b/README.md deleted file mode 100644 index f898513..0000000 --- a/README.md +++ /dev/null @@ -1,76 +0,0 @@ -# Kernel builds for Garden Linux - -This repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. -The build is based on [the debian kernel build](https://salsa.debian.org/kernel-team/linux). - -Garden Linux includes the latest LTS version of the kernel. - -## Components of this repository - -`./config` contains Garden Linux specific build configuration for the kernel. - -`./fixes-debian` contains patches for the debian build if needed. -We apply all patches from debian by default. -In some cases, we need to make changes to those to get a working build. - -`./upstream-patches` contains kernel patches that are not included in debian's kernel, but are part of the Garden Linux kernel. - -`./prepare_source` contains a shell script that merges debian's kernel build repository with the upstream kernel sources. - -`./update-kernel.py` contains a script which helps keeping up with patch releases of the LTS kernel version. - -`.github/workflows/pr-if-new-kernel.yml` contains the workflow to create new PRs based on `./update-kernel.py` if new patch versions of the LTS kernel are available. - -`.github/workflows/build.yml` contains the workflow to build and release the kernel binaries. - -## Backports - -| branch | description | -| ------------- | -------------- | -| `main` | latest lts kernel we maintain (6.18) | -| `maint-6.12` | maintenance of source code for kernel 6.12 | -| `maint-6.6` | maintenance of source code for kernel 6.6 | -| `rel-1877` | backport for 1877, merge code from `maint-6.12` | -| `rel-1592` | backport for 1592, merge code from `maint-6.6` | - - -The main branch of this repository always contains the latest kernel available in Garden Linux, and in the nightly builds. -Typically, this will be the most recent long term support (LTS) line from kernel.org, but from time to time it might also be a 'stable' kernel that will become the next LTS. - -We maintain also older supported kernel versions, if they are required by supported Garden Linux versions. - -Any kernel version that we need to maintain other than the latest LTS in main, are maintained in `maint-` branches (e.g. `maint-6.6`). -Backport releases need to branch off from the respective `maint-` branch and include the corresponding `.container` file for target backport. - -Branches containing the `.container` file must be named according to the `rel-MAJOR` naming scheme (e.g. `rel-1443`). - -## How to do a backport from maint-X.Y branch - -``` -git checkout rel-MAJOR -git merge --squash origin/maint-x.y -# resolve merge conflicts -git commit -git push -# Pipeline builds new rel-MAJOR version -``` - -> [!Tip] -> You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) - -> [!Note] -> We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) - -## Automated kernel patch level upgrades - -A scheduled workflow scans a list of configured branches [see](https://github.com/gardenlinux/package-linux/blob/main/.github/workflows/pr-if-new-kernel.yml#L12), and bumps the patch level of the version defined in the prepare_source file. -The automation creates a PR if a new patch level is available. - -> [!Important] -> Note that build failures in this PR will not be visible in the way you are used to it. -> This is due to limitations on GitHub. -> Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. -> [See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). - -> [!Note] -> This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool diff --git a/README.md b/README.md new file mode 120000 index 0000000..ae68a5d --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +docs/how-to/kernel-builds.md \ No newline at end of file diff --git a/docs/explanation/kernel.md b/docs/explanation/kernel.md new file mode 100644 index 0000000..df69f11 --- /dev/null +++ b/docs/explanation/kernel.md @@ -0,0 +1,71 @@ +--- +title: "Kernel" +description: Why we build the Garden Linux Kernel the way we build it +order: 119 +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" +migration_source: "00_introduction/kernel.md" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmang0ld, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/explanation/kernel.md +github_target_path: docs/explanation/kernel.md +--- + +# Kernel Philosophy + +Garden Linux aims towards a complete open, reproducible and easy-to-understand solution. That also includes all activities around the Kernel. +[Kernel.org](https://kernel.org) is the source of the official Linux kernels and therefore all kernels in Garden Linux are mainly based on this. Not to forget our Debian roots: we integrate with the build environment [Debian kernels](https://wiki.debian.org/Kernel) to support the Debian featureset to be compatible. Garden Linux tries to keep the amount of patches in the kernel diverging from Debian and kernel.org low, so everybody can easily support the Garden Linux kernel and no deep knowledge of Garden Linux internals is needed. + +## Kernel Versioning Strategy + +In contrast to Debian, Garden Linux integrates always with the latest Long Term Support kernel (LTS) and maintains this kernel at least for one overlapping period till the next kernel will be available. You can find the release categories and the time schedule for LTS releases also on [kernel.org](https://www.kernel.org/category/releases.html). +Garden Linux aims to integrate the latest long term release. + +### Why does Garden Linux not integrate the mainline stable? + +Mainline stable introduces features to the new Linux kernel, which happens every ~2 months. Some of those features affect the way e.g. container or network environment interact with the kernel and need some time to be adopted in surrounding tooling. Also some other feature introduce bugs, recognized after release and need to be reverted or other changes. In short: to avoid this we wait until a kernel version becomes a longterm stable and try to integrate always the latest long term stable and the one before to have a decent deprecation phase. +**Garden Linux takes advantage of these patches.** + +### A new long term kernel is released, when will it be integrated? + +We are probably on it, but feel free to open a Github issue. + +## Relationship to Debian + +Garden Linux 💚 Debian. + +Debian is free and open source software. There are good [reasons](https://www.debian.org/intro/why_debian) +to use Debian. In the following we explain our reasons in the kernel context. + +First, Debian provides an enterprise grade server operating system, +while protecting the claim to stay 100% free and open source. +Debian is rigorous when it comes to non-free software licenses, +also when it comes to the Linux Kernel. A prominent example of +what this means, is the extraction of non-free firmware from +the Linux Kernel. + +Debian scans licenses and patches out everything +that violates the claim to stay 100% free. Since Garden Linux shares this +approach, we benefit from Debian patches. + +Additionally, Debian provides a good kernel configuration, +which is used by Garden Linux as a base for configuration. +We extend this kernel configuration to our specific requirements during the +kernel integration process. + +Furthermore, Debian kernel [patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) are applied in most cases. + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics + + diff --git a/docs/how-to/kernel-builds.md b/docs/how-to/kernel-builds.md new file mode 100644 index 0000000..7344471 --- /dev/null +++ b/docs/how-to/kernel-builds.md @@ -0,0 +1,123 @@ +--- +title: "Kernel Builds" +description: "How to build a Garden Linux Kernel" +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/how-to/kernel-builds.md +github_target_path: docs/how-to/kernel-builds.md +--- + +# Kernel Builds + +The [package-linux](https://github.com/gardenlinux/package-linux) repository contains the code for building the [kernel](https://www.kernel.org) in Garden Linux. +The build is based on [the debian kernel build](https://salsa.debian.org/kernel-team/linux). + +Garden Linux includes the latest LTS version of the kernel. + +## Components + +`./config` contains Garden Linux specific build configuration for the kernel. + +`./fixes-debian` contains patches for the debian build if needed. +We apply all patches from debian by default. +In some cases, we need to make changes to those to get a working build. + +`./upstream-patches` contains kernel patches that are not included in debian's kernel, but are part of the Garden Linux kernel. + +`./prepare_source` contains a shell script that merges debian's kernel build repository with the upstream kernel sources. + +`./update-kernel.py` contains a script which helps keeping up with patch releases of the LTS kernel version. + +`.github/workflows/pr-if-new-kernel.yml` contains the workflow to create new PRs based on `./update-kernel.py` if new patch versions of the LTS kernel are available. + +`.github/workflows/build.yml` contains the workflow to build and release the kernel binaries. + +## Branch Structure + +| branch | description | +| ------------ | ----------------------------------------------- | +| `main` | latest lts kernel we maintain (6.18) | +| `maint-6.12` | maintenance of source code for kernel 6.12 | +| `maint-6.6` | maintenance of source code for kernel 6.6 | +| `rel-1877` | backport for 1877, merge code from `maint-6.12` | +| `rel-1592` | backport for 1592, merge code from `maint-6.6` | + +The main branch of this repository always contains the latest kernel available in Garden Linux, and in the nightly builds. +Typically, this will be the most recent long term support (LTS) line from kernel.org, but from time to time it might also be a 'stable' kernel that will become the next LTS. + +We maintain also older supported kernel versions, if they are required by supported Garden Linux versions. + +Any kernel version that we need to maintain other than the latest LTS in main, are maintained in `maint-` branches (e.g. `maint-6.6`). +Backport releases need to branch off from the respective `maint-` branch and include the corresponding `.container` file for target backport. + +Branches containing the `.container` file must be named according to the `rel-MAJOR` naming scheme (e.g. `rel-1443`). + +## How to Create Kernel Backports from `maint-X.Y` branch + +1. Checkout the appropriate release branch: + +```bash +git checkout rel-MAJOR +``` + +2. Merge changes from the maintenance branch (replace x.y with the appropriate version): + +```bash +git merge --squash origin/maint-x.y +# resolve merge conflicts +``` + +3. Commit the changes: + +```bash +git commit +``` + +4. Push the changes: + +```bash +git push origin rel-MAJOR +``` + +5. The Github Workflow will now build the new rel-MAJOR version. + +:::tip +You can find out the correct `.container` file by copying it from the corresponding tag of the https://github.com/gardenlinux/repo branch, for example [1877.0](https://github.com/gardenlinux/repo/blob/1877.0/.container) +::: + +:::info +We must create `rel-*` branches to include the respective `.container` file, and not use `maint-*` for backports. This is required because multiple releases can use the same kernel version (e.g. `rel-1443` and `rel-1592` both use `maint-6.6`) +::: + +## Automated kernel patch level upgrades + +A scheduled workflow scans a list of configured branches [see](https://github.com/gardenlinux/package-linux/blob/main/.github/workflows/pr-if-new-kernel.yml#L12), and bumps the patch level of the version defined in the prepare_source file. +The automation creates a PR if a new patch level is available. + +:::warning +Note that build failures in this PR will not be visible in the way you are used to it. +This is due to limitations on GitHub. +Always check the PR-related workflow manually before merge as it might well be that an upgrade of the kernel breaks the build. +[See this issue for more information if you are interested](https://github.com/gardenlinux/package-linux/issues/47). +::: + +:::info +This is done via the [update-kernel.py](https://github.com/gardenlinux/package-linux/blob/main/update-kernel.py) tool +::: + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics + + diff --git a/docs/reference/kernel-flavors.md b/docs/reference/kernel-flavors.md new file mode 100644 index 0000000..2eddeb4 --- /dev/null +++ b/docs/reference/kernel-flavors.md @@ -0,0 +1,41 @@ +--- +title: "Kernel Flavors" +description: Available kernel variants for different architectures and use cases +related_topics: + - /explanation/kernel.md + - /how-to/kernel-builds.md + - /reference/kernel-flavors.md +migration_status: "done" +migration_issue: "https://github.com/gardenlinux/gardenlinux/issues/4629" +migration_stakeholder: "@tmangold, @yeoldegrove, @ByteOtter" +migration_approved: false +github_org: gardenlinux +github_repo: package-linux +github_source_path: docs/reference/kernel-flavors.md +github_target_path: docs/reference/kernel-flavors.md +--- + +# Kernel Flavors + +Garden Linux provides multiple kernel variants optimized for different architectures and deployment scenarios. + +## Available Flavors + +| Flavour | Architecture | Description | +| ----------- | ------------ | -------------------------------------------------------------- | +| amd64 | x86_64 | 64-bit PCs; includes Intel SGX, TDX, Mellanox SmartNIC support | +| cloud-amd64 | x86_64 | Cloud VMs (AWS, Azure, GCP) - stripped-down with cloud drivers | +| arm64 | aarch64 | 64-bit ARMv8 machines | +| cloud-arm64 | aarch64 | Cloud VMs (AWS, Azure, GCP) - stripped-down with cloud drivers | + +Cloud flavors disable graphics, USB, wireless, Bluetooth, and audio drivers +and enable Hyper-V, virtio, Xen, ENA (AWS), GVE (GCE), and MANA (Azure). + +## Further reading + +- [kernel.org LTS releases](https://www.kernel.org/category/releases.html) +- [Debian kernel patches](https://salsa.debian.org/kernel-team/linux/-/tree/master/debian/patches) + +## Related Topics + +