Update machine controller docs #2056
Conversation
rajaSahil
commented
Jan 6, 2026
rajaSahil
commented
- Update machine controller docs
kubermatic-bot
added
dco-signoff: yes
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here. DetailsNeeds approval from an approver in each of these files:Approvers can indicate their approval by writing |
rajaSahil
force-pushed
the
update-machine-controller-docs
branch
from
339532b to
e1835ae
Compare
Signed-off-by: rajaSahil <[email protected]>
rajaSahil
force-pushed
the
update-machine-controller-docs
branch
from
8530589 to
6b4063a
Compare
Signed-off-by: rajaSahil <[email protected]>
| ┌─────────────────────────────────────┐ | ||
| │ Cloud Instances (Worker Nodes) │ | ||
| └─────────────────────────────────────┘ | ||
| ``` |
There was a problem hiding this comment.
for of the vertical borders are unaligned
|
|
||
| ### Supported Operating Systems | ||
|
|
||
| - Ubuntu (20.04, 22.04, 24.04 LTS) |
|
|
||
| - Ubuntu (20.04, 22.04, 24.04 LTS) | ||
| - Flatcar Container Linux | ||
| - RHEL (Red Hat Enterprise Linux) 8.x |
| - Ubuntu (20.04, 22.04, 24.04 LTS) | ||
| - Flatcar Container Linux | ||
| - RHEL (Red Hat Enterprise Linux) 8.x | ||
| - Rocky Linux 8.5+ |
|
|
||
| ### Prerequisites | ||
|
|
||
| - Go 1.21 or later |
There was a problem hiding this comment.
Let's recommend the latest and greatest Go 1.25
| │ ├── e2e/ # End-to-end tests | ||
| │ └── tools/ # Test utilities | ||
| └── Makefile # Build automation | ||
| ``` |
There was a problem hiding this comment.
This schema is not accurate anymore: we introduced a dedicated module skd, we dropped userdata.
|
|
||
| To add support for a new operating system: | ||
|
|
||
| 1. **Create userdata package**: `pkg/userdata/<os-name>/` |
There was a problem hiding this comment.
All that's referred to userdata should be removed
|
|
||
| Before installing machine-controller, ensure you have: | ||
|
|
||
| - A running Kubernetes cluster (version 1.31 or later) |
There was a problem hiding this comment.
To avoid constantly updating this kubernetes version let's simply omit it
| machine-controller uses webhooks that require TLS certificates. Install cert-manager to automatically manage these certificates: | ||
|
|
||
| ```bash | ||
| kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.2/cert-manager.yaml |
There was a problem hiding this comment.
| kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.11.2/cert-manager.yaml | |
| kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.crds.yaml | |
| kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml |
| The Operating System Manager is responsible for managing user data and operating system configurations for worker nodes: | ||
|
|
||
| ```bash | ||
| kubectl apply -f https://github.com/kubermatic/machine-controller/raw/main/examples/operating-system-manager.yaml |
| operatingSystemSpec: | ||
| distUpgradeOnBoot: false | ||
| versions: | ||
| kubelet: "1.28.0" |
There was a problem hiding this comment.
| kubelet: "1.28.0" | |
| kubelet: "<YOUR-KUBERNETES-VERSION>" |
To avoid having outdated versions
| "template": { | ||
| "spec": { | ||
| "versions": { | ||
| "kubelet": "1.29.0" |
There was a problem hiding this comment.
| "kubelet": "1.29.0" | |
| "kubelet": "<YOUR-UPGRADED-KUBERNETES-VERSION>" |
To avoid having outdated versions
| operatingSystemSpec: | ||
| distUpgradeOnBoot: false | ||
| versions: | ||
| kubelet: "1.28.0" |
| operatingSystemSpec: | ||
| distUpgradeOnBoot: false | ||
| versions: | ||
| kubelet: "1.28.0" |
| operatingSystemSpec: | ||
| distUpgradeOnBoot: false | ||
| versions: | ||
| kubelet: "1.28.0" |
| @@ -0,0 +1,170 @@ | |||
| +++ | |||
| title = "Installation" | |||
There was a problem hiding this comment.
| title = "Installation" | |
| title = "Quick Start" |
There was a problem hiding this comment.
I know you didn't write this file but it contains URL for outdated ubuntu jammy, let's replace it with current LTS (24.04).
| - **Systemd**: Uses systemd for service management | ||
|
|
||
| {{% notice warning %}} | ||
| Amazon Linux 2 support ends on June 30, 2025. Consider migrating to Amazon Linux 2023 or other distributions for new deployments. |
There was a problem hiding this comment.
we need to rethink this doc as AL2 is EOL already and we should kill it too from our end
|
|
||
| ## Supported Versions | ||
|
|
||
| Machine-controller officially supports: |
There was a problem hiding this comment.
| Machine-controller officially supports: | |
| OSM officially supports: |
| - **Rocky Linux 8.x** (stable) | ||
| - **Rocky Linux 9.x** (latest) |
There was a problem hiding this comment.
| - **Rocky Linux 8.x** (stable) | |
| - **Rocky Linux 9.x** (latest) | |
| - **Rocky Linux 9.x** |
| ```bash | ||
| aws ec2 describe-images \ | ||
| --owners 792107900819 \ | ||
| --filters "Name=name,Values=Rocky-8-EC2-Base-*" \ |
There was a problem hiding this comment.
| --filters "Name=name,Values=Rocky-8-EC2-Base-*" \ | |
| --filters "Name=name,Values=Rocky-9-EC2-*" \ |
| publisher: "erockyenterprisesoftwarefoundationinc1653071250513" | ||
| offer: "rockylinux" | ||
| sku: "rocky-linux-8" | ||
| version: "latest" |
There was a problem hiding this comment.
| publisher: "erockyenterprisesoftwarefoundationinc1653071250513" | |
| offer: "rockylinux" | |
| sku: "rocky-linux-8" | |
| version: "latest" | |
| publisher: "resf" | |
| offer: "rockylinux-x86_64" | |
| sku: "9-base" | |
| version: "latest" |
| wget https://download.rockylinux.org/pub/rocky/8/images/x86_64/Rocky-8-GenericCloud-Base.latest.x86_64.qcow2 | ||
| ``` | ||
|
|
||
| 2. Upload to OpenStack Glance: | ||
| ```bash | ||
| openstack image create \ | ||
| --disk-format qcow2 \ | ||
| --container-format bare \ | ||
| --file Rocky-8-GenericCloud-Base.latest.x86_64.qcow2 \ | ||
| rocky-linux-8 | ||
| ``` | ||
|
|
||
| 3. Reference in MachineDeployment: | ||
| ```yaml | ||
| cloudProviderSpec: | ||
| image: "rocky-linux-8" |
There was a problem hiding this comment.
Same, please update to the Rocky9
| - **Ubuntu 20.04 LTS** (Focal Fossa) | ||
| - **Ubuntu 22.04 LTS** (Jammy Jellyfish) | ||
| - **Ubuntu 24.04 LTS** (Noble Numbat) |
There was a problem hiding this comment.
| - **Ubuntu 20.04 LTS** (Focal Fossa) | |
| - **Ubuntu 22.04 LTS** (Jammy Jellyfish) | |
| - **Ubuntu 24.04 LTS** (Noble Numbat) | |
| - **Ubuntu 24.04 LTS** (Noble Numbat) |
| offer: "0001-com-ubuntu-server-jammy" | ||
| sku: "22_04-lts-gen2" | ||
| version: "latest" |
There was a problem hiding this comment.
| offer: "0001-com-ubuntu-server-jammy" | |
| sku: "22_04-lts-gen2" | |
| version: "latest" | |
| offer: "ubuntu-24_04-lts" | |
| sku: "server-gen1" | |
| version: "latest" |
There was a problem hiding this comment.
Please replace all the old references of 22.04 with 24.04
There was a problem hiding this comment.
too much of outdated OS versions here too
| - Ubuntu (20.04, 22.04, 24.04 LTS) | ||
| - Flatcar Container Linux | ||
| - RHEL 8.x, 9.x | ||
| - Rocky Linux 8.x, 9.x | ||
| - Amazon Linux 2 |
There was a problem hiding this comment.
| - Ubuntu (20.04, 22.04, 24.04 LTS) | |
| - Flatcar Container Linux | |
| - RHEL 8.x, 9.x | |
| - Rocky Linux 8.x, 9.x | |
| - Amazon Linux 2 | |
| - Ubuntu (24.04 LTS) | |
| - Flatcar Container Linux | |
| - RHEL 9.x | |
| - Rocky Linux 9.x |
