onmetalimage

README

onmetal-image

Overview

onmetal-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 onmetal image.

Onmetal images are used for machine / volume pool implementors (see onmetal-api) to prepare and bootstrap machines and machine disks.

They are custom OCI images, meaning they can managed with 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 install

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

Library

The library behind onmetal-image can be fetched by running

go get github.com/onmetal/onmetal-image@latest

Usage

Library

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

Command-Line Tool

For getting basic help, you can simply run

onmetal-image help

This will print the available commands.

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

onmetal-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 ~/.onmetal) and print out the id of the built image.

To tag the image with a more fluent name, run

onmetal-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.

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

To push the image to the registry, run

onmetal-image push ghcr.io/onmetal/onmetal-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

onmetal-image pull ghcr.io/onmetal/onmetal-image/my-image:latest

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

Documentation

Index

• Constants
• func SetupContext(ctx context.Context) context.Context
• type Config
• type Image
  • func ResolveImage(ctx context.Context, ociImg image.Image) (*Image, error)

Constants

const (
	ConfigMediaType         = "application/vnd.onmetal.image.config.v1alpha1+json"
	RootFSLayerMediaType    = "application/vnd.onmetal.image.rootfs.v1alpha1.rootfs"
	InitRAMFSLayerMediaType = "application/vnd.onmetal.image.initramfs.v1alpha1.initramfs"
	KernelLayerMediaType    = "application/vnd.onmetal.image.vmlinuz.v1alpha1.vmlinuz"
)

Functions

func SetupContext

func SetupContext(ctx context.Context) context.Context

SetupContext sets up context.Context to not log warnings on onmetal media types.

Types

type Config

type Config struct {
	CommandLine string `json:"commandLine,omitempty"`
}

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
	// InitRAMFs is the layer containing the initramfs / initrd.
	InitRAMFs image.Layer
	// Kernel is the layer containing the kernel.
	Kernel image.Layer
}

Image is an onmetal image.

func ResolveImage

func ResolveImage(ctx context.Context, ociImg image.Image) (*Image, error)

ResolveImage resolves an oci image to an onmetal Image.