IronCore in a Box is a project that brings up the IronCore stack inside a local kind cluster. It provides a local demo environment to illustrate the capabilities of IronCore.
This project supports Linux, macOS, and Windows (via WSL2) environments.
Ensure you have the following installed before running the project:
IronCore relies on specific Linux kernel features. Ensure your kernel has the following configurations enabled, at least as modules (=m):
- CONFIG_LWTUNNEL
- CONFIG_LWTUNNEL_BPF
- CONFIG_IPV6_TUNNEL
Most modern Linux distributions have these enabled by default. However, minimal installations or older versions might require a custom kernel build or module loading.
Important for Windows/WSL2 Users
The default WSL2 kernel often lacks the Linux options. You will likely need to compile a custom kernel. Please ensure you have followed the WSL2 Custom Kernel Guide before proceeding with the installation if the required kernel modules are missing.
When using docker, you cannot directly connect to container IPs attached to the docker network bridge. docker-mac-net-connect is a lightweight service daemon based on Wireguard which automatically maintains the appropriate routing tables on your macOS. This tool is able to make it possible to use the VIP to access provisioned VM directly from Mac's shell, without entering the docker virtual machine.
You can install and make it running each time when Mac is booted by using following commands. If you would like to start/stop this tool manually each time, simply run sudo docker-mac-net-connect after installation.
# Install via Homebrew
$ brew install chipmk/tap/docker-mac-net-connect
# Run the service and register it to launch at boot
$ sudo brew services start chipmk/tap/docker-mac-net-connectWhen using docker with colima, its default memory size is small and dpservice-system cannot start.
If already started, stop colima and then start it with colima start --edit and change memory to e.g. 8.
To set up and start the IronCore stack, run the following command from the root of this repository:
make upThis command will:
- Create a local kind cluster (if it doesn't exist).
- Deploy the IronCore stack components into the cluster.
During make up, the IPv4 public VIP range is auto-detected from the current kind container network (for example 172.19.1.0/24 when kind runs on 172.19.0.0/16) and used to render runtime kustomize overlays under .tmp/runtime-overlays/.
For development on libvirt-provider you can point IronCore in a Box at a local checkout and/or a custom image tag instead of the upstream defaults. When either of the following environment variables is set, make up writes a mutated copy of the kustomize tree to .tmp/config/ and deploys from there:
| Variable | Effect |
|---|---|
LIBVIRT_PROVIDER_CONFIG_DIR |
Replace the remote github.com/ironcore-dev/libvirt-provider/config/default?ref=... kustomize resource with a relative path to a local libvirt-provider/config/default directory. |
LIBVIRT_PROVIDER_IMAGE_TAG |
Override the libvirt-provider container image tag (resolved against ghcr.io/ironcore-dev/libvirt-provider). |
Example — deploy from a local checkout with a locally-built image:
LIBVIRT_PROVIDER_CONFIG_DIR=../libvirt-provider/config/default \
LIBVIRT_PROVIDER_IMAGE_TAG=local \
make upBoth variables are independent and can be used on their own. With neither set, the upstream pinned versions are used unchanged.
You can find examples of how to use the IronCore API in the Examples directory. You can spin up a VM in a VPC / Overlay Network with a virtual IP. Using the command kubectl get machine,network,nic,virtualip to find out status and more information regarding the provisioned VM. By default, VMs enable password login for easy accessing and testing. The default username and password are ironcore and best123. Customized ignition can be also generated and used for other purposes.
Your local "datacenter" is at your fingertips to test. Ironcore API documentation can be found here which shows the whole capabilities of IronCore.
This project uses BATS for testing. It comes bundled with the repository in the form of git submodules and does not need to be externally installed. There are however some additional dependencies needed for tests:
- sshpass
- (Optional) shellcheck - Only if you want to lint tests
To execute tests, simply run
make testTests will reuse existing ironcore-in-a-box kind cluster if it already exists or bootstrap a new cluster if it does not. Note that tests may perform desctructive actions on the cluster.
Tests are written in bash. If you are developing tests, it's recommended to run them through linter before submitting a pull request.
make lint-tests
To remove the kind cluster and all deployed resources, run:
make downThis will effectively stop and delete the entire local IronCore environment created by this project.