https://github.com/ironcore-dev/ironcore-image
IronCore OCI Image Specification, Library and Tooling
https://github.com/ironcore-dev/ironcore-image
ironcore oci os-image
Last synced: 28 days ago
JSON representation
IronCore OCI Image Specification, Library and Tooling
- Host: GitHub
- URL: https://github.com/ironcore-dev/ironcore-image
- Owner: ironcore-dev
- License: apache-2.0
- Created: 2021-10-12T19:51:08.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2025-04-12T09:35:24.000Z (about 1 month ago)
- Last Synced: 2025-04-12T10:26:36.566Z (about 1 month ago)
- Topics: ironcore, oci, os-image
- Language: Go
- Homepage:
- Size: 328 KB
- Stars: 1
- Watchers: 5
- Forks: 4
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# ironcore-image
[](https://api.reuse.software/info/github.com/ironcore-dev/ironcore-image)
[](https://goreportcard.com/report/github.com/ironcore-dev/ironcore-image)
[](https://pkg.go.dev/github.com/ironcore-dev/ironcore-image)
[](LICENSE)
[](https://makeapullrequest.com)
## 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](https://github.com/ironcore-dev/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
```shell
make build
```
This will install the tool available under `$GOBIN/ironcore-image`.
### Library
The library behind `ironcore-image` can be fetched by running
```shell
go get github.com/ironcore-dev/ironcore-image@latest
```
## Usage
### Library
For the docs, check out the [ironcore-image pkg.go.dev documentation](https://pkg.go.dev/github.com/ironcore-dev/ironcore-image).
### Command-Line Tool
For getting basic help, you can simply run
```shell
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
```shell
ironcore-image build \
--rootfs-file \
--initramfs-file \
--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
```shell
ironcore-image tag 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.
```shell
ironcore-image tag ghcr.io/ironcore-dev/ironcore-image/my-image:latest
```
To push the image to the registry, run
```shell
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
```shell
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](https://github.com/ironcore-dev/metal-operator) layer and can also be used in virtualized environments within the IronCore virtualization stack.
See the full [OCI image layout specification](OCI-SPEC.md) 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](LICENSE)