Skip to content

Update README #405

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

Draft
simcod wants to merge 1 commit into
base: master
Choose a base branch
from
+15 −9
Draft

Update README #405

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
24 changes: 15 additions & 9 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,13 @@
# metal-images
# metal-stack.io | metal-images

![Go version](https://img.shields.io/github/go-mod/go-version/metal-stack/metal-images)
[![Go Report Card](https://goreportcard.com/badge/github.com/metal-stack/metal-images)](https://goreportcard.com/report/github.com/metal-stack/metal-images)
[![go.dev reference](https://img.shields.io/badge/go.dev-reference-007d9c?logo=go&logoColor=white&style=flat-square)](https://pkg.go.dev/github.com/metal-stack/metal-images)
[![Build](https://github.com/metal-stack/metal-images/actions/workflows/docker.yaml/badge.svg?branch=master)](https://github.com/metal-stack/metal-images/actions)
[![Slack](https://img.shields.io/badge/slack-metal--stack-brightgreen.svg?logo=slack)](https://metal-stack.slack.com/)

This project builds operating system images that can be used for bare metal server deployments with [metal-stack](https://metal-stack.io).
Every OS image is built from a Dockerfile, exported to a lz4 compressed tarball, and uploaded to <https://images.metal-stack.io/>.
Every OS image is built from a `Dockerfile`, exported to a `lz4` compressed tarball, and uploaded to [images.metal-stack.io](https://images.metal-stack.io/).

More information about the image store is available in [IMAGE_STORE.md](./IMAGE_STORE.md).

Expand All @@ -24,11 +30,11 @@ We also publish images that we need for special purposes but do not officially s

### GPU Support

With the nvidia image a worker has GPU support. Please check our official documentation on [docs.metal-stack.io](https://metal-stack.io/docs/gpu-workers) on how to get this running on Kubernetes.
GPU support for workers are available by using the `debian-nvidia` images. Please check our official documentation at [metal-stack.io](https://metal-stack.io/docs/gpu-workers) how to get this running on Kubernetes.

## How new images become usable in a metal-stack partition

Images are synchronized to partitions using a service called [metal-image-cache-sync](https://github.com/metal-stack/metal-image-cache-sync). The service mirrors the public operating system images to the management servers and transparently serves the metal images within a partition.
Images are synchronized to partitions using a service called [metal-image-cache-sync](https://github.com/metal-stack/metal-image-cache-sync). This service mirrors the public operating system images to the management servers and transparently serves the metal-images within a partition.

Released images are tagged with the release date and can be accessed using the following image URL pattern:

Expand All @@ -42,15 +48,15 @@ For other branches, the URL pattern is as follows:

`https://images.metal-stack.io/metal-os/pull_requests/${CI_COMMIT_REF_SLUG}/debian/12/img.tar.lz4`

These URLs can be used to define an image at the metal-api.
These URLs can be used to define an image at the `metal-api`.

## Local development and integration testing

Please also refer to our documentation on docs.metal-stack.io on [Build Your Own Images](https://metal-stack.io/docs/operating-systems#building-your-own-images) to check for the contract an OS image is expected to fulfill.
Please also refer to our section [Build Your Own Images](https://metal-stack.io/docs/operating-systems#building-your-own-images) in our documentation to check for the contract an OS image is expected to fulfill.

Before you can start developing changes for metal-images or even introduce new operating systems, you should install the following tools:

- **docker**: for sure
- **docker**
- **golang**
- **kvm**: hypervisor used for integration tests
- **lz4**: to compress tarballs
Expand All @@ -76,7 +82,7 @@ make nvidia
make almalinux
```

*IMPORTANT* if you prefer the old docker build output instead of the fancy buildx srolling behind output, do the following:
_IMPORTANT_ if you prefer the old docker build output instead of the fancy buildx rolling behind output, do the following:
Copy link
Copy Markdown
Contributor

@majst01 majst01 Apr 19, 2026

Choose a reason for hiding this comment

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

Suggested change
_IMPORTANT_ if you prefer the old docker build output instead of the fancy buildx rolling behind output, do the following:
_IMPORTANT_ if you prefer the old docker build output instead of the fancy buildx scrolling behind output, do the following:


```bash
BUILDKIT_PROGRESS=plain make debian
Expand Down Expand Up @@ -118,4 +124,4 @@ vgchange -ay
mount /dev/csi-lvm/varlib /var/lib/
```

Keep in mind that you are still running on the metal-hammer kernel, which is different from the kernel that will be run in the operating system after provisioning. For further information on the metal-stack machine provisioning sequence, check out documentation on [docs.metal-stack.io](https://metal-stack.io/docs/architecture/#Machine-Provisioning-Sequence). The kernel used by the metal-hammer is built on our own inside the [kernel repository](https://github.com/metal-stack/kernel).
Keep in mind that you are still running on the metal-hammer kernel, which is different from the kernel that will be run in the operating system after provisioning. For further information on the metal-stack machine provisioning sequence, check out our documentation at [metal-stack.io](https://metal-stack.io/docs/architecture/#Machine-Provisioning-Sequence). The kernel used by the metal-hammer is built on our own inside the [kernel repository](https://github.com/metal-stack/kernel).
Loading