Repository files navigation

LinuxKit, a toolkit for building custom minimal, immutable Linux distributions.

• Secure defaults without compromising usability
• Everything is replaceable and customisable
• Immutable infrastructure applied to building Linux distributions
• Completely stateless, but persistent storage can be attached
• Easy tooling, with easy iteration
• Built with containers, for running containers
• Designed to createreproducible builds [WIP]
• Designed for building and running clustered applications, including but not limited to container orchestration such as Docker or Kubernetes
• Designed from the experience of building Docker Editions, but redesigned as a general-purpose toolkit
• Designed to be managed by external tooling, such asInfrakit (renamed todeploykit which has been archived in 2019) or similar tools
• Includes a set of longer-term collaborative projects in various stages of development to innovate on kernel and userspace changes, particularly around security

LinuxKit currently supports thex86_64,arm64, ands390x architectures on a variety of platforms, both as virtual machines and baremetal (seebelow for details).

• LinuxKit kubernetes aims to build minimal and immutable Kubernetes images. (previouslyprojects/kubernetes in this repository).
• LinuxKit LCOW LinuxKit images and utilities for Microsoft's Linux Containers on Windows.
• linux A copy of the Linux stable tree with branches LinuxKit kernels.
• virtsock Ago library and test utilities forvirtio and Hyper-V sockets.
• rtf A regression test framework used for the LinuxKit CI tests (and other projects).
• homebrew Homebrew packages for thelinuxkit tool.

LinuxKit uses thelinuxkit tool for building, pushing and running VM images.

Simple build instructions: usemake to build. This will build the tool inbin/. Add thisto yourPATH or copy it to somewhere in yourPATH egsudo cp bin/* /usr/local/bin/. Or you can usesudo make install.

If you already havego installed you can usego install github.com/linuxkit/linuxkit/src/cmd/linuxkit@latest to install thelinuxkit tool.

On MacOS there is abrew tap available. Detailed instructions are atlinuxkit/homebrew-linuxkit,the short summary is

brew tap linuxkit/linuxkitbrew install --HEAD linuxkit

Build requirements from source using a container

• GNUmake
• Docker
• optionallyqemu

For a local build usingmake local

• go
• make
• go get -u golang.org/x/lint/golint
• go get -u github.com/gordonklaus/ineffassign

Once you have built the tool, use

linuxkit build linuxkit.yml

to build the example configuration. You can also specify different output formats, eglinuxkit build -format raw-bios linuxkit.yml tooutput a raw BIOS bootable disk image, orlinuxkit build -format iso-efi linuxkit.yml to output an EFI bootable ISO image. Seelinuxkit build -help for more information.

You can uselinuxkit run <name> orlinuxkit run <name>.<format> toexecute the image you created withlinuxkit build <name>.yml. Thiswill use a suitable backend for your platform or you can choose one,for example VMWare. Seelinuxkit run --help.

Currently supported platforms are:

• Local hypervisors
  • Virtualization.Framework (macOS)[x86_64, arm64]
  • HyperKit (macOS)[x86_64]
  • Hyper-V (Windows)[x86_64]
  • qemu (macOS, Linux, Windows)[x86_64, arm64, s390x]
  • VMware (macOS, Windows)[x86_64]
• Cloud based platforms:
  • Amazon Web Services[x86_64]
  • Google Cloud[x86_64]
  • Microsoft Azure[x86_64]
  • OpenStack[x86_64]
  • Scaleway[x86_64]
• Baremetal:
  • packet.net[x86_64, arm64]
  • Raspberry Pi Model 3b[arm64]

The test suite usesrtf Toinstall this you should usemake bin/rtf && make install. You willalso need to installexpect on your system as some tests use it.

To run the test suite:

cd testrtf -v run -x

This will run the tests and put the results in a the_results directory!

Run control is handled using labels and with pattern matching.To run add a label you may use:

rtf -v -l slow run -x

To run tests that match the patternlinuxkit.examples you would use the following command:

rtf -v run -x linuxkit.examples

To customise, copy or modify thelinuxkit.yml to your ownfile.yml or use one of theexamples and then runlinuxkit build file.yml togenerate its specified output. You can run the output withlinuxkit run file.

The yaml file specifies a kernel and base init system, a set of containers that are built into the generated image and started at boot time. You can specify the typeof artifact to build eglinuxkit build -format vhd linuxkit.yml.

If you want to build your own packages, see thisdocument.

The yaml format specifies the image to be built:

• kernel specifies a kernel Docker image, containing a kernel and a filesystem tarball, eg containing modules. The example kernels are built fromkernel/
• init is the baseinit process Docker image, which is unpacked as the base system, containinginit,containerd,runc and a few tools. Built frompkg/init/
• onboot are the system containers, executed sequentially in order. They should terminate quickly when done.
• services is the system services, which normally run for the whole time the system is up
• files are additional files to add to the image

For a more detailed overview of the options seeyaml documentation

There is anoverview of the architecture covering how the system works.

There is anoverview of the security considerations and direction covering the security design of the system.

This project was extensively reworked from the code we are shipping in Docker Editions, and the result is not yet production quality. The plan is to return to productionquality during Q3 2017, and rebase the Docker Editions on this open source project during this quarter. We plan to start making stable releases on this timescale.

This is an open project without fixed judgements, open to the community to set the direction. The guiding principles are:

• Security informs design
• Infrastructure as code: immutable, manageable with code
• Sensible, secure, and well-tested defaults
• An open, pluggable platform for diverse use cases
• Easy to use and participate in the project
• Built with containers, for portability and reproducibility
• Run with system containers, for isolation and extensibility
• A base for robust products

There are monthlydevelopment reports summarising the work carried out each month.

We maintain an incomplete list ofadopters. Please open a PR if you are using LinuxKit in production or in your project, or both.

SeeFAQ.

Released under theApache 2.0 license.