Spread the love



“…LinuxKit? A New Beast?

     What problem does it solve for us?..”



In case you missed out Dockercon 2017 and have no idea what is LinuxKit all about, then you have arrived at the right place. For the next 30 minutes of your time, I will be talking about an open source container toolkit which Docker Inc. has recently made to the public & will help you get started with it in very easy and precise way.

What is LinuxKit?

LinuxKit is just like Docker’s other open-source container toolkits such as InfraKit and VPNkit. It is essentially a container-native toolkit that allows organizations to build their own containerized operating systems that are secure, lean, modular and portable. Essentially, it is more of a developer kit than an end-user product.This project is completely open source and  is hosted on GitHub, under an Apache 2 licence.

What problem does it solve?

Last year Docker Inc. started shipping Docker for Mac, Docker for Windows, Docker for Azure & Docker for GCP and that brought a Docker-native experience to these various platforms. One of the common problem which the community faced was non-standard Linux OS running on all those platform.  Esp. Cloud platform do not ship with a standard Linux which brought lots of concerns around portability, security and  incompatibility. This lead Docker Inc. to bundle Linux into the Docker platform to run on all of these places uniformly.

Talking about portability, Docker Inc. has always focused on product which should run anywhere. Hence, they worked with partners like HP, Intel, ARM and Microsoft to ensure that LinuxKit toolkit should flawlessly run on the desktop, server, cloud ARM, x86, virtual environment and on bare metal. LinuxKit was built with an intention of  an optimized tooling for portability which can accommodate a new architecture, a new system in very easier way.

What does LinuxKit hold?

LinuxKit includes the tooling to allow building custom Linux subsystems that only include exactly the components the runtime platform requires. All system services are containers that can be replaced, and everything that is not required can be removed.The toolkit works with Docker’s containerd. All components can be substituted with ones that match specific needs.You can optimize LinuxKit images for specific hardware platforms and host operating systems with just the drivers and other dependencies you need, and nothing more, rather than use a full-fat generic base. The toolkit basically tries to help you create your own slimline containerized operating system as painlessly as possible. The size of a LinuxKit image is in MBs ( around 35-50MB).


The above shown is YAML file which specifies a kernel and base init system, a set of containers that are built into the generated image and started at boot time. It also specifies what formats to output(shown at the last line), such as bootable ISOs and images for various platforms. Interestingly, system services are sandboxed in containers, with only the privileges they need. The configuration is designed for the container use case. The whole system is built to be used as immutable infrastructure, so it can be built and tested in your CI pipeline, deployed, and new versions are redeployed when you wish to upgrade. To know more about YAML specification, check this out.

What tool does LinuxKit uses?

There are two basic tools which LinuxKit uses – Linuxkit & Moby.


In short, the moby tool converts the yaml specification into one or more bootable images.

Let us get started with LinuxKit to understand how it builds customized ISO images and run uniformly across various platform. Under this blog post, I have chosen Google Cloud Platform. We will build LinuxKit based customized ISO image locally on my Macbook Air and push it to Google Cloud Platform to run as VM instance. I will be using forked linuxkit repository which I have built around and runs Docker container(ex. running Portainer docker container) inside VM instance too.


  1. Install LinuxKit & Moby tool on macOS
  2. Building a LinuxKit ISO Image with Moby 
  3. Create a bucket under Google Cloud Platform
  4. Upload the LinuxKit ISO image to a GCP bucket using LinuxKit tool
  5. Initiate the GCP instance from the LinuxKit ISO image placed under GCP bucket
  6. Verifying Docker running inside LinuxKitOS 
  7. Running Portainer as Docker container



– Install Google Cloud SDK on your macOS system through this link. You will need to verify your google account using the below command:

$gcloud auth login

– Ensure that the build essential tools like make are perfectly working

– Ensure that GO packages are installed on macOS..


  1. Clone the repository:


sudo git clone https://github.com/ajeetraina/linuxkit


2.  Change directory to linuxkit and run make which builds “moby” and “linuxkit” for us

cd linuxkit && sudo make


3.  Verify that these tools are built and placed under /bin:

cd bin/
moby         linuxkit

4.  Copy these tools into system PATH:

sudo cp bin/* /usr/local/bin/

5. Use moby tool to build the customized ISO image:


cd examples/
sudo moby build gcpwithdocker.yml




[Update: 6/21/2017 – With the latest release of LinuxKit, Output section is no longer allowed inside YAML file. It means that whenever you use moby build command to build an image, specify -output gcp to build an image in a format that GCP will understand. For example:

moby build -output gcp example/gcpwithdocker.yml

This will create a local gcpwithdocker.img.tar.gz compressed image file.]


6.  Create a GCE bucket “mygcp” under your Google Cloud Platform:


7. Run  linuxkit push command  to push it to GCP:


sudo linuxkit push gcp -project synthetic-diode-161714 -bucket mygcp gcpwithdocker.img.tar.gz



[Note: “synthetic-diode-161714” is my GCP project name and “mygcp” is the bucket name which I created in earlier step. Please input as per your environment.]

Please note that you might need to enable Google Cloud API using this link in case you encounter “unable to connect GCP”  error. 

8.  You can execute the image you created and this will should show up under VM instance on Google  Cloud Platform:



This will build up a LinuxKit OS which you can verify below:


You can also verify if this brings up VM instance on GCP platform:


9. You can use runc command to list out all the services which were defined under gcpwithdocker.yml file:


10. As shown above, one of the service which I am interested is called “docker”. You can use the below command to enter into docker service:


runc exec -t docker sh

Wow ! It is running the latest Docker 17.04.0-ce version.

11.  Let us try to run Portainer application and check if it works good.


You can verify the IP address running ifconfig for that specific container which in my case is


Now this is what I call ” a coolest stuff on earth”. Linuxkit allows you to build your own secure, modular, portable, lean and mean containerized OS and that too in just minutes. I am currently exploring LinuxKit in terms of bare metal OS and will share it under my next blog post.

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

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

Spread the love

Ajeet Raina

My name is Ajeet Singh Raina and I am an author of this blogging site. I am a Docker Captain, ARM Innovator & Docker Bangalore Community Leader. I bagged 2 special awards last year(2019): Firstly, “The Tip of Captain’s Hat Award” at Dockercon 2019, San Francisco, and secondly, “2019 Docker Community Award“. I run Collabnix Community Slack with over 5300+ audience . I have built popular GITHUB repositories like DockerLabs, KubeLabs, Kubetools, RedisPlanet Terraform etc. with the support of Collabnix Community. Currently working as Developer Relations Manager at Redis Labs where I help customers and community members adopt Redis. With over 12,000+ followers over LinkedIn & close to 5100+ twitter followers, I like sharing Docker and Kubernetes related content . You can follow me on Twitter(@ajeetsraina) & GitHub(@ajeetraina)


Nicolas · 6th May 2017 at 3:48 am


Thanks for article. Just for information, it is not **gcloud auth login2** but **gcloud auth login**, except error…

I cannot connect to GCE to push my image.
*linuxkit push gcp -project nicolas -bucket mygcp13100 gcpwithdocker.img.tar.gz*
Give me always : FATA[0000] Unable to connect to GCP

How to check it ? Thanks a lot.
Best regards

    ajeetraina · 16th May 2017 at 1:18 pm


    Were you able to fix this issue? I believe it has something to do with network(either slow or firewall). I did face that error while I was trying it first time but after few minutes it was working for me. Can you try it from any of Ubuntu instance running on GCP instead?

ajeetraina · 7th May 2017 at 12:59 pm

Thanks. It was just a typo.
I tried on my macOS and it just worked fine for me multiple times. I have updated the github.
Have a look.

Bob Ben · 21st June 2017 at 3:59 pm

Hi, Thanks for your article on Linux kit.

following the steps on this article be getting an error with the build step.

>:examples bob$ sudo moby build gcpwithdocker.yml
The configuration file is invalid:
– outputs: Additional property outputs is not allowed
FATA[0000] Invalid config: invalid configuration file

    ajeetraina · 21st June 2017 at 8:05 pm

    Hello Bob,

    Thanks for reminding me. There has been recent change under LinuxKit YAML file. Output is not allowed inside YAML File but one has to specify directly over the commandline. For Example:

    $moby build -output gcp example/gcpwithdocker.yml

    I will update it in the blog soon.


giabar · 7th July 2017 at 1:29 pm

I’m trying to play with linuxkit but I’m not able to set the output format.
I always receive this error:

The configuration file is invalid:
– outputs: Additional property outputs is not allowed

    ajeetraina · 7th July 2017 at 7:23 pm

    There has been recent change in YAML specification. Now you don’t have to pass output parameter inside YAML file. It should be passed as with moby build -o command.

Test-Drive LinuxKit OS on Oracle VirtualBox running on macOS Sierra – Collabnix · 1st May 2017 at 4:40 pm

[…] my last blog post, I showed how to get started with LinuxKit for Google Cloud Platform. LinuxKit is […]

Running LinuxKit on AWS Platform made easy – Collabnix · 20th June 2017 at 11:48 pm

[…] after DockerCon 2017, I wrote a blog post on how to get started with LinuxKit for Google Cloud Platform. Since then I have been closely […]

Leave a Reply

Your email address will not be published. Required fields are marked *