Skip to content

docs: document the OS image lifecycle and provisioning model #307

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
l0wl3vel wants to merge 1 commit into
base: main
Choose a base branch
from
+18 −0
Open

docs: document the OS image lifecycle and provisioning model #307

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions docs/04-For Operators/02-operating-systems.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,24 @@ The supported images for firewalls are:
| :------- | :----------- | :------ | -------- |
| Linux | Ubuntu | 3 | 24.04 |

## Image Lifecycle

Our images are derived from the official Docker images of the respective distribution. On top of that, we add the components required by the metal-stack infrastructure, e.g. FRR for routing-to-the-host and automation tools like [cloud-init](https://docs.cloud-init.io/en/latest/index.html) to run user provided post-install tasks.

@majst01 majst01 Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We actually only install ignition

@l0wl3vel l0wl3vel Jun 30, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see we install cloud-init here and also mention userdata: https://github.com/metal-stack/metal-images/blob/master/debian/Dockerfile

What is cloud-init used for and is it not accessible to the end user?

@majst01 majst01 Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you are right, it was removed once back in time and added again :-) We should therefore mention both. Ignition is the one used for the gardener integration. Sorry for the noise.

@Gerrit91 Gerrit91 Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not think we have any E2E for cloud-init bootstrapping though. :(

@Gerrit91 Gerrit91 Jun 30, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CAPMS would like to switch to cloud-init as far as I know. Maybe we can test it there.

@ma-hartma ma-hartma Jul 1, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, there is an issue: metal-stack/cluster-api-provider-metal-stack#92

@l0wl3vel l0wl3vel Jul 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could someone, who has worked with these features, please write a paragraph about that? I am not that familiar with our implementation and use cases.

And lets please skip "to-be-implemented" features in the docs and instead create a follow up issue.


Every image registered with the metal-api carries one of the following lifecycle classifications:

| Classification | Meaning |
| :------------- | :--------------------------------------------------------------------------------------- |
| preview | Recently introduced image, not yet recommended for production use |
| supported | Regularly updated and scanned image, recommended for production use |
| deprecated | Image will expire and be removed soon, users should switch to a newer image |

These classifications prevent breaking changes in new images from affecting production workloads.

:::info
Operating system images are provided by the operators of a metal-stack installation, not by its end-users. End-users can only choose from the images that have been registered with the metal-api. If you require an additional image in an installation, get in touch with your operators.
:::

## Building Your Own Images

It is fully possible to build your own operating system images and provision them through the metal-stack without any in-tree implementations.
Expand Down