Why Infrakit & LinuxKit are better together for Building Immutable Infrastructure?

Yet Another Problem Statement(YAPS)…

Let us accept the fact – “Managing Docker on different Infrastructure is still difficult and not portable”. While working on Docker for Mac, AWS, GCP & Azure, Docker Team realized the need for a standard way to create and manage infrastructure state that was portable across any type of infrastructure, from different cloud providers to on-prem. One serious challenge is that each vendor has differentiated IP invested in how they handle certain aspects of their cloud infrastructure. It is not enough to just provision n-number of servers;what IT ops teams need is a simple and consistent way to declare the number of servers, what size they should be, and what sort of base software configuration is required. Also, in the case of server failures (especially unplanned), that sudden change needs to be reconciled against the desired state to ensure that any required servers are re-provisioned with the necessary configuration. Docker Team introduced and open sourced “InfraKit” last year to solve these problems and to provide the ability to create a self healing infrastructure for distributed systems.

Screen Shot 2017-06-11 at 5.05.12 PM


InfraKit is basically a toolkit for infrastructure orchestration. With an emphasis on immutable infrastructure, it breaks down infrastructure automation and management processes into small, pluggable components. These components work together to actively ensure the infrastructure state matches the user’s specifications. InfraKit therefore provides infrastructure support for higher-level container orchestration systems and can make your infrastructure self-managing and self-healing.

Why the Integration of LinuxKit with Infrakit now??

LinuxKit is gaining momentum in terms of  a toolkit for building custom minimal, immutable Linux distributions. Integration of Infrakit with LinuxKit will help users  to build and deploy custom OS images to a variety of targets – from a single vm instance on the mac (via xhyve / hyperkit, no virtualbox) to a cluster of them, as well as booting a remote ARM host on Packet.net from the local laptop via a ngrok tunnel.

Under this blog post, I will show you how does InfraKit and LinuxKit work together to build immutable infrastructure. I want to test drive these toolkits on my macOS Sierra 10.12.3 system.

Installing Homebrew

/usr/bin/ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)”

Installing WGET

brew install wget

Installing Infrakit:

sudo wget -qO- https://docker.github.io/infrakit/install | sh

Copy the file to your path:

sudo cp ./infrakit /usr/local/bin/

Infrakit is cross compiled and installed on your system. Let us try to see what playbook are available as of now.

Screen Shot 2017-06-12 at 2.04.28 AM


Adding INFRAKIT_HOME variable:

bash-3.2$ source ./.bash_profile

bash-3.2$ echo $INFRAKIT_HOME



Adding LinuxKit Playbook

By default, there is no playbook available . Let us try to install LinuxKit and see how InfraKit integrate with LinuxKit.

Create a directory called testproj. 

mkdir testproj
cd testproj

Add the LinuxKit Playbook:

 infrakit playbook add linuxkit https://docker.github.io/infrakit/playbooks/linuxkit/index.yml

Verifying the LinuxKit Playbook

sudo infrakit playbook ls
PLAYBOOK                      URL                           
linuxkit                      https://docker.github.io/infrakit/playbooks/linuxkit/index.yml

Screen Shot 2017-06-12 at 2.02.57 AM


Run the below command to see what options are available under LinuxKit playbook:

infrakit playbook linuxkit

Screen Shot 2017-06-12 at 2.05.51 AM


Installing HyperKit Plugin on your Mac

infrakit playbook linuxkit install-hyperkit


Screen Shot 2017-06-12 at 2.01.54 AM

This command installs HyperKit plugins and add it under /usr/local/bin directory automatically.

Under the testproj directory, you will now see infrakit-instance-hyperkit gets created:

testproj$ ls
docker4mac infrakit-instance-hyperkit

Installing Moby Build Tool  to build custom OS images

infrakit playbook linuxkit install-moby

Screen Shot 2017-06-12 at 1.56.10 AM

Once it gets completed, you will see the options to build OS images:

Screen Shot 2017-06-11 at 7.50.40 AM

Now the software has been installed. The Playbook has command to start everything.

Starting the LinuxKit 

sudo infrakit playbook linuxkit start

Screen Shot 2017-06-12 at 1.59.23 AM

Ensure that you type “yes” for ‘Start HYPERKIT plugin’ while running the above command.

By now, the Infrakit command line interface will show additional options:

infrakit -h
Infrakit command line interface
infrakit [command]
Available Commands:
event Access event exposed by infrakit plugins
event-time Access plugin event-time which implements Metadata/0.1.0
event-time/time Access plugin event-time/time which implements Metadata/0.1.0
event-time/timer Access plugin event-time/timer which implements Event/0.1.0
flavor-vanilla Access plugin flavor-vanilla which implements Flavor/0.1.0
group Access plugin group which implements Group/0.1.0,Manager/0.1.0,Metadata/0.1.0,Updatable/0.1.0
group-stateless Access plugin group-stateless which implements Group/0.1.0,Metadata/0.1.0
instance-hyperkit Access plugin instance-hyperkit which implements Instance/0.5.0,Metadata/0.1.0
manager Access the manager
metadata Access metadata exposed by infrakit plugins
playbook Manage playbooks
plugin Manage plugins
remote Manage remotes
template Render an infrakit template at given url. If url is ‘-‘, read from stdin
util Utilities
version Print build version information
x Experimental features

As you see above, CLI is contextual. It basically discovers the hyperkit plugin running and generates a new command for you to access it


In case hyperkit plugin is not turning up, you can kill the old hyperkit instance process and re-start it.

Screen Shot 2017-06-13 at 9.19.10 AM

Verify if the hyperkit plugin is up and running

Screen Shot 2017-06-12 at 1.52.27 AM

In case you want to run HyperKit, there is recommended command for it.

bash-3.2$ infrakit playbook linuxkit run-hyperkit
Start HYPERKIT plugin? [no]: yes
Starting HYPERKIT plugin.  This must be running on the Mac as a daemon and not as a container
This plugin is listening at localhost:24865

By now, we have everything ready for our LinuxKit SSH playbook

LinuxKit SSHD Example:

Now let me show you how to build a LinuxKit image containing just a simple sshd.The file `sshd.yml` defines the components inside the image.  Instead of a standard LinuxKit image yml, it is actually an InfraKit template that is rendered before the moby tool is invoked to build the actual OS image.

sudo infrakit playbook linuxkit demo-sshd

This will show up the detailed information on its usage on your terminal:


Screen Shot 2017-06-11 at 8.13.58 AM

Screen Shot 2017-06-11 at 8.14.51 AM

Screen Shot 2017-06-11 at 8.16.07 AM

Let us first build the “SSHD” YAML file using the below command:

sudo infrakit playbook linuxkit demo-sshd build-image
Verifying the SSH outputs:
Looking into sshd.yml content:
The below content shows us that SSH service has been right created:
The command `build-image` will collect user input such as the public key location and use that to generate the final input to `moby`.
Open up a new terminal to watch our first Hyperkit instance:
watch -d infrakit instance-hyperkit describe

Running the SSH Instance

Using the `hyperkit` subcommand (does not require billing accounts / signup on providers),you can create a single or a cluster of instances after you run the `build-image`.

The command `… hyperkit run-instance` will use hyperkit plugin to create a single guest vm that boots from the image you built with `build-image`.

infrakit playbook linuxkit demo-sshd hyerpkit run-instance

This command brings up the LinuxKitOS instance. 

Now you can run the below command to enter into SH shell

docker run --rm -ti -v ~/.ssh:/root/.ssh  infrakit/ssh /bin/sh

[ A Special Thanks to David Chung, Docker Team for assisting me understand LinuxKit Playbook thoroughly.]

In the future blog post, I will show you how LinuxKit + Infrakit + GCP works together.

Did you find this blog helpful?  Feel free to share your experience. Get in touch @ajeetsraina

If you are looking out for contribution/discussion, join me at Docker Community Slack Channel.

Know more what’s happening with Infrakit project activities clicking on this link.