github.com/stackdocker/rkt@v0.10.1-0.20151109095037-1aa827478248/README.md (about) 1 # rkt - App Container runtime 2 3 [](http://godoc.org/github.com/coreos/rkt) 4 [](https://travis-ci.org/coreos/rkt) 5 [](https://semaphoreci.com/coreos/rkt) 6 7  8 9 rkt (pronounced _"rock-it"_) is a CLI for running app containers on Linux. rkt is designed to be composable, secure, and fast. 10 11 Some of rkt's key features and goals include: 12 - First-class integration with init systems ([systemd](Documentation/using-rkt-with-systemd.md), upstart) and cluster orchestration tools (fleet, Kubernetes) 13 - Compatibility with other container software (e.g. rkt can run [Docker images](Documentation/running-docker-images.md)) 14 - Modular and extensible architecture ([network configuration plugins](Documentation/networking.md), swappable execution engines based on systemd or QEMU/KVM) 15 16 For more on the background and motivation behind rkt, read the original [launch announcement](https://coreos.com/blog/rocket). 17 18 ## App Container 19 20 rkt is an implementation of the [App Container spec](Documentation/app-container.md). 21 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. 22 23 ## Project status 24 25 rkt is maturing rapidly while under active development, and its interfaces are not yet considered stable. We do not recommend its use in production, but we encourage you to try out rkt and provide feedback via issues and pull requests. 26 27 Check out the [roadmap](ROADMAP.md) for more details on the future of rkt. 28 29 ## Trying out rkt 30 31 ### Using rkt on Linux 32 33 `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. 34 35 To download the `rkt` binary, simply grab the latest release directly from GitHub: 36 37 ``` 38 wget https://github.com/coreos/rkt/releases/download/v0.10.0/rkt-v0.10.0.tar.gz 39 tar xzvf rkt-v0.10.0.tar.gz 40 cd rkt-v0.10.0 41 ./rkt help 42 ``` 43 44 ### Trying out rkt using Vagrant 45 46 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: 47 ``` 48 git clone https://github.com/coreos/rkt 49 cd rkt 50 vagrant up 51 vagrant ssh 52 ``` 53 54 Keep in mind while running through the examples that right now `rkt` needs to be run as root for most operations. 55 56 ## rkt basics 57 58 ### Building App Container Images (ACIs) 59 60 rkt's native image format is ACI, defined in the [App Container spec](Documentation/app-container.md). 61 To build ACIs, a simple way to get started is by using [`acbuild`](https://github.com/appc/acbuild). 62 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. 63 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). 64 65 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)). 66 67 ### Downloading an App Container Image (ACI) 68 69 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. 70 71 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`: 72 73 ``` 74 $ sudo rkt trust --prefix=coreos.com/etcd 75 Prefix: "coreos.com/etcd" 76 Key: "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" 77 GPG key fingerprint is: 8B86 DE38 890D DB72 9186 7B02 5210 BD88 8818 2190 78 CoreOS ACI Builder <release@coreos.com> 79 Are you sure you want to trust this key (yes/no)? yes 80 Trusting "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" for prefix "coreos.com/etcd". 81 Added key for prefix "coreos.com/etcd" at "/etc/rkt/trustedkeys/prefix.d/coreos.com/etcd/8b86de38890ddb7291867b025210bd8888182190" 82 ``` 83 84 In Documentation, you can find a [detailed, step-by-step guide for the signing procedure](Documentation/getting-started-ubuntu-vivid.md#trust-the-coreos-signing-key). 85 86 Now that we've trusted the CoreOS public key, we can fetch the ACI using `rkt fetch`: 87 88 ``` 89 $ sudo rkt fetch coreos.com/etcd:v2.0.4 90 rkt: searching for app image coreos.com/etcd:v2.0.4 91 rkt: fetching image from https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-linux-amd64.aci 92 Downloading aci: [========================================== ] 3.47 MB/3.7 MB 93 Downloading signature from https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0.4-linux-amd64.aci.asc 94 rkt: signature verified: 95 CoreOS ACI Builder <release@coreos.com> 96 sha512-1eba37d9b344b33d272181e176da111e 97 ``` 98 99 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). 100 101 For the curious, we can see the files written to disk in rkt's CAS: 102 103 ``` 104 $ find /var/lib/rkt/cas/blob/ 105 /var/lib/rkt/cas/blob/ 106 /var/lib/rkt/cas/blob/sha512 107 /var/lib/rkt/cas/blob/sha512/1e 108 /var/lib/rkt/cas/blob/sha512/1e/sha512-1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62 109 ``` 110 111 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: 112 113 ``` 114 $ wget https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-linux-amd64.aci 115 ... 116 $ gzip -dc etcd-v2.0.4-linux-amd64.aci > etcd-v2.0.4-linux-amd64.tar 117 $ sha512sum etcd-v2.0.4-linux-amd64.tar 118 1eba37d9b344b33d272181e176da111ef2fdd4958b88ba4071e56db9ac07cf62cce3daaee03ebd92dfbb596fe7879938374c671ae768cd927bab7b16c5e432e8 etcd-v2.0.4-linux-amd64.tar 119 ``` 120 121 ### Launching an ACI 122 123 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: 124 125 ``` 126 # Example of running via ACI name:version 127 $ sudo rkt run coreos.com/etcd:v2.0.4 128 ... 129 Press ^] three times to kill container 130 ``` 131 132 ``` 133 # Example of running via ACI hash 134 $ sudo rkt run sha512-1eba37d9b344b33d272181e176da111e 135 ... 136 Press ^] three times to kill container 137 ``` 138 139 ``` 140 # Example of running via ACI URL 141 $ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.4/etcd-v2.0.4-linux-amd64.aci 142 ... 143 Press ^] three times to kill container 144 ``` 145 146 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. 147 148 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. 149 150 ## Known issues 151 152 Due to a bug in the Linux kernel, using rkt's overlay support on top of an overlay filesystem requires Linux 4.3+. 153 154 ## Contributing to rkt 155 156 rkt is an open source project under the Apache 2.0 [license](LICENSE), and contributions are gladly welcomed! 157 See the [Hacking Guide](Documentation/hacking.md) for more information on how to build and work on rkt. 158 See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow. 159 160 ## Contact 161 162 - Mailing list: [rkt-dev](https://groups.google.com/forum/?hl=en#!forum/rkt-dev) 163 - IRC: #[rkt-dev](irc://irc.freenode.org:6667/#rkt-dev) on freenode.org 164 - Planning: [milestones](https://github.com/coreos/rkt/milestones)