rkt Design Proposals

Trying out rkt

This document introduces the basics of getting rkt and running a container with it. For a more in-depth guide to building application containers and running them with rkt, check out the getting started guide.

Installing rkt from a Linux distribution package

Another easy way to run rkt is to install it with your system's package manager, like apt on Debian or dnf on Fedora. Check for your Linux distribution in the distributions list to see if a rkt package is available.

Running rkt in a Vagrant virtual machine

If your operating system isn't Linux, it's easy to run rkt in a Linux virtual machine with Vagrant. The instructions below start a virtual machine with rkt installed and ready to run.

Vagrant on Mac and Windows

For Mac (and other Vagrant) users we have set up a Vagrantfile. Make sure you have Vagrant 1.5.x or greater installed.

First, download the Vagrantfile and start a Linux machine with rkt installed by running vagrant up.

git clone https://github.com/rkt/rkt
cd rkt
vagrant up

Vagrant on Linux

To use Vagrant on a Linux machine, you may want to use libvirt as a VMM instead of VirtualBox. To do so, install the necessary plugins, convert the box, and start the machine using the libvirt provider:

Accessing the Vagrant VM and running rkt

With a subsequent vagrant ssh you will have access to run rkt:

If you are running an outdated version of VirtualBox, it may be that SSH asks for a password. You can find the password for the ubuntu user in ~/.vagrant.d/boxes/ubuntu-VAGRANTSLASH-xenial64/[DATE]/virtualbox/Vagrantfile
under config.ssh.password.

vagrant ssh
rkt --help

Consult the rkt manual for more details:

man rkt

The Vagrant setup also includes bash-completion to assist with rkt subcommands and options.

Container networking on a Vagrant VM

To reach pods from your host, determine the IP address of the Vagrant machine:

The following command starts an nginx container, for simplicity using host networking to make the pod directly accessible on the host's network address and ports. Signature validation isn't supported for Docker registries and images, so --insecure-options=image switches off the signature check:

sudo rkt run --net=host --insecure-options=image docker://nginx

The nginx container is now accessible on the host under http://172.28.128.3.

In order to use containers with the default contained network, a route to the 172.16.28.0/24 container network must be configured from the host through the VM:

In this example, the nginx container was assigned the IP address 172.16.28.2 (the address assigned on your system may vary). Since we established a route from the host to the 172.16.28.0/24 pod network the nginx container is now accessible on the host under http://172.16.28.2.

Success! The rest of the guide can now be followed normally.

Configuring a rkt host

Once rkt is present on a machine, some optional configuration steps can make it easier to operate.

SELinux

rkt supports running under SELinux mandatory access controls, but an SELinux policy needs to be tailored to your distribution. New rkt users on distributions other than Container Linux should temporarily disable SELinux to make it easier to get started. If you can help package rkt for your distro, including SELinux policy support, please lend a hand!

Optional: Set up privilege separation

To allow different subcommands to use the least necessary privilege, rkt recognizes a rkt group that has read-write access to the rkt data directory. This allows rkt fetch, which downloads and verifies images, to run as an unprivileged user who is a member of the rkt group.

If you skip this section, you can still run sudo rkt fetch instead, but setting up a rkt group is a good basic security practice for production use. The rkt repo includes a setup-data-dir.sh script that can help set up the appropriate permissions for unprivileged execution of subcommands that manipulate the local store, but not the execution environment:

Trust the signing key to validate unprivileged fetches

Trust the signing key for etcd images. This step must be run as root because access to the keystore is restricted from even the rkt group:

sudo ./rkt trust --prefix coreos.com/etcd

Fetch an image as an unprivileged member of the rkt group

Test this out by retrieving an etcd image using a non-root user in the rkt group. Make sure your shell is restarted to enable the rkt group for your user, or
just run newgrp rkt to enable it and continue in the same session.

Now fetch the etcd image as an unprivileged user:

./rkt fetch coreos.com/etcd:v3.1.7

Success! Now rkt can fetch and download images as an unprivileged user.

rkt basics

Building an App Container Image

rkt's native image format is the App Container Image (ACI), defined in the App Container spec. The acbuild tool is a simple way to get started building ACIs. The appc build repository has resources for building ACIs from a number of popular applications.

Downloading an ACI

rkt uses content addressable storage (CAS) to store an ACI on disk. In this example, an image is downloaded and added to the CAS. Downloading an image before running it is not strictly necessary – if an image is not present in the store, rkt will attempt to retrieve it – but it illustrates how rkt works.

Downloading images from private registries

Downloading container images from a private registry usually involves passing usernames and passwords or other kinds of credentials to the server. rkt supports different authentication regimes with configuration files. The configuration documentation describes the file format and gives examples of setting up authentication with HTTP basic auth, OAuth bearer tokens, and other methods.

The image in the local store

For the curious, it is possible to list the hash-identified files written to disk in rkt's CAS:

Running an ACI with rkt

After it has been retrieved and stored locally, an ACI can be run by pointing rkt run at either the original image reference (in this case, coreos.com/etcd:v3.1.7), the ACI hash, or the full URL of the ACI. Therefore the following three examples are equivalent:

Running the container by ACI name and version

$ sudo rkt run coreos.com/etcd:v3.1.7
...
Press ^] three times to kill container

Running the container by ACI URL

When given an ACI URL, rkt will do the appropriate ETag checking to fetch the latest version of the container image.

Exiting rkt pods

As shown above, repeating the ^] escape character three times kills the pod and detaches from its console to return to the user's shell.

The escape character ^] is generated by Ctrl-] on a US keyboard. The required key combination will differ on other keyboard layouts. For example, the Swedish keyboard layout uses Ctrl-å on OS X, or Ctrl-^ on Windows, to generate the ^] escape character.