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)