LinuxKit
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 create reproducible 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 as Infrakit (renamed to deploykit 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 the x86_64, arm64, and s390x architectures on a variety of platforms, both as virtual machines and baremetal (see below for details).
Subprojects
- LinuxKit kubernetes aims to build minimal and immutable Kubernetes images. (previously
projects/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 A
go library and test utilities for virtio and Hyper-V sockets.
- rtf A regression test framework used for the LinuxKit CI tests (and other projects).
- homebrew Homebrew packages for the
linuxkit tool.
Getting Started
Build the linuxkit tool
LinuxKit uses the linuxkit tool for building, pushing and running VM images.
Simple build instructions: use make to build. This will build the tool in bin/. Add this
to your PATH or copy it to somewhere in your PATH eg sudo cp bin/* /usr/local/bin/. Or you can use sudo make install.
If you already have go installed you can use go install github.com/linuxkit/linuxkit/src/cmd/linuxkit@latest to install the linuxkit tool.
On MacOS there is a brew tap available. Detailed instructions are at linuxkit/homebrew-linuxkit,
the short summary is
brew tap linuxkit/linuxkit
brew install --HEAD linuxkit
Build requirements from source using a container
For a local build using make local
gomakego get -u golang.org/x/lint/golintgo get -u github.com/gordonklaus/ineffassign
Building images
Once you have built the tool, use
linuxkit build linuxkit.yml
to build the example configuration. You can also specify different output formats, eg linuxkit build --format raw-bios linuxkit.yml to
output a raw BIOS bootable disk image, or linuxkit build --format iso-efi linuxkit.yml to output an EFI bootable ISO image. See linuxkit build -help for more information.
Booting and Testing
You can use linuxkit run <name> or linuxkit run <name>.<format> to
execute the image you created with linuxkit build <name>.yml. This
will use a suitable backend for your platform or you can choose one,
for example VMWare. See linuxkit run --help.
Currently supported platforms are:
- Local hypervisors
- Cloud based platforms:
- Baremetal:
Running the Tests
The test suite uses rtf To
install this you should use make bin/rtf && make install. You will
also need to install expect on your system as some tests use it.
To run the test suite:
cd test
rtf -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 pattern linuxkit.examples you would use the following command:
rtf -v run -x linuxkit.examples
Building your own customised image
To customise, copy or modify the linuxkit.yml to your own file.yml or use one of the examples and then run linuxkit build file.yml to
generate its specified output. You can run the output with linuxkit 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 type
of artifact to build eg linuxkit build -format vhd linuxkit.yml.
If you want to build your own packages, see this document.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
