README
¶
Rocket - App Container runtime
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.
Trying out Rocket
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.2.0/rocket-v0.2.0.tar.gz
tar xzvf rocket-v0.2.0.tar.gz
cd rocket-v0.2.0
./rkt help
Keep in mind while running through the examples that right now rkt needs to be run as root for most operations.
Rocket basics
Downloading an App Container Image (ACI)
Rocket uses content addressable storage (CAS) for storing an ACI on disk. In this example, the image is downloaded and added to the CAS.
(Note that since Rocket verifies signatures by default, you will need to first trust the CoreOS public key used to sign the image. Detailed step-by-step for the signing procedure is here.)
[~/rocket-v0.2.0]$ sudo ./rkt fetch https://github.com/coreos/etcd/releases/download/v2.0.0-rc.1/etcd-v2.0.0-rc.1-linux-amd64.aci
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0-rc.1/etcd-v2.0.0-rc.1-linux-amd64.aci
Downloading aci: [=============================== ] 2.49 MB/3.58 MB
Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0-rc.1/etcd-v2.0.0-rc.1-linux-amd64.sig
rkt: signature verified:
CoreOS ACI Builder <release@coreos.com>
sha512-fcdf12587358af6ebe69b5338a05df67
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/fc
/var/lib/rkt/cas/blob/sha512/fc/sha512-fcdf12587358af6ebe69b5338a05df673ab7c95539f4cac09b0ceb4ea9b12339
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-rc.1/etcd-v2.0.0-rc.1-linux-amd64.aci
...
[~]$ $ gzip -dc etcd-v2.0.0-rc.1-linux-amd64.aci > etcd-v2.0.0-rc.1-linux-amd64.tar
[~]$ sha512sum etcd-v2.0.0-rc.1-linux-amd64.tar
fcdf12587358af6ebe69b5338a05df673ab7c95539f4cac09b0ceb4ea9b1233922700bdbafd5b6783e129d3f5e9d17bc7f0a07912b8a0a8c0ff7bf732a3f0acf etcd-v2.0.0-rc.1-linux-amd64.tar
Launching an ACI
An ACI can be run by pointing rkt at either the ACI's hash or URL.
# Example of running via ACI hash
[~/rocket-v0.2.0]$ sudo ./rkt run sha512-fcdf12587358af6ebe69b5338a05df67
...
Press ^] three times to kill container
# Example of running via ACI URL
[~/rocket-v0.2.0]$ sudo ./rkt run https://github.com/coreos/etcd/releases/download/v2.0.0-rc.1/etcd-v2.0.0-rc.1-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 basics
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:
[~/rocket-v0.2.0]$ sudo ./rkt run -volume database:/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 internals
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.
Stage 0
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:
[~/rocket-v0.2.0]$ sudo ./rkt run --volume bind:/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:
containeris the container manifest filestage1is a copy of the stage1 ACI that is safe for read/writestage1/manifestis the manifest of the stage1 ACIstage1/rootfsis the rootfs of the stage1 ACIstage1/rootfs/initis the actual stage1 binary to be executed (this path may vary according to thecoreos.com/rocket/stage1/initAnnotation of the stage1 ACI)stage1/rootfs/opt/stage2are 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.
Stage 1
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.
Stage 2
The final stage is executing the actual application. The responsibilities of the stage2 include:
- Launch the init process described in the Application Manifest
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps
|
|
|
_workspace/src/code.google.com/p/go-uuid/uuid
The uuid package generates and inspects UUIDs.
|
The uuid package generates and inspects UUIDs. |
|
_workspace/src/github.com/appc/spec/aci
Package aci contains various functions for working with App Container Images.
|
Package aci contains various functions for working with App Container Images. |
|
_workspace/src/github.com/appc/spec/actool
Package main contains a tool for building and validating images and manifests that meet the App Container specifications.
|
Package main contains a tool for building and validating images and manifests that meet the App Container specifications. |
|
_workspace/src/github.com/appc/spec/discovery
Package discovery contains an experimental implementation of the Image Discovery section of the appc specification.
|
Package discovery contains an experimental implementation of the Image Discovery section of the appc specification. |
|
_workspace/src/github.com/appc/spec/pkg/tarheader
Package tarheader contains a simple abstraction to accurately create tar.Headers on different operating systems.
|
Package tarheader contains a simple abstraction to accurately create tar.Headers on different operating systems. |
|
_workspace/src/github.com/appc/spec/schema
Package schema provides definitions for the JSON schema of the different manifests in the App Container Specification.
|
Package schema provides definitions for the JSON schema of the different manifests in the App Container Specification. |
|
_workspace/src/github.com/appc/spec/schema/types
Package types contains structs representing the various types in the app container specification.
|
Package types contains structs representing the various types in the app container specification. |
|
_workspace/src/github.com/gorilla/context
Package context stores values shared during a request lifetime.
|
Package context stores values shared during a request lifetime. |
|
_workspace/src/github.com/gorilla/mux
Package gorilla/mux implements a request router and dispatcher.
|
Package gorilla/mux implements a request router and dispatcher. |
|
_workspace/src/github.com/petar/GoLLRB/llrb
A Left-Leaning Red-Black (LLRB) implementation of 2-3 balanced binary search trees, based on the following work: http://www.cs.princeton.edu/~rs/talks/LLRB/08Penn.pdf http://www.cs.princeton.edu/~rs/talks/LLRB/LLRB.pdf http://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java 2-3 trees (and the run-time equivalent 2-3-4 trees) are the de facto standard BST algoritms found in implementations of Python, Java, and other libraries.
|
A Left-Leaning Red-Black (LLRB) implementation of 2-3 balanced binary search trees, based on the following work: http://www.cs.princeton.edu/~rs/talks/LLRB/08Penn.pdf http://www.cs.princeton.edu/~rs/talks/LLRB/LLRB.pdf http://www.cs.princeton.edu/~rs/talks/LLRB/Java/RedBlackBST.java 2-3 trees (and the run-time equivalent 2-3-4 trees) are the de facto standard BST algoritms found in implementations of Python, Java, and other libraries. |
|
_workspace/src/github.com/vishvananda/netlink
Package netlink provides a simple library for netlink.
|
Package netlink provides a simple library for netlink. |
|
_workspace/src/github.com/vishvananda/netlink/nl
Package nl has low level primitives for making Netlink calls.
|
Package nl has low level primitives for making Netlink calls. |
|
_workspace/src/golang.org/x/crypto/cast5
Package cast5 implements CAST5, as defined in RFC 2144.
|
Package cast5 implements CAST5, as defined in RFC 2144. |
|
_workspace/src/golang.org/x/crypto/openpgp
Package openpgp implements high level operations on OpenPGP messages.
|
Package openpgp implements high level operations on OpenPGP messages. |
|
_workspace/src/golang.org/x/crypto/openpgp/armor
Package armor implements OpenPGP ASCII Armor, see RFC 4880.
|
Package armor implements OpenPGP ASCII Armor, see RFC 4880. |
|
_workspace/src/golang.org/x/crypto/openpgp/clearsign
Package clearsign generates and processes OpenPGP, clear-signed data.
|
Package clearsign generates and processes OpenPGP, clear-signed data. |
|
_workspace/src/golang.org/x/crypto/openpgp/elgamal
Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v.
|
Package elgamal implements ElGamal encryption, suitable for OpenPGP, as specified in "A Public-Key Cryptosystem and a Signature Scheme Based on Discrete Logarithms," IEEE Transactions on Information Theory, v. |
|
_workspace/src/golang.org/x/crypto/openpgp/errors
Package errors contains common error types for the OpenPGP packages.
|
Package errors contains common error types for the OpenPGP packages. |
|
_workspace/src/golang.org/x/crypto/openpgp/packet
Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880.
|
Package packet implements parsing and serialization of OpenPGP packets, as specified in RFC 4880. |
|
_workspace/src/golang.org/x/crypto/openpgp/s2k
Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1.
|
Package s2k implements the various OpenPGP string-to-key transforms as specified in RFC 4800 section 3.7.1. |
|
_workspace/src/golang.org/x/net/html
Package html implements an HTML5-compliant tokenizer and parser.
|
Package html implements an HTML5-compliant tokenizer and parser. |
|
_workspace/src/golang.org/x/net/html/atom
Package atom provides integer codes (also known as atoms) for a fixed set of frequently occurring HTML strings: tag names and attribute keys such as "p" and "id".
|
Package atom provides integer codes (also known as atoms) for a fixed set of frequently occurring HTML strings: tag names and attribute keys such as "p" and "id". |
|
_workspace/src/golang.org/x/net/html/charset
Package charset provides common text encodings for HTML documents.
|
Package charset provides common text encodings for HTML documents. |
|
Package cas implements a content-addressable-store on disk.
|
Package cas implements a content-addressable-store on disk. |
|
Package common defines values shared by different parts of rkt (e.g.
|
Package common defines values shared by different parts of rkt (e.g. |
|
pkg
|
|
|
aci
Package aci implements helper functions for working with ACIs
|
Package aci implements helper functions for working with ACIs |
|
keystore
Package keystore implements the ACI keystore.
|
Package keystore implements the ACI keystore. |
|
keystore/keystoretest
Package keystoretest provides utilities for ACI keystore testing.
|
Package keystoretest provides utilities for ACI keystore testing. |
|
lock
Package lock implements simple locking primitives on a directory using flock
|
Package lock implements simple locking primitives on a directory using flock |
|
tar
Package tar contains helper functions for working with tar files
|
Package tar contains helper functions for working with tar files |
|
Package rkt (main) implements the command line interface to rocket
|
Package rkt (main) implements the command line interface to rocket |