May 13, 2021

Running Potluck Images with runj

A quite new project called runj has been created which offers an interface between FreeBSD Jails and containerd. runj is already in the Ports tree or it can be found at https://github.com/samuelkarp/runj.

The Potluck container image library wants to provide complex services out of the box, like e.g. a complete postfix secondary mailserver. Many of the images are prepared to be orchestrated via nomad and nomad-pot-driver (which also is in the Ports tree).

This small how-to shows that these blocking nomad jails can also very easily be started via runj though.

Setting Up a Test VM

We are using bhyve with vm-bhyveto create a FreeBSD 13 VM to provide a test environment. Of course you can also run the examples below directly on your FreeBSD host or in a VM in any other hypervisor.

$ vm iso https://download.freebsd.org/ftp/releases/ISO-IMAGES/13.0/FreeBSD-13.0-RELEASE-amd64-disc1.iso  
$ vm create runjvm

Increase the memory size of the VM in runjvm.conf in your VM directory to 2048M before you install FreeBSD in it.

$ vm install -f runjvm FreeBSD-13.0-RELEASE-amd64-disc1.iso

You need to ensure that your VM is set up using the ZFS file system but otherwise you can use the default configuration options.

Installing runj

Start the VM and directly connect to the console:

$ vm start -f runjvm

All the following commands are executed inside the VM:

$ pkg install git
...
$ git clone https://git.FreeBSD.org/ports.git /usr/ports
$ cd /usr/ports/sysutils/runj && make install clean

Converting a Potluck Image to a runj Jail

We use the the git-nomad v1.0.3 image in this example, which is a jail that is prepared to be run within a nomad environment and therefore contains a /usr/local/bin/cook script (for more details, see the Potluck flavour how-to.)

All the following commands are still executed inside the VM.

Download Image and Convert Into ZFS Dataset

$ curl https://potluck.honeyguide.net/git-nomad/git-nomad-amd64-13_0_1.0.3.xz > gitfs.xz
$ xz -d gitfs.xz
$ cat gitfs | zfs recv -F zroot/git

Prepare for runj

$ mkdir git && cd git

Create config.json with the content below which essentially points to the git filesystem we just created and tells runj to start the cook script:

{
  "ociVersion": "1.0.2-runj-dev",
  "process": {
    "args": [
      "/usr/local/bin/cook"
    ]
  },
  "root": {
    "path": "/zroot/git/m"
  }
}

Note that the pot jails are always located in a .../m subdirectory.

Finally, create the jail in runj from this configuration:

$ runj create git /root/git

Run in runj

Start the jail with

$ runj start git

If everything works, you should see the cook process with a simple ps ax.

This simple example does not yet set any of the parameters exposed by the image and it also does not deal with setting up a network configuration so that services running within the jail can be reached from the outside. Also, re-packaging for deployment via containerd would be an obvious next step.

Nonetheless, it shows that it should not be complicated to use the Potluck image library and the image creation tools and processes it uses in a containerd environment, too.

See Also