ironcore-in-a-box

Overview

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.

Prerequisites

Ensure you have the following installed before running the project:

• curl
• make
• go
• docker (recommended) or podman (refer to podman user guidance)

Linux Kernel Requirements

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.

Windows/WSL2 Requirements

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.

MacOS Requirements

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-connect

Installation

To set up and start the IronCore stack, run the following command from the root of this repository:

make up

This command will:

1. Create a local kind cluster (if it doesn't exist).
2. Deploy the IronCore stack components into the cluster.

Examples

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.

Cleanup

To remove the kind cluster and all deployed resources, run:

make down

This will effectively stop and delete the entire local IronCore environment created by this project.

License

Apache-2.0