From 6cd4ebeb6ea18ef042e94429d5bde3895432604d Mon Sep 17 00:00:00 2001 From: Jonathan Boulle Date: Thu, 17 Dec 2015 12:50:27 +0100 Subject: [PATCH] docs: rework README + add docs for nomad/k8s This breaks apart much of the README into a new "basics" document. The goal is to make the README a little more approachable and do better at highlighting the different options for people to reach out. Also adds initial documents describing integration with Nomad and Kubernetes and links to them appropriately. --- Documentation/trying-out-rkt.md | 136 ++++++++++++++++ Documentation/using-rkt-with-kubernetes.md | 26 +++ Documentation/using-rkt-with-nomad.md | 8 + README.md | 179 +++++---------------- 4 files changed, 206 insertions(+), 143 deletions(-) create mode 100644 Documentation/trying-out-rkt.md create mode 100644 Documentation/using-rkt-with-kubernetes.md create mode 100644 Documentation/using-rkt-with-nomad.md diff --git a/Documentation/trying-out-rkt.md b/Documentation/trying-out-rkt.md new file mode 100644 index 00000000..bf28b08c --- /dev/null +++ b/Documentation/trying-out-rkt.md @@ -0,0 +1,136 @@ +# Trying out rkt + +This guide provides a short introduction to trying out rkt. +For a more in-depth guide of a full end-to-end workflow of building an application and running it using rkt, check out the [getting-started-guide][getting-started-guide.md] + +## Using rkt on Linux + +`rkt` consists of a single self-contained CLI, and is currently supported on amd64 Linux. +A modern kernel is required but there should be no other system dependencies. +We recommend booting up a fresh virtual machine to test out rkt. + +To download the `rkt` binary, simply grab the latest release directly from GitHub: + +``` +wget https://github.com/coreos/rkt/releases/download/v0.14.0/rkt-v0.14.0.tar.gz +tar xzvf rkt-v0.14.0.tar.gz +cd rkt-v0.14.0 +./rkt help +``` + +## Trying out rkt using Vagrant + +For Mac (and other Vagrant) users we have set up a `Vagrantfile`: clone this repository and make sure you have [Vagrant](https://www.vagrantup.com/) 1.5.x or greater installed. +`vagrant up` starts up a Linux box and installs via some scripts `rkt` and `actool`. +With a subsequent `vagrant ssh` you are ready to go: + +``` +git clone https://github.com/coreos/rkt +cd rkt +vagrant up +vagrant ssh +``` + +Keep in mind while running through the examples that right now `rkt` needs to be run as root for most operations. + +## rkt basics + +### Building App Container Images (ACIs) + +rkt's native image format is ACI, defined in the [App Container spec](app-container.md). +To build ACIs, a simple way to get started is by using [`acbuild`](https://github.com/appc/acbuild). +Another good resource is the [appc build repository](https://github.com/appc/build-repository) which has resources for building ACIs from a number of popular projects and languages. +There are also tools for converting [Docker images to ACIs](https://github.com/appc/docker2aci) (although note that rkt can [also run Docker images natively](running-docker-images.md) directly from Docker repositories by using this library internally). + +The example below uses a pre-built ACI for [etcd](https://github.com/coreos/etcd) (this was built by the [build-aci script](https://github.com/coreos/etcd/blob/master/scripts/build-aci)). + +### Downloading an App Container Image (ACI) + +rkt uses content addressable storage (CAS) for storing an ACI on disk. +In this example, the image is downloaded and added to the CAS. +Downloading an image before running it is not strictly necessary (if it is not present, rkt will automatically retrieve it), but useful to illustrate how rkt works. + +Since rkt verifies signatures by default, you will need to first [trust](signing-and-verification-guide.md#establishing-trust) the [CoreOS public key](https://coreos.com/dist/pubkeys/aci-pubkeys.gpg) used to sign the image, using `rkt trust`: + +``` +$ 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 +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" +``` + +For more information, see the [detailed, step-by-step guide for the signing procedure](signing-and-verification-guide.md). + +Now that we've trusted the CoreOS public key, we can fetch the ACI using `rkt fetch`: + +``` +$ sudo rkt fetch coreos.com/etcd:v2.0.4 +rkt: searching for app image coreos.com/etcd:v2.0.4 +rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-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.4-linux-amd64.aci.asc +rkt: signature verified: + CoreOS ACI Builder +sha512-1eba37d9b344b33d272181e176da111e +``` + +Sometimes you will want to download an image from a private repository. +This usually involves passing usernames and passwords or other kinds of credentials to the server. +rkt currently supports authentication via configuration files. +You can find configuration file format description (with examples!) in [configuration documentation](configuration.md). + +For the curious, we can see the files written to disk in rkt's CAS: + +``` +$ find /var/lib/rkt/cas/blob/ +/var/lib/rkt/cas/blob/ +/var/lib/rkt/cas/blob/sha512 +/var/lib/rkt/cas/blob/sha512/1e +/var/lib/rkt/cas/blob/sha512/1e/sha512-1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62 +``` + +Per the [App Container Specification](https://github.com/appc/spec/blob/master/spec/aci.md#image-archives), 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.4/etcd-v2.0.4-linux-amd64.aci +... +$ gzip -dc etcd-v2.0.4-linux-amd64.aci > etcd-v2.0.4-linux-amd64.tar +$ sha512sum etcd-v2.0.4-linux-amd64.tar +1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62cce3daaee03ebd92dfbb596fe7879938374c671ae768cd927bab7b16c5e432e8 etcd-v2.0.4-linux-amd64.tar +``` + +### Launching an ACI + +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:v2.0.4"), the full URL of the ACI, or the ACI hash. +Hence, the following three examples are equivalent: + +``` +# Example of running via ACI name:version +$ sudo rkt run coreos.com/etcd:v2.0.4 +... +Press ^] three times to kill container +``` + +``` +# Example of running via ACI hash +$ sudo rkt run sha512-1eba37d9b344b33d272181e176da111e +... +Press ^] three times to kill container +``` + +``` +# Example of running via ACI URL +$ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-linux-amd64.aci +... +Press ^] three times to kill container +``` + +In the latter case, `rkt` will do the appropriate ETag checking on the URL to make sure it has the most up to date version of the image. + +Note that 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. diff --git a/Documentation/using-rkt-with-kubernetes.md b/Documentation/using-rkt-with-kubernetes.md new file mode 100644 index 00000000..52654479 --- /dev/null +++ b/Documentation/using-rkt-with-kubernetes.md @@ -0,0 +1,26 @@ +# Using rkt with Kubernetes (aka "rktnetes") + +[Kubernetes](https://kubernetes.io) is a system for managing containerized applications across a cluster of machines. +Kubernetes runs all applications in containers. +In the default setup, this is performed using the Docker engine, but Kubernetes also features support for using rkt as its container runtime backend. +This allows a Kubernetes cluster to leverage some of rkt's security features and native pod support. + +## Configuring rkt as the Kubernetes container runtime + +The container runtime is configured at the _kubelet_ level. +The kubelet is the agent that runs on each machine to manage containers. +The kubelet provides several flags to use rkt as the container runtime: +- `--container-runtime=rkt` chooses rkt as the runtime. +- `--rkt-path` sets the rkt binary path. +- `--rkt-stage1-image` sets the stage1 image path. + +The [getting started with rkt guide][] in the Kubernetes repository provides more detailed information about how to launch a kubernetes cluster with rkt, how to debug it, and more. + +[getting started with rkt guide]: https://github.com/kubernetes/kubernetes/blob/master/docs/getting-started-guides/rkt/README.md + +### Current Status + +Integration of rkt as a container runtime for Kubernetes is under active development. +For the latest information on the progress of the integration, check out [this Google doc][rkt-k8s-checklist] which tracks the detailed status of implemented functionality. + +[rkt-k8s-checklist]: https://docs.google.com/document/d/1dYxInIUDTm4HEArQ9Hom_1NhYw22WrXWdglnaLjtQsI/edit diff --git a/Documentation/using-rkt-with-nomad.md b/Documentation/using-rkt-with-nomad.md new file mode 100644 index 00000000..136763fe --- /dev/null +++ b/Documentation/using-rkt-with-nomad.md @@ -0,0 +1,8 @@ +# Using rkt with Nomad + +[Nomad][nomad] is a distributed scheduler which supports using a variety of different backends to execute _tasks_. +As of the v0.2.0 release, Nomad includes experimental support for using `rkt` as a task execution driver. +For more details, check out the [official Nomad documentation][rkt-driver]. + +[nomad]: https://www.nomadproject.io/ +[rkt-driver]: https://www.nomadproject.io/docs/drivers/rkt.html diff --git a/README.md b/README.md index e0419b84..472ca66b 100644 --- a/README.md +++ b/README.md @@ -10,16 +10,19 @@ rkt (pronounced _"rock-it"_) is a CLI for running app containers on Linux. rkt i Some of rkt's key features and goals include: -- First-class integration with init systems ([systemd](Documentation/using-rkt-with-systemd.md), upstart) and cluster orchestration tools (fleet, Kubernetes) -- Compatibility with other container software (e.g. rkt can run [Docker images](Documentation/running-docker-images.md)) -- Modular and extensible architecture ([network configuration plugins](Documentation/networking.md), swappable execution engines based on systemd or QEMU/KVM) +- First-class integration with init systems ([systemd][systemd], upstart) and cluster orchestration tools (fleet, [Kubernetes][kubernetes], [Nomad][nomad]) +- Compatibility with other container software (e.g. rkt can run [Docker images][docker]) +- Modular and extensible architecture ([network configuration plugins][networking], swappable execution engines based on systemd or [KVM][lkvm]) -For more on the background and motivation behind rkt, read the original [launch announcement](https://coreos.com/blog/rocket). +For more on the background and motivation behind rkt, read the original [launch announcement][blog-post]. -## App Container - -rkt is an implementation of the [App Container spec](Documentation/app-container.md). -rkt's native image format ([ACI](Documentation/app-container.md#ACI)) and runtime/execution environment ([pods](Documentation/app-container.md#pods)) are defined in the specification. +[systemd]: Documentation/using-rkt-with-systemd.md +[kubernetes]: Documentation/using-rkt-with-kubernetes.md +[nomad]: Documentation/using-rkt-with-nomad.md +[docker]: Documentation/running-docker-images.md +[networking]: Documentation/networking.md +[lkvm]: Documentation/running-lkvm-stage1.md +[blog-post]: https://coreos.com/blog/rocket ## Project status @@ -28,143 +31,34 @@ We do not recommend its use in production, but we encourage you to try out rkt a Check out the [roadmap](ROADMAP.md) for more details on the future of rkt. +## rkt and App Container (appc) + +rkt is an implementation of the [App Container (appc) spec](Documentation/app-container.md). +rkt's native image format ([ACI](Documentation/app-container.md#ACI)) and runtime/execution environment ([pods](Documentation/app-container.md#pods)) are defined in the specification. + ## Trying out rkt -### Using rkt on Linux +To get started quickly using rkt for the first time, start with the ["trying out rkt" document](Documentation/trying-out-rkt.md). +For an end-to-end example of building an application from scratch and running it with rkt, check out the [getting started guide](Documentation/getting-started-guide.md). -`rkt` consists of a single self-contained CLI, and is currently supported on amd64 Linux. -A modern kernel is required but there should be no other system dependencies. -We recommend booting up a fresh virtual machine to test out rkt. +## Getting help with rkt -To download the `rkt` binary, simply grab the latest release directly from GitHub: +There are a number of different avenues for seeking help and communicating with the rkt community: +- For bugs and feature requests (including documentation!), file an [issue][new-issue] +- For general discussion about both using and developing rkt, join the [rkt-dev][rkt-dev] mailing list +- For real-time discussion, join us on IRC: #[rkt-dev][irc] on freenode.org +- For more details on rkt development plans, check out the GitHub [milestones][milestones] -``` -wget https://github.com/coreos/rkt/releases/download/v0.14.0/rkt-v0.14.0.tar.gz -tar xzvf rkt-v0.14.0.tar.gz -cd rkt-v0.14.0 -./rkt help -``` +Most discussion about rkt development happens on GitHub via issues and pull requests. +The rkt developers also host a semi-regular community sync meeting open to the public. +This sync usually features demos, updates on the roadmap, and time for anyone from the community to ask questions of the developers or share users stories with others. +For more details, including how to join and recordings of previous syncs, see the [sync doc on Google Docs][sync-doc]. -### Trying out rkt using Vagrant - -For Mac (and other Vagrant) users we have set up a `Vagrantfile`: clone this repository and make sure you have [Vagrant](https://www.vagrantup.com/) 1.5.x or greater installed. -`vagrant up` starts up a Linux box and installs via some scripts `rkt` and `actool`. -With a subsequent `vagrant ssh` you are ready to go: - -``` -git clone https://github.com/coreos/rkt -cd rkt -vagrant up -vagrant ssh -``` - -Keep in mind while running through the examples that right now `rkt` needs to be run as root for most operations. - -## rkt basics - -### Building App Container Images (ACIs) - -rkt's native image format is ACI, defined in the [App Container spec](Documentation/app-container.md). -To build ACIs, a simple way to get started is by using [`acbuild`](https://github.com/appc/acbuild). -Another good resource is the [appc build repository](https://github.com/appc/build-repository) which has resources for building ACIs from a number of popular projects and languages. -There are also tools for converting [Docker images to ACIs](https://github.com/appc/docker2aci) (although note that rkt can [also run Docker images natively](Documentation/running-docker-images.md) directly from Docker repositories by using this library internally). - -The example below uses a pre-built ACI for [etcd](https://github.com/coreos/etcd) (this was built by the [build-aci script](https://github.com/coreos/etcd/blob/master/scripts/build-aci)). - -### Downloading an App Container Image (ACI) - -rkt uses content addressable storage (CAS) for storing an ACI on disk. -In this example, the image is downloaded and added to the CAS. -Downloading an image before running it is not strictly necessary (if it is not present, rkt will automatically retrieve it), but useful to illustrate how rkt works. - -Since rkt verifies signatures by default, you will need to first [trust](https://github.com/coreos/rkt/blob/master/Documentation/signing-and-verification-guide.md#establishing-trust) the [CoreOS public key](https://coreos.com/dist/pubkeys/aci-pubkeys.gpg) used to sign the image, using `rkt trust`: - -``` -$ 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 -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" -``` - -In Documentation, you can find a [detailed, step-by-step guide for the signing procedure](Documentation/signing-and-verification-guide.md). - -Now that we've trusted the CoreOS public key, we can fetch the ACI using `rkt fetch`: - -``` -$ sudo rkt fetch coreos.com/etcd:v2.0.4 -rkt: searching for app image coreos.com/etcd:v2.0.4 -rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-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.4-linux-amd64.aci.asc -rkt: signature verified: - CoreOS ACI Builder -sha512-1eba37d9b344b33d272181e176da111e -``` - -Sometimes you will want to download an image from a private repository. -This usually involves passing usernames and passwords or other kinds of credentials to the server. -rkt currently supports authentication via configuration files. -You can find configuration file format description (with examples!) in [configuration documentation](Documentation/configuration.md). - -For the curious, we can see the files written to disk in rkt's CAS: - -``` -$ find /var/lib/rkt/cas/blob/ -/var/lib/rkt/cas/blob/ -/var/lib/rkt/cas/blob/sha512 -/var/lib/rkt/cas/blob/sha512/1e -/var/lib/rkt/cas/blob/sha512/1e/sha512-1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62 -``` - -Per the [App Container Specification](https://github.com/appc/spec/blob/master/spec/aci.md#image-archives), 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.4/etcd-v2.0.4-linux-amd64.aci -... -$ gzip -dc etcd-v2.0.4-linux-amd64.aci > etcd-v2.0.4-linux-amd64.tar -$ sha512sum etcd-v2.0.4-linux-amd64.tar -1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62cce3daaee03ebd92dfbb596fe7879938374c671ae768cd927bab7b16c5e432e8 etcd-v2.0.4-linux-amd64.tar -``` - -### Launching an ACI - -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:v2.0.4"), the full URL of the ACI, or the ACI hash. -Hence, the following three examples are equivalent: - -``` -# Example of running via ACI name:version -$ sudo rkt run coreos.com/etcd:v2.0.4 -... -Press ^] three times to kill container -``` - -``` -# Example of running via ACI hash -$ sudo rkt run sha512-1eba37d9b344b33d272181e176da111e -... -Press ^] three times to kill container -``` - -``` -# Example of running via ACI URL -$ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-linux-amd64.aci -... -Press ^] three times to kill container -``` - -In the latter case, `rkt` will do the appropriate ETag checking on the URL to make sure it has the most up to date version of the image. - -Note that 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. - -## Known issues - -Due to a bug in the Linux kernel, using rkt's overlay support on top of an overlay filesystem requires Linux 4.3+. +[new-issue]: https://github.com/coreos/rkt/issues/new +[rkt-dev]: https://groups.google.com/forum/?hl=en#!forum/rkt-dev +[irc]: irc://irc.freenode.org:6667/#rkt-dev +[milestones]: https://github.com/coreos/rkt/milestones +[sync-doc]: https://docs.google.com/document/d/1NT_J5X2QErtKgd8Y3TFXNknWhJx_yOCMJnq3Iy2jPgE/edit# ## Contributing to rkt @@ -172,8 +66,7 @@ rkt is an open source project under the Apache 2.0 [license](LICENSE), and contr See the [Hacking Guide](Documentation/hacking.md) for more information on how to build and work on rkt. See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow. -## Contact +## Known issues + +Due to a bug in the Linux kernel, using rkt's overlay support on top of an overlay filesystem requires Linux 4.3+. -- Mailing list: [rkt-dev](https://groups.google.com/forum/?hl=en#!forum/rkt-dev) -- IRC: #[rkt-dev](irc://irc.freenode.org:6667/#rkt-dev) on freenode.org -- Planning: [milestones](https://github.com/coreos/rkt/milestones)