https://github.com/metal-stack/metal-images
CI-Builds for the metal-stack OS images
https://github.com/metal-stack/metal-images
containers debian linux metal-images ubuntu
Last synced: 3 months ago
JSON representation
CI-Builds for the metal-stack OS images
- Host: GitHub
- URL: https://github.com/metal-stack/metal-images
- Owner: metal-stack
- License: mit
- Created: 2020-02-17T17:58:57.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2026-01-28T12:34:50.000Z (3 months ago)
- Last Synced: 2026-01-29T04:59:24.117Z (3 months ago)
- Topics: containers, debian, linux, metal-images, ubuntu
- Language: Go
- Homepage:
- Size: 759 KB
- Stars: 15
- Watchers: 7
- Forks: 1
- Open Issues: 22
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# metal-images
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 .
More information about the image store is available in [IMAGE_STORE.md](./IMAGE_STORE.md).
Information about our initial architectural decisions can be found in [ARCHITECTURE.md](./ARCHITECTURE.md).
## Supported Images
Currently these images are supported:
1. Debian 12
1. Ubuntu 24.04
1. Firewall 3.0-ubuntu (based on Ubuntu 24.04)
1. Nvidia (based on Debian 12)
## Unsupported Images
We also publish images that we need for special purposes but do not officially support. Use at your own risk.
1. Almalinux 9
### 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.
## 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.
Released images are tagged with the release date and can be accessed using the following image URL pattern:
`https://images.metal-stack.io/metal-os/20240913/debian/12/img.tar.lz4`
Images built from the master branch are accessible at an image URL like this:
`https://images.metal-stack.io/metal-os/stable/debian/12/img.tar.lz4`
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.
## 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.
Before you can start developing changes for metal-images or even introduce new operating systems, you should install the following tools:
- **docker**: for sure
- **golang**
- **kvm**: hypervisor used for integration tests
- **lz4**: to compress tarballs
- enable docker's [**containerd image store**](https://docs.docker.com/engine/storage/containerd/#enable-containerd-image-store-on-docker-engine)
- **[cloud-hypervisor](https://github.com/cloud-hypervisor/cloud-hypervisor)**: virtual machine monitor running on top of KVM to spin up MicroVMs for integration tests
You can build metal-images like that:
```bash
# for debian images
make debian
# for ubuntu images
make ubuntu
# for firewall images
make firewall
# for nvidia images
make nvidia
# for almalinux images
make almalinux
```
*IMPORTANT* if you prefer the old docker build output instead of the fancy buildx srolling behind output, do the following:
```bash
BUILDKIT_PROGRESS=plain make debian
```
For integration testing the images are started as [cloud-hypervisor](https://www.cloudhypervisor.org) VMs and basic properties like interfaces to other metal-stack components, kernel parameters, internet accessibility, DNS resolution etc. are checked with [goss](https://github.com/aelsabbahy/goss) in a GitHub action workflow. Integration tests are also executed if you build an image locally.
### Debugging Image Provisioning
In some cases it may be necessary to manually figure out the commands for provisioning a machine image. To do this in a real server environment, it is possible to hook into the metal-hammer through the machine's serial console.
You can interrupt the metal-hammer at any time by sending a keyboard interrupt. The metal-hammer takes a short break before booting into the operating system kernel, which is a good time to send the interrupt.
To prevent the machine from rebooting, you should immediately issue the following command:
```bash
while true; do echo "1" > /dev/watchdog && sleep 55; done &
```
If you want to enter the operating system through `chroot`, you need to remount some file systems that were mounted by the metal-hammer during provisioning:
```bash
# the mount points also depend on the file system layout of the machine, so please only take this as an example:
mount /dev/sda2 /rootfs
mount -t vfat /dev/sda1 /rootfs/boot/efi
mount -t proc /proc /rootfs/proc
mount -t sysfs /sys /rootfs/sys
mount -t efivarfs /sys/firmware/efi/efivars /rootfs/sys/firmware/efi/efivars
mount -t devtmpfs /dev /rootfs/dev
```
Finally, you can then enter the provisioned OS image.
```bash
chroot /rootfs
# maybe you can mount further file systems here, which was not possible in the u-root environment of the metal-hammer
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).