ironcore-image

Overview

ironcore-image contains a library to simplify interaction with an OCI-comptabile registry, and it holds the specification as well as a simple command-line client for the ironcore-image.

IronCore images are used for machine / volume pool implementors (see ironcore) to prepare and bootstrap machines and machine disks.

They are custom OCI images, meaning they can be published in any OCI compatible registry. They consist of 4 layers:

1. Config layer, containing additional information how to manage a machine / volume with the image.
2. RootFS layer, containing the root file system for the image.
3. InitRAMFS layer, containing the initramfs / initrd for the image.
4. Kernel layer, containing the kernel for the image.

Installation

Command-Line Tool

To install the command tool, make sure you have a working go installation and GOBIN set up correctly. Then simply run

make build

This will install the tool available under $GOBIN/ironcore-image.

Library

The library behind ironcore-image can be fetched by running

go get github.com/ironcore-dev/ironcore-image@latest

Usage

Library

For the docs, check out the ironcore-image pkg.go.dev documentation.

Command-Line Tool

For getting basic help, you can simply run

ironcore-image help

This will print the available commands.

To build an ironcore-image, you'll need the rootfs, initramfs and kernel of your desired operating system. Once you have them on disk, simply run

ironcore-image build \
  --rootfs-file <path to rootfs file> \
  --initramfs-file <path to initramfs> \
  --kernel-file <path to kernel file>

This will build the image, put it into your local OCI store (usually at ~/.ironcore) and print out the id of the built image.

To tag the image with a more fluent name, run

ironcore-image tag <id> my-image:latest

This will tag the image with the name my-image and the tag latest.

To push an image to a remote registry, make sure you authenticated your local docker client with that registry. Consult your registry provider's documentation for instructions.

Once authenticated, tag your image, so it points towards that registry, e.g.

ironcore-image tag <id> ghcr.io/ironcore-dev/ironcore-image/my-image:latest

To push the image to the registry, run

ironcore-image push ghcr.io/ironcore-dev/ironcore-image/my-image:latest

:danger: This currently doesn't do any output, wait a while for it to be done.

To pull the pushed image, run

ironcore-image pull ghcr.io/ironcore-dev/ironcore-image/my-image:latest

OCI Specification

This project also defines and publishes the OCI image specification that operating systems must conform to in order to be compatible with the IronCore ecosystem.

Following this specification ensures that OS images can be used to boot bare-metal machines via the metal automation layer and can also be used in virtualized environments within the IronCore virtualization stack.

See the full OCI image layout specification for details on how to package your OS images for IronCore.

Contributing

We'd love to get feedback from you. Please report bugs, suggestions or post questions by opening a GitHub issue.

License

Apache-2.0