README
¶
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:
Configlayer, containing additional information how to manage a machine / volume with the image.RootFSlayer, containing the root file system for the image.InitRAMFSlayer, containing the initramfs / initrd for the image.Kernellayer, 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
Documentation
¶
Index ¶
Constants ¶
const ( ConfigMediaType = "application/vnd.ironcore.image.config.v1+json" RootFSLayerMediaType = "application/vnd.ironcore.image.rootfs" InitRAMFSLayerMediaType = "application/vnd.ironcore.image.initramfs" KernelLayerMediaType = "application/vnd.ironcore.image.kernel" SquashFSLayerMediaType = "application/vnd.ironcore.image.squashfs" UKILayerMediaType = "application/vnd.ironcore.image.uki" ISOLayerMediaType = "application/vnd.ironcore.image.iso" )
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Image ¶
type Image struct {
// Config holds additional configuration for a machine / machine pool using the image.
Config Config
// RootFS is the layer containing the root file system.
RootFS image.Layer
// SquashFS is the layer containing the root file system.
SquashFS image.Layer
// InitRAMFs is the layer containing the initramfs / initrd.
InitRAMFs image.Layer
// Kernel is the layer containing the kernel.
Kernel image.Layer
// UKI is a Unified Kernel Image layer.
UKI image.Layer
// ISO is a layer containing a bootable ISO image.
ISO image.Layer
}
Image is an ironcore image.
Source Files
Directories