Release early, release often: Rocket is currently a prototype and we are seeking your feedback via issues and pull requests

Rocket is a CLI for running App Containers. The goal of rocket is to be composable, secure, and fast.

Read more about Rocket in the launch announcement.

rkt is currently supported on amd64 Linux. We recommend booting up a fresh virtual machine to test out rocket.

To install the rkt binary, grab the release directly from GitHub:

wget https://github.com/coreos/rocket/releases/download/v0.3.1/rocket-v0.3.1.tar.gz
tar xzvf rocket-v0.3.1.tar.gz
cd rocket-v0.3.1
./rkt help

Keep in mind while running through the examples that right now rkt needs to be run as root for most operations.

Rocket uses content addressable storage (CAS) for storing an ACI on disk. In this example, the image is downloaded and added to the CAS.

Since Rocket verifies signatures by default, you will need to first trust the CoreOS public key used to sign the image:

$ sudo rkt trust --prefix coreos.com/etcd
Prefix: "coreos.com/etcd"
Key: "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg"
GPG key fingerprint is: 8B86 DE38 890D DB72 9186  7B02 5210 BD88 8818 2190
  CoreOS ACI Builder <release@coreos.com>
Are you sure you want to trust this key (yes/no)? yes
Trusting "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" for prefix "coreos.com/etcd".
Added key for prefix "coreos.com/etcd" at "/etc/rkt/trustedkeys/prefix.d/coreos.com/etcd/8b86de38890ddb7291867b025210bd8888182190"

A detailed step-by-step for the signing procedure is here.

Now that we've trusted the CoreOS public key, we can fetch the ACI:

$ sudo rkt fetch coreos.com/etcd:v2.0.0
rkt: searching for app image coreos.com/etcd:v2.0.0
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
Downloading aci: [==========================================   ] 3.47 MB/3.7 MB
Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.sig
rkt: signature verified: 
  CoreOS ACI Builder <release@coreos.com>
sha512-fa1cb92dc276b0f9bedf87981e61ecde

These files are now written to disk:

[~]$ find /var/lib/rkt/cas/blob/
/var/lib/rkt/cas/blob/
/var/lib/rkt/cas/blob/sha512
/var/lib/rkt/cas/blob/sha512/fa
/var/lib/rkt/cas/blob/sha512/fa/sha512-fa1cb92dc276b0f9bedf87981e61ecde93cc16432d2441f23aa006a42bb873df

Per the App Container Specification, the SHA-512 hash is of the tarball and can be reproduced with other tools:

$ wget https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
...
$ gzip -dc etcd-v2.0.0-linux-amd64.aci > etcd-v2.0.0-linux-amd64.tar
$ sha512sum etcd-v2.0.0-linux-amd64.tar
fa1cb92dc276b0f9bedf87981e61ecde93cc16432d2441f23aa006a42bb873dfc67480dafb0dfb33b91fd848e138268f71e1f32b55e197cdc2d874ae8da01bbe  etcd-v2.0.0-linux-amd64.tar

An ACI can be run by pointing rkt at either the ACI's hash or URL.

# Example of running via ACI hash
$ sudo rkt run sha512-fa1cb92dc276b0f9bedf87981e61ecde
...
Press ^] three times to kill container

# Example of running via ACI URL
$ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
...
Press ^] three times to kill container

rkt will do the appropriate ETag checking on the URL to make sure it has the most up to date version of the image.

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 and Ctrl-^ on Windows to generate the ^] escape character.

App Container is a specification of an image format, runtime, and discovery protocol for running a container. We anticipate app container will be adopted by other runtimes outside of Rocket itself. Read more about it here.

To validate the rkt with the App Container validation ACIs run:

$ sudo ./rkt run --volume database,kind=host,source=/tmp \
	https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-main.aci \
	https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-sidekick.aci

Rocket is designed to be modular and pluggable by default. To do this we have a concept of "stages" of execution of the container.

Execution with Rocket is divided into a number of distinct stages. The motivation for this is to separate the concerns of initial filesystem setup, execution environment, and finally the execution of the apps themselves.

The first step of the process, stage 0, is the actual rkt binary itself. This binary is in charge of doing a number of initial preparatory tasks:

• Fetching the specified ACIs, including the stage 1 ACI of --stage1-image if specified.
• Generating a Container UUID
• Generating a Container Runtime Manifest
• Creating a filesystem for the container
• Setting up stage 1 and stage 2 directories in the filesystem
• Unpacking the stage 1 ACI into the container filesystem
• Unpacking the ACIs and copying each app into the stage2 directories

Given a run command such as:

$ sudo ./rkt run --volume data,kind=host,source=/opt/tenant1/database \
	sha512-8a30f14877cd8065939e3912542a17d1a5fd9b4c \
	sha512-abcd29837d89389s9d0898ds908ds890df890908

a container manifest compliant with the ACE spec will be generated, and the filesystem created by stage0 should be:

/container
/stage1
/stage1/manifest
/stage1/rootfs/init
/stage1/rootfs/opt
/stage1/rootfs/opt/stage2/sha512-648db489d57363b29f1597d4312b2129
/stage1/rootfs/opt/stage2/sha512-0c45e8c0ab2b3cdb9ec6649073d5c6c4

where:

• container is the container manifest file
• stage1 is a copy of the stage1 ACI that is safe for read/write
• stage1/manifest is the manifest of the stage1 ACI
• stage1/rootfs is the rootfs of the stage1 ACI
• stage1/rootfs/init is the actual stage1 binary to be executed (this path may vary according to the coreos.com/rocket/stage1/run Annotation of the stage1 ACI)
• stage1/rootfs/opt/stage2 are copies of the unpacked ACIs

At this point the stage0 execs /stage1/rootfs/init with the current working directory set to the root of the new filesystem.

The next stage is a binary that the user trusts to set up cgroups, execute processes, and other operations as root. This stage has the responsibility to take the execution group filesystem that was created by stage 0 and create the necessary cgroups, namespaces and mounts to launch the execution group:

• Generate systemd unit files from the Application and Container Manifests (containing, respectively, the exec specifications of each container and the ordering given by the user)
• Set up any external volumes (undefined at this point)
• nspawn attaching to the bridge and launch the execution group systemd
• Launch the root systemd
• Have the root systemd

This process is slightly different for the qemu-kvm stage1 but a similar workflow starting at exec()'ing kvm instead of an nspawn.

The final stage is executing the actual application. The responsibilities of the stage2 include:

• Launch the init process described in the Application Manifest