clearlinux/rkt

Fork 0

mirror of https://github.com/clearlinux/rkt.git synced 2026-08-18 21:16:13 +00:00

Files

T

Jonathan Boulle 1268ff8dae docs: fix host volume example

2015-05-07 13:25:39 -07:00

14 KiB

Raw Permalink Blame History

rkt Commands

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

Downloading Images (ACIs)

rkt runs applications packaged as Application Container Images (ACI) an open-source specification. ACIs consist of the root filesystem of the application 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. rkt uses these hints to execute meta discovery.

rkt trust

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

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

When adding a trusted key, a prefix can scope the level of established trust to a subset of images. 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. rkt 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 rkt 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 rkt 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/rkt/issues/500

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

rkt fetch

rkt 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. rkt 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 image 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

Fetch from a Docker registry

If you want to run an existing Docker image, you can fetch from a Docker registry. rkt will download and convert the image to ACI.

$ rkt -insecure-skip-verify fetch docker://busybox
rkt: fetching image from docker://busybox
rkt: warning: signature verification has been disabled
Downloading layer: 4986bf8c15363d1c5d15512d5266f8777bfba4974ac56e3270e7760f6f0a8125
Downloading layer: ea13149945cb6b1e746bf28032f02e9b5a793523481a0a18645fc77ad53c4ea2
Downloading layer: df7546f9f060a2268024c8a230d8639878585defcc1bc6f79d2728a13957871b
Downloading layer: 511136ea3c5a64f264b78b5433614aec563103b4d4702f3ba7d4d2698e22c158
sha512-c4010045aec65aefa74770ef2bb648d9

Docker images do not support signature verification.

Running Pods

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

rkt run

Image Addressing

Images can be run by either their name, their hash, an explicit transport address, or a Docker registry URL.

# 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

# Run by Docker registry
$ sudo rkt run docker://quay.io/coreos/etcd:v2.0.0

Passing Arguments

To pass additional arguments to images use the pattern of image1 -- [image1 flags] --- image2 -- [image2 flags]. For example:

$ sudo rkt run example.com/worker -- --loglevel verbose --- example.com/syncer -- --interval 30s

Influencing Environment Variables

To inherit all environment variables from the parent use the --inherit-env flag.

To explicitly set individual environment variables use the --set-env flag.

The precedence is as follows with the last item replacing previous environment entries:

Parent environment
App image environment
Explicitly set environment

$ export EXAMPLE_ENV=hello
$ export EXAMPLE_OVERRIDE=under
$ sudo rkt run --inherit-env --set-env FOO=bar --set-env EXAMPLE_OVERRIDE=over example.com/env-printer
EXAMPLE_ENV=hello
FOO=bar
EXAMPLE_OVERRIDE=over

TODO: Exit codes 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 Pod

Volumes are defined in each ACI and are referenced by name. Volumes can be exposed from the host into the pod (host) or initialized as empty storage to be accessed locally within the pod (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.

Mounting Host Volumes

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 pod 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-style worker. We'll call this app example.com/reduce-worker.

We also want this data to be available to a backup application that runs alongside the worker (in the same pod). We'll call this app 'example.com/worker-backup`. The backup application only needs read-only access to the data.

Below we show the abbreviated manifests for the respective applications (recall that the manifest is bundled into the application's ACI):

{
    "acKind": "ImageManifest",
    "name": "example.com/reduce-worker",
    ...
    "app": {
        ...
        "mountPoints": [
            {
                "name": "work",
                "path": "/var/lib/work",
                "readOnly": false
            }
        ],
    ...
}

{
    "acKind": "ImageManifest",
    "name": "example.com/worker-backup",
    ...
    "app": {
        ...
        "mountPoints": [
            {
                "name": "work",
                "path": "/backup",
                "readOnly": true
            }
        ],
    ...
}

In this case, both apps reference a volume they call "work", and expect it to be made available at /var/lib/work and /backup within their respective root filesystems.

Since they reference the volume using an abstract name rather than a specific source path, the same image can be used on a variety of different hosts without being coupled to the host's filesystem layout.

To tie it all together, we use the rkt run command-line to provide them with a volume by this name. Here's what it looks like:

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

Now when the pod is running, the two apps will see the host's /opt/tenant1/work directory made available at their expected locations.

Customize Networking

The default networking configuration for rkt is "host networking". This means that the apps within the pod will share the network stack and the interfaces with the host machine. Since the metadata service uses the pod IP for identity, rkt will not register the pod with the metadata service in this mode.

Private Networking

Another common configuration, "private networking", means the pod will be executed with its own network stack. This is similar to how other container tools work. The metadata service (launched via rkt metadata-service) must be running to use private networking.

By default, rkt private networking will create a loopback device and a veth device. The veth pair creates a point-to-point link between the pod and the host. rkt will allocate an IPv4 /31 (2 IP addresses) out of 172.16.28.0/24 and assign one IP to each end of the veth pair. It will additionally set a route for metadata service (169.254.169.255/32) and default route in the pod namespace. Finally, it will enable IP masquerading on the host to NAT the egress traffic.

sudo ./rkt run --private-net coreos.com/etcd:v2.0.0