Skip to content

Commit 9a8a53b

Browse files
authored
Merge branch 'main' into docs/gpu-vgpu-setup
2 parents 4aaabe3 + 3e58234 commit 9a8a53b

12 files changed

Lines changed: 323 additions & 12 deletions

File tree

‎assets/scss/blocks/_hero.scss‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,34 @@
5656
}
5757
}
5858

59+
.hero-taglines {
60+
list-style: none;
61+
padding: 0;
62+
margin: 1rem 0 0;
63+
display: flex;
64+
flex-wrap: wrap;
65+
gap: 0.6rem;
66+
}
67+
68+
.hero-tagline {
69+
display: inline-block;
70+
padding: 0.4rem 0.9rem;
71+
border: 1px solid rgba($cozy-light-blue, 0.55);
72+
border-radius: 999px;
73+
color: $cozy-white;
74+
background: rgba($cozy-dark-blue, 0.18);
75+
font-size: 0.95rem;
76+
font-weight: 600;
77+
line-height: 1.2;
78+
letter-spacing: 0.01em;
79+
white-space: nowrap;
80+
81+
@include media-breakpoint-down(sm) {
82+
white-space: normal;
83+
font-size: 0.9rem;
84+
}
85+
}
86+
5987
// Align Kubernetes Certified logo with the title top
6088
.row.align-items-start {
6189
img[alt="Certified Kubernetes"] {

‎content/en/_index.html‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,13 @@
11
---
22
title: "Cozystack: Free Cloud Platform based on Kubernetes"
3-
description: >
3+
description: >
44
Transform a set of bare metal servers into an intelligent system with a simple REST API for spawning Kubernetes clusters, Databases-as-a-Service, virtual machines, load balancers, HTTP caching services, and other services with ease.
55

66
Use Cozystack to build your own cloud or provide cost-effective development environments.
7+
taglines:
8+
- Self-Hosted Alternative to AWS
9+
- AI-Ready Infrastructure
10+
- Open-Source VMware Alternative
711
benefits:
812
- title: API-first
913
icon: fas fa-code

‎content/en/docs/next/getting-started/requirements.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ To run this tutorial, you will need the following setup:
3434
- There are [other installation methods]({{% ref "/docs/next/install/talos" %}}) which require either any Linux or no OS at all to start.
3535

3636
**BIOS/UEFI Settings:**
37-
- **Secure Boot must be disabled.**<br>
38-
Secure Boot is currently not supported and must be disabled in the BIOS/UEFI settings before installation.
37+
- **Secure Boot.**<br>
38+
Talos Linux ships pre-signed kernel modules and works with Secure Boot enabled. On non-Talos Ubuntu hosts, the default piraeus-operator flow compiles DRBD in-cluster; the resulting unsigned modules are rejected by kernel lockdown when Secure Boot is enforced. The simplest path is to disable Secure Boot in BIOS/UEFI; alternatively, follow [Ubuntu + Secure Boot]({{% ref "/docs/next/install/kubernetes/ubuntu-secure-boot" %}}) to pre-install dkms-signed DRBD on the host.
3939

4040
**Networking:**
4141
- Routable FQDN domain.<br>If you don't have one, you can use [nip.io](https://nip.io/) with dash notation

‎content/en/docs/next/install/kubernetes/generic.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ For new production deployments, [Talos Linux]({{% ref "/docs/next/guides/talos"
2020

2121
## Prerequisites
2222

23+
{{% alert color="warning" %}}
24+
**Ubuntu hosts with UEFI Secure Boot enabled** require pre-installing `drbd-dkms` before deploying Cozystack. The default piraeus-operator flow compiles DRBD in-cluster and `insmod`s the unsigned module, which kernel lockdown rejects with `Key was rejected by service`. See [Ubuntu + Secure Boot]({{% ref "/docs/next/install/kubernetes/ubuntu-secure-boot" %}}) for the workaround.
25+
{{% /alert %}}
26+
2327
### Supported Distributions
2428

2529
Cozystack has been tested on:
Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
title: "Ubuntu Secure Boot: DRBD prerequisites"
3+
linkTitle: "Ubuntu + Secure Boot"
4+
description: "Prepare Ubuntu LTS hosts with UEFI Secure Boot enabled for Cozystack non-Talos installation by pre-installing drbd-dkms from the LINBIT PPA"
5+
weight: 52
6+
---
7+
8+
This page covers a single prerequisite for installing Cozystack on Ubuntu hosts where UEFI Secure Boot is enabled. If your nodes are Talos Linux, or Ubuntu with Secure Boot disabled, you can skip this page — the default piraeus-operator flow handles those cases.
9+
10+
## Why this is needed
11+
12+
Cozystack uses [LINSTOR](https://linbit.com/linstor/) for replicated block storage, which depends on the DRBD 9.x kernel module. The piraeus-operator that ships with Cozystack defaults to **compiling DRBD from source on each node at runtime** and loading the module via `insmod`.
13+
14+
On hosts where UEFI Secure Boot is enabled, the kernel's lockdown subsystem rejects unsigned modules at load time:
15+
16+
```text
17+
insmod: ERROR: could not insert module ./drbd.ko: Key was rejected by service
18+
```
19+
20+
(A preceding `chcon: can't apply partial context to unlabeled file './drbd.ko'` line may also appear when the loader image sets `LB_SELINUX_AS` — that warning is benign and unrelated to the load failure.)
21+
22+
The compiled `.ko` files are not signed against any key the host trusts, so `init_module()` fails. The linstor satellite Pod never reaches `Ready` and Cozystack storage stays broken.
23+
24+
This is common on bare-metal Ubuntu installs and on cloud SKUs that ship with Secure Boot enabled. Stock cloud-VM images on AWS, GCP, and Azure typically ship without Secure Boot enforcement and the default piraeus-operator flow works as-is.
25+
26+
This guide covers Ubuntu LTS only. Debian 12 has the same DRBD-unsigned-module problem under Secure Boot but LINBIT does not publish a Debian PPA — those operators must use LINBIT's customer-portal apt mirror or build and sign drbd-dkms manually. RHEL/SUSE flows (LINBIT-managed RPM repos with pre-signed kmods) are out of scope here.
27+
28+
## Recommended fix: pre-install drbd-dkms on the host
29+
30+
Install the LINBIT-published `drbd-dkms` package on each node **before** deploying Cozystack, then add a `usermode_helper=disabled` modprobe.d drop-in and mask the host-side `drbd.service`. Minimal Ubuntu cloud images do not ship `add-apt-repository`; install `software-properties-common` first if it is missing. The full flow on each node:
31+
32+
1. Add LINBIT PPA, install `drbd-dkms`. The package goes through Ubuntu's standard `shim-signed` + dkms pipeline:
33+
- On first dkms install with no existing MOK present, Ubuntu's `shim-signed` postinst generates a per-host signing keypair at `/var/lib/shim-signed/mok/MOK.priv` and `/var/lib/shim-signed/mok/MOK.der` (referenced from `/etc/dkms/framework.conf` as `mok_signing_key` / `mok_certificate`).
34+
- dkms compiles the module against the running kernel and signs the freshly built `.ko` against that key.
35+
- During `apt-get install`, debconf prompts the operator for an enrollment password; the matching public key is queued for MOK enrollment via `mokutil --import`. **If the install runs non-interactively** (`DEBIAN_FRONTEND=noninteractive`), the prompt is bypassed and the operator must run `mokutil --import /var/lib/shim-signed/mok/MOK.der` manually after the install.
36+
2. Write `/etc/modprobe.d/cozystack-drbd.conf` with `options drbd usermode_helper=disabled`. piraeus-operator's daemonset sets `LB_FAIL_IF_USERMODE_HELPER_NOT_DISABLED=yes` on the loader, so the loader fails on a host-loaded module without that param (see LINBIT/drbd [`entry.sh` line 332](https://github.com/LINBIT/drbd/blob/8c279459a32823b495a2649fc6dafc9fdfac1c7f/docker/entry.sh#L332) and the env wiring in piraeus-operator's [satellite daemonset](https://github.com/piraeusdatastore/piraeus-operator/blob/3bf3e75a142f69534609a6323c88db29150047a2/pkg/resources/satellite/satellite/daemonset.yaml)).
37+
3. `systemctl mask drbd.service`. `drbd-utils` lands on the host transitively as a hard apt dependency of `drbd-dkms` and ships a `drbd.service` unit that would race piraeus-operator's satellite container if accidentally enabled.
38+
4. Write `/etc/modules-load.d/cozystack-drbd.conf` containing `drbd` so `systemd-modules-load.service` loads the module on every boot. Without this file the host depends on whatever (if any) `modules-load.d` entry the `drbd-utils` package ships, which has varied across releases — making it explicit removes the ambiguity and matches the path the companion Ansible playbook writes.
39+
5. **Reboot each node and confirm MOK enrollment at the shim console** (Enroll MOK → View key → Continue → enter the password set during step 1's debconf prompt or via `mokutil --import`). One reboot per node is required for the operator to walk through shim's MOK Manager. This step cannot be automated — it is the design of UEFI Secure Boot.
40+
6. After enrollment, the kernel trusts the signing key and the dkms-built DRBD module loads with the right param.
41+
42+
Once the host has DRBD 9.x loaded with `usermode_helper=disabled`, piraeus-operator's loader detects the host-loaded module on Pod startup and exits cleanly without attempting its own compile and `insmod`. No operator-side configuration is required.
43+
44+
## Automated path: ansible-cozystack
45+
46+
The [`cozystack/ansible-cozystack`](https://github.com/cozystack/ansible-cozystack) collection is being extended to automate the install side of the dance via [PR #39](https://github.com/cozystack/ansible-cozystack/pull/39). When that PR merges, `examples/ubuntu/prepare-ubuntu.yml` will add the LINBIT PPA, install `drbd-dkms`, write `/etc/modprobe.d/cozystack-drbd.conf` with `options drbd usermode_helper=disabled`, mask the host-side `drbd.service`, and try to load the module immediately. Variables to know once the PR lands:
47+
48+
- `cozystack_enable_drbd_dkms` (default `true`) — set `false` on Talos hosts or where Secure Boot is disabled and you prefer the in-cluster compile path.
49+
- `cozystack_drbd_ppa` (default `ppa:linbit/linbit-drbd9-stack`) — point at a Launchpad mirror of the LINBIT archive.
50+
- `cozystack_drbd_supported_releases` (default `[jammy, noble]`) — extend in inventory once LINBIT publishes for a new Ubuntu series.
51+
52+
Until that PR merges, follow the manual path below. The two flows produce the same end state on the host.
53+
54+
After the playbook (or the manual steps) completes, **reboot each node** and confirm MOK enrollment at the shim console. Then re-run the playbook on the same nodes; the second run should report `changed=0` and the modprobe will succeed.
55+
56+
{{% alert color="warning" %}}
57+
**MOK enrollment is interactive and per-node**. The operator must access the console (physical, IPMI, or KVM) of each node on the next reboot and walk through shim's MOK Manager. There is no Kubernetes-level workaround — kernel module signing under Secure Boot is a host-firmware concern.
58+
{{% /alert %}}
59+
60+
## Manual path
61+
62+
For operators who do not use Ansible, the equivalent steps on each Ubuntu LTS node are:
63+
64+
```bash
65+
# 1. Install add-apt-repository (not present on minimal cloud images).
66+
sudo apt-get update
67+
sudo apt-get install --yes software-properties-common
68+
69+
# 2. Add LINBIT PPA and install drbd-dkms. During the install, debconf
70+
# prompts for a one-time MOK enrollment password — choose any
71+
# password you can re-enter at the shim console after reboot.
72+
sudo add-apt-repository --yes ppa:linbit/linbit-drbd9-stack
73+
sudo apt-get install --yes drbd-dkms
74+
75+
# 3. Configure the required module parameter.
76+
sudo tee /etc/modprobe.d/cozystack-drbd.conf <<'EOF'
77+
options drbd usermode_helper=disabled
78+
EOF
79+
80+
# 4. Mask the host drbd.service so it cannot race piraeus-operator.
81+
sudo systemctl mask drbd.service
82+
83+
# 5. Persist the module load on boot. The drbd-utils package's own
84+
# /lib/modules-load.d/ entry has varied across releases; an explicit
85+
# /etc/ entry overrides anything in /lib/ and removes the ambiguity.
86+
echo drbd | sudo tee /etc/modules-load.d/cozystack-drbd.conf
87+
88+
# 6. Reboot. At the shim MOK Manager menu, choose:
89+
# Enroll MOK -> View key -> Continue -> Yes -> enter the password
90+
# you set at the debconf prompt during step 2.
91+
sudo reboot
92+
```
93+
94+
After the reboot, verify the module loaded with the right param:
95+
96+
```bash
97+
cat /sys/module/drbd/parameters/usermode_helper
98+
# expected: disabled
99+
```
100+
101+
Then deploy Cozystack as usual. The piraeus-operator loader will detect the host-loaded DRBD and exit cleanly.
102+
103+
## What happens at deploy time
104+
105+
When piraeus-operator's satellite Pod starts on a node, its `drbd-module-loader` initContainer runs [LINBIT/drbd's `entry.sh`](https://github.com/LINBIT/drbd/blob/master/docker/entry.sh). Lines 328–339 short-circuit the compile + insmod path when DRBD is already loaded on the host:
106+
107+
```sh
108+
if grep -q '^drbd ' /proc/modules; then
109+
echo "DRBD module is already loaded"
110+
[[ $LB_FAIL_IF_USERMODE_HELPER_NOT_DISABLED == yes ]] \
111+
&& ! grep -qw disabled /sys/module/drbd/parameters/usermode_helper \
112+
&& die "..."
113+
drbd_matches_min_version "$LB_DRBD_MIN_LOADED_VERSION" || die "..."
114+
exit 0
115+
fi
116+
```
117+
118+
Two preconditions are checked:
119+
120+
1. The module must be loaded with `usermode_helper=disabled`. The modprobe.d drop-in above takes care of this.
121+
2. The loaded version must satisfy `LB_DRBD_MIN_LOADED_VERSION`. piraeus-operator's daemonset sets it to `9`. LINBIT's `drbd-dkms` ships DRBD 9.x, so this is automatic.
122+
123+
Both conditions met → `exit 0` → satellite Pod proceeds. No operator-side change to piraeus-operator or LinstorSatelliteConfiguration is needed.
124+
125+
## Alternatives
126+
127+
- **Talos Linux** ([guide]({{% ref "/docs/next/guides/talos" %}})) ships pre-signed DRBD modules in its system extensions and has none of these problems. Recommended for new deployments where you do not need a custom Linux distro.
128+
- **Disable Secure Boot** in the host's UEFI firmware. The default in-cluster compile path then works without modification. Operationally undesirable for fleets where Secure Boot is part of the security baseline, but a valid escape hatch.
129+
- **Build and sign drbd-dkms manually** against your own enterprise CA. This is what production environments with their own MOK / shim signing infrastructure already do; it is out of scope for this guide.
130+
131+
## Troubleshooting
132+
133+
**`modprobe drbd` returns `Key was rejected by service` after dkms install** — the dkms-generated MOK key is queued but not yet enrolled. Reboot the node and confirm enrollment at the shim console (Enroll MOK → View key → Continue → dkms password). Re-run modprobe.
134+
135+
**`cat /sys/module/drbd/parameters/usermode_helper` is not `disabled`** — the modprobe.d drop-in is missing or the module was loaded before it was written. `sudo rmmod drbd && sudo modprobe drbd` after the drop-in is in place, or reboot.
136+
137+
**piraeus-operator loader Pod logs `Could not load DRBD kernel modules`** even after host install — check `LB_DRBD_MIN_LOADED_VERSION` via `kubectl --namespace cozy-linstor describe pod --selector app.kubernetes.io/component=linstor-satellite` and `cat /proc/drbd` on the host. The host module must be at least the loader's required minimum (`9` per piraeus-operator's daemonset). LINBIT PPA `drbd-dkms` is 9.x so this is rarely the issue.
138+
139+
**Ubuntu 26.04+ or interim releases (Oracular 24.10, Plucky 25.04)** — LINBIT's PPA publishes `drbd-dkms` only for the LTS series LINBIT keeps current. Check [the PPA detail page](https://launchpad.net/~linbit/+archive/ubuntu/linbit-drbd9-stack) for the current series list. On unsupported releases the PPA add fails on a 404 Release file. Build and sign drbd-dkms manually, downgrade to a supported LTS, or wait for LINBIT to publish for your release. Ansible operators can extend `cozystack_drbd_supported_releases` once that happens.

‎content/en/docs/next/install/providers/hetzner.md‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -52,9 +52,8 @@ Complete the following steps to prepare your servers for installing Cozystack:
5252

5353
1. Make sure that Secure Boot is disabled.
5454

55-
Secure Boot is currently not supported in Talos Linux.
56-
If your server is configured to use Secure Boot, you need to disable this feature in your BIOS.
57-
Otherwise, it will block the server from booting after Talos Linux installation.
55+
The Talos installation procedure used in this guide (rescue-mode `installimage` writing a standard EFI/MBR layout) requires Secure Boot disabled. Talos does support UEFI Secure Boot via its UKI / SecureBoot installation flow, but that path is not covered here.
56+
If your server is configured to use Secure Boot, disable it in BIOS before continuing — otherwise it will block the server from booting after Talos installation.
5857

5958
Check it with the following command:
6059

‎content/en/docs/v1.2/guides/platform-stack/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ Deployment involves the following components:
170170
This architecture ensures isolated, scalable, and efficient Kubernetes environments tailored for each tenant.
171171

172172
- Supported version: Kubernetes v1.32.4
173-
- Operator: [aenix-io/etcd-operator](https://github.com/aenix-io/etcd-operator) v0.4.2
173+
- Kubernetes operator: [aenix-io/etcd-operator](https://github.com/aenix-io/etcd-operator) v0.4.3
174174
- Managed application reference: [Kubernetes]({{% ref "/docs/v1.2/kubernetes" %}})
175175

176176

‎content/en/docs/v1.3/getting-started/requirements.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ To run this tutorial, you will need the following setup:
3434
- There are [other installation methods]({{% ref "/docs/v1.3/install/talos" %}}) which require either any Linux or no OS at all to start.
3535

3636
**BIOS/UEFI Settings:**
37-
- **Secure Boot must be disabled.**<br>
38-
Secure Boot is currently not supported and must be disabled in the BIOS/UEFI settings before installation.
37+
- **Secure Boot.**<br>
38+
Talos Linux ships pre-signed kernel modules and works with Secure Boot enabled. On non-Talos Ubuntu hosts, the default piraeus-operator flow compiles DRBD in-cluster; the resulting unsigned modules are rejected by kernel lockdown when Secure Boot is enforced. The simplest path is to disable Secure Boot in BIOS/UEFI; alternatively, follow [Ubuntu + Secure Boot]({{% ref "/docs/v1.3/install/kubernetes/ubuntu-secure-boot" %}}) to pre-install dkms-signed DRBD on the host.
3939

4040
**Networking:**
4141
- Routable FQDN domain.<br>If you don't have one, you can use [nip.io](https://nip.io/) with dash notation

‎content/en/docs/v1.3/install/kubernetes/generic.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,10 @@ For new production deployments, [Talos Linux]({{% ref "/docs/v1.3/guides/talos"
2020

2121
## Prerequisites
2222

23+
{{% alert color="warning" %}}
24+
**Ubuntu hosts with UEFI Secure Boot enabled** require pre-installing `drbd-dkms` before deploying Cozystack. The default piraeus-operator flow compiles DRBD in-cluster and `insmod`s the unsigned module, which kernel lockdown rejects with `Key was rejected by service`. See [Ubuntu + Secure Boot]({{% ref "/docs/v1.3/install/kubernetes/ubuntu-secure-boot" %}}) for the workaround.
25+
{{% /alert %}}
26+
2327
### Supported Distributions
2428

2529
Cozystack has been tested on:

0 commit comments

Comments
 (0)