clearlinux/rkt

Fork 0

mirror of https://github.com/clearlinux/rkt.git synced 2026-09-01 11:26:05 +00:00

Files

T

Rob Szumski 43a29fd811 docs: fix --volume flags

2015-02-11 15:33:05 -08:00

9.9 KiB

Raw Permalink Blame History

Rocket Commands

Work in progress. Please contribute if you see an area that needs more detail.

Downloading Images (ACIs)

Rocket runs containers packaged as Application Container Images (ACI) an open-source specification. ACIs consist of the root filesystem of the container, a manifest and an optional signature.

ACIs are named with a URL-like structure. This naming scheme allows for a decentralized discovery of ACIs, related signatures and public keys. Rocket uses these hints to execute meta discovery.

rkt trust

Before executing a remotely fetched container, Rocket will verify it based on attached signatures generated by the ACI creator.

Before this can happen, Rocket needs to know which creators you trust, and therefore are trusted to run containers on your machine. The identity of each ACI creator is established with a public key, which is placed in Rocket's key store on disk.

When adding a trusted key, a prefix can scope the level of established trust to a subset of containers. A few examples:

$rkt trust --prefix storage.coreos.com

$rkt trust --prefix coreos.com/etcd

To trust a key for an entire root domain, you must use the --root flag.

$rkt trust --root coreos.com

Trust a Key Using Meta Discovery

The easiest way to trust a key is through meta discovery. Rocket will find and download a public key that the creator has published on their website. This process is detailed in the Application Container specification. The TL;DR is Rocket will find a meta tag that looks like:

<meta name="ac-discovery-pubkeys" content="coreos.com/etcd https://coreos.com/dist/pubkeys/aci-pubkeys.gpg">

And use it to download the public key and present it to you for approval:

$ 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"

If Rocket can't find a key using meta discovery, an error will be printed:

$ rkt trust --prefix coreos.com                     
Error determining key location: --prefix meta discovery error: found no ACI meta tags

Trust a Key From Specific Location

If you know where a public key is located, you can request it directly from disk or via HTTPS:

$ sudo ./rkt trust --prefix coreos.com/etcd https://coreos.com/dist/pubkeys/aci-pubkeys.gpg
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"

Pre-Populating Trusted Keys on Disk

Trusted public keys can be pre-populated by placing them in the appropriate location on disk for the desired prefix.

Depends on https://github.com/coreos/rocket/issues/500

$ ls -l /etc/rkt/trustedkeys/
[insert example of root key vs prefixed key]

rkt fetch

Rocket uses HTTPS to locate and download remote ACIs and their attached signatures. If the ACI exists locally, it won't be re-downloaded.

Fetch with Meta Discovery

The easiest way to fetch an ACI is through meta discovery. Rocket will find and download the ACI and signature from a location that the creator has published on their website. This process is detailed in the Application Container specification.

If you have previously trusted the container creator, it will be downloaded and verified:

$ 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.25 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

If you haven't trusted the creator, it will be downloaded but not verified:

$ 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.25 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: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
sha512-fa1cb92dc276b0f9bedf87981e61ecde

Fetch from Specific Location

If you already know where an image is stored, you can fetch it directly:

$ rkt fetch https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
Downloading aci: [=======================================      ] 3.25 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: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci
sha512-fa1cb92dc276b0f9bedf87981e61ecde

Running Containers

Rocket can run ACIs based on name, hash, local file on disk or URL. If an ACI hasn't been cached on disk, Rocket will attempt to find and download it.

rkt run

# Run by name
$ sudo rkt run coreos.com/etcd:v2.0.0

# Run by hash
$ sudo rkt run sha512-fa1cb92dc276b0f9bedf87981e61ecde

# Run by ACI address
$ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.0-linux-amd64.aci

TODO: Exit codes TODO: Environment variables TODO: Logging

Disable Signature Verification

If desired, -insecure-skip-verify can be used to disable this security check:

$ sudo rkt -insecure-skip-verify run 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
rkt: warning: signature verification has been disabled
...

Mount Volumes into a Container

Volumes are defined in each ACI and are referenced by name. Volumes can be exposed from the host into the container (host) or initialized as empty storage to be accessed locally within the container (empty pending rkt #378). Each volume can be selectively mounted into each application at differing mount points or not mounted into specific apps at all.

For host volumes, the --volume flag allows you to specify each mount, its type and the location on the host. The volume is then mounted into each app running to the container based on information defined in the ACI manifest.

For example, let's say we want to read data from the host directory /opt/tenant1/work to power a MapReduce-syle worker. We'll call this volume work. Our ACI manifest specifies that work is mounted read-only from the host, and is mounted at work and backup into two apps but not into the third. Here's an appreviated version of the ACI manifest:

"apps": [{
  "app": "example.com/reduce-worker-1.0.0",
  "mounts": [
       {"volume": "work", "mountPoint": "work"}
  ]
  ...
},
{
  "app": "example.com/worker-backup-1.0.0",
  "mounts": [
       {"volume": "work", "mountPoint": "backup"}
  ]
  ...
},
{
  "app": "example.com/reduce-worker-register-1.0.0",
  ...
}],
"volumes": [
  {
    "name": "work",
    "kind": "host",
    "source": "/opt/tenant1/work",
    "readOnly": true
  }
],
...

The corresponding rkt run looks like:

sudo ./rkt run --volume work,kind=host,source=/opt/tenant1/work \
  example.com/reduce-worker-1.0.0 \
  example.com/worker-backup-1.0.0 \
  example.com/reduce-worker-register-1.0.0