github.com/rkt/rkt@v1.30.1-0.20200224141603-171c416fac02/Documentation/trying-out-rkt.md (about) 1 # Trying out rkt 2 3 This document introduces the basics of getting rkt and running a container with it. For a more in-depth guide to building application containers and running them with rkt, check out the [getting started guide][getstart]. 4 5 Giving rkt a spin takes just a few basic steps, detailed below. 6 7 1. Install rkt: 8 * [CoreOS Container Linux][run-cl] comes with rkt installed and configured. You can skip straight to [running a container with rkt][id-rkt-run-by-name]. 9 * On other Linux distributions, [grab the latest rkt binary][id-lin-rkt-bin], or [the distribution's rkt package][id-lin-rkt-pkg]. 10 * On Mac or Windows, you can [use a Vagrant virtual machine to run rkt][id-vagrant-rkt] 11 2. [Configure rkt][id-config-rkt]: Optional steps that make it simpler to experiment with rkt. 12 3. [Download][id-rkt-fetch] and [run a container with rkt][id-rkt-run]. 13 14 ## Using rkt on Linux 15 16 rkt is written in Go and can be compiled for several CPU architectures. The rkt project distributes binaries for amd64. These rkt binaries will run on any modern Linux amd64 kernel. 17 18 ### Running the latest rkt binary 19 20 To start running the latest version of rkt on amd64, grab the release directly from the rkt GitHub project: 21 22 ``` 23 wget https://github.com/rkt/rkt/releases/download/v1.30.0/rkt-v1.30.0.tar.gz 24 tar xzvf rkt-v1.30.0.tar.gz 25 cd rkt-v1.30.0 26 ./rkt help 27 ``` 28 29 ### Installing rkt from a Linux distribution package 30 31 Another easy way to run rkt is to install it with your system's package manager, like *apt* on Debian or *dnf* on Fedora. Check for your Linux distribution in the [distributions list][distlist] to see if a rkt package is available. 32 33 ## Running rkt in a Vagrant virtual machine 34 35 If your operating system isn't Linux, it's easy to run rkt in a Linux virtual machine with Vagrant. The instructions below start a virtual machine with rkt installed and ready to run. 36 37 ### Vagrant on Mac and Windows 38 39 For Mac (and other Vagrant) users we have set up a `Vagrantfile`. Make sure you have [Vagrant][vagrant] 1.5.x or greater installed. 40 41 First, download the `Vagrantfile` and start a Linux machine with rkt installed by running `vagrant up`. 42 43 ``` 44 git clone https://github.com/rkt/rkt 45 cd rkt 46 vagrant up 47 ``` 48 49 ### Vagrant on Linux 50 51 To use Vagrant on a Linux machine, you may want to use libvirt as a VMM instead of VirtualBox. To do so, install the necessary plugins, convert the box, and start the machine using the `libvirt` provider: 52 53 ``` 54 vagrant plugin install vagrant-libvirt 55 vagrant plugin install vagrant-mutate 56 vagrant mutate ubuntu/xenial64 libvirt 57 vagrant up --provider=libvirt 58 ``` 59 60 ### Accessing the Vagrant VM and running rkt 61 62 With a subsequent `vagrant ssh` you will have access to run rkt: 63 64 If you are running an outdated version of VirtualBox, it may be that SSH asks for a password. You can find the password for the `ubuntu` user in `~/.vagrant.d/boxes/ubuntu-VAGRANTSLASH-xenial64/[DATE]/virtualbox/Vagrantfile` 65 under `config.ssh.password`. 66 67 ``` 68 vagrant ssh 69 rkt --help 70 ``` 71 72 Consult the rkt manual for more details: 73 74 ``` 75 man rkt 76 ``` 77 78 The Vagrant setup also includes bash-completion to assist with rkt subcommands and options. 79 80 #### Container networking on a Vagrant VM 81 82 To reach pods from your host, determine the IP address of the Vagrant machine: 83 84 ``` 85 vagrant ssh -c 'ip address' 86 ... 87 3: enp0s8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 88 link/ether 08:00:27:04:e4:5d brd ff:ff:ff:ff:ff:ff 89 inet 172.28.128.3/24 brd 172.28.128.255 scope global enp0s8 90 valid_lft forever preferred_lft forever 91 ... 92 ``` 93 94 In this example, the Vagrant machine has the IP address `172.28.128.3`. 95 96 The following command starts an [`nginx`][docker-nginx] container, for simplicity using [*host networking*][host-network] to make the pod directly accessible on the host's network address and ports. Signature validation isn't supported for Docker registries and images, so `--insecure-options=image` switches off the signature check: 97 98 ``` 99 sudo rkt run --net=host --insecure-options=image docker://nginx 100 ``` 101 102 The nginx container is now accessible on the host under `http://172.28.128.3`. 103 104 In order to use containers with the default [*contained network*][contained-network], a route to the 172.16.28.0/24 container network must be configured from the host through the VM: 105 106 On Linux, execute: 107 108 ``` 109 sudo ip route add 172.16.28.0/24 via 172.28.128.3 110 ``` 111 112 On Mac OSX, execute: 113 114 ``` 115 sudo route -n add 172.16.28.0/24 172.28.128.3 116 ``` 117 118 Now nginx can be started using the default contained network: 119 120 ``` 121 $ sudo rkt run --insecure-options=image docker://nginx 122 $ rkt list 123 UUID APP IMAGE NAME STATE CREATED STARTED NETWORKS 124 0c3ab969 nginx registry-1.docker.io/library/nginx:latest running 2 minutes ago 2 minutes ago default:ip4=172.16.28.2 125 ``` 126 127 In this example, the nginx container was assigned the IP address 172.16.28.2 (the address assigned on your system may vary). Since we established a route from the host to the `172.16.28.0/24` pod network the nginx container is now accessible on the host under `http://172.16.28.2`. 128 129 Success! The rest of the guide can now be followed normally. 130 131 ## Configuring a rkt host 132 133 Once rkt is present on a machine, some optional configuration steps can make it easier to operate. 134 135 ### SELinux 136 137 rkt supports running under SELinux mandatory access controls, but an SELinux policy needs to be tailored to your distribution. New rkt users on distributions other than Container Linux should temporarily [disable SELinux][disable-selinux] to make it easier to get started. If you can help package rkt for your distro, including SELinux policy support, [please lend a hand][distro-pkg-help]! 138 139 ### Optional: Set up privilege separation 140 141 To allow different subcommands to use the least necessary privilege, rkt recognizes a `rkt` group that has read-write access to the rkt data directory. This allows [`rkt fetch`][rkt-fetch], which downloads and verifies images, to run as an unprivileged user who is a member of the `rkt` group. 142 143 If you skip this section, you can still run `sudo rkt fetch` instead, but setting up a `rkt` group is a good basic security practice for production use. The rkt repo includes a [`setup-data-dir.sh`][setup-data-dir] script that can help set up the appropriate permissions for unprivileged execution of subcommands that manipulate the local store, but not the execution environment: 144 145 ``` 146 sudo groupadd rkt 147 export WHOAMI=$(whoami); sudo gpasswd -a $WHOAMI rkt 148 sudo ./dist/scripts/setup-data-dir.sh 149 ``` 150 151 #### Trust the signing key to validate unprivileged fetches 152 153 Trust the signing key for etcd images. This step must be run as root because access to the keystore is restricted from even the `rkt` group: 154 155 ``` 156 sudo ./rkt trust --prefix coreos.com/etcd 157 ``` 158 159 #### Fetch an image as an unprivileged member of the rkt group 160 161 Test this out by retrieving an etcd image using a non-root user in the rkt group. Make sure your shell is restarted to enable the `rkt` group for your user, or 162 just run `newgrp rkt` to enable it and continue in the same session. 163 164 Now fetch the etcd image as an unprivileged user: 165 166 ``` 167 ./rkt fetch coreos.com/etcd:v3.1.7 168 ``` 169 170 Success! Now rkt can fetch and download images as an unprivileged user. 171 172 ## rkt basics 173 174 ### Building an App Container Image 175 176 rkt's native image format is the App Container Image (ACI), defined in the [App Container spec][appc]. The [`acbuild`][acbuild] tool is a simple way to get started building ACIs. The [appc build repository][appc-build-repo] has resources for building ACIs from a number of popular applications. 177 178 The `docker2aci` tool [converts Docker images to ACIs][docker2aci], or rkt can [convert images directly from Docker registries on the fly][rktdocker]. 179 180 The example below uses an [etcd][etcd] ACI constructed with `acbuild` by the etcd project's [`build-aci` script][build-aci]. 181 182 ### Downloading an ACI 183 184 rkt uses content addressable storage (CAS) to store an ACI on disk. In this example, an image is downloaded and added to the CAS. Downloading an image before running it is not strictly necessary – if an image is not present in the store, [rkt will attempt to retrieve it][aci-discovery] – but it illustrates how rkt works. 185 186 Since rkt verifies signatures by default, the first step is to [trust][signguide-establishing-trust] the [CoreOS public key][coreos-pubkey] used to sign the image, using the [`rkt trust`][rkt-trust] subcommand: 187 188 #### Trusting the signing key 189 190 ``` 191 $ sudo rkt trust --prefix=coreos.com/etcd 192 Prefix: "coreos.com/etcd" 193 Key: "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" 194 GPG key fingerprint is: 8B86 DE38 890D DB72 9186 7B02 5210 BD88 8818 2190 195 CoreOS ACI Builder <release@coreos.com> 196 Are you sure you want to trust this key (yes/no)? yes 197 Trusting "https://coreos.com/dist/pubkeys/aci-pubkeys.gpg" for prefix "coreos.com/etcd". 198 Added key for prefix "coreos.com/etcd" at "/etc/rkt/trustedkeys/prefix.d/coreos.com/etcd/8b86de38890ddb7291867b025210bd8888182190" 199 ``` 200 201 For more information, see the [detailed, step-by-step guide for the signing procedure][signguide]. 202 203 #### Fetching the ACI 204 205 Now that the CoreOS public key is trusted, fetch the ACI using [`rkt fetch`][rkt-fetch]. This step doesn't need root privileges if the rkt host has been [configured for privilege separation][id-privsep]: 206 207 ``` 208 $ rkt fetch coreos.com/etcd:v3.1.7 209 rkt: searching for app image coreos.com/etcd:v3.1.7 210 rkt: fetching image from https://github.com/coreos/etcd/releases/download/v3.1.7/etcd-v3.1.7-linux-amd64.aci 211 Downloading aci: [========================================== ] 3.47 MB/3.7 MB 212 Downloading signature from https://github.com/coreos/etcd/releases/download/v3.1.7/etcd-v3.1.7-linux-amd64.asc 213 rkt: signature verified: 214 CoreOS ACI Builder <release@coreos.com> 215 sha512-7d28419b27d5ae56cca97f4c6ccdd309c... 216 ``` 217 218 #### Downloading images from private registries 219 220 Downloading container images from a private registry usually involves passing usernames and passwords or other kinds of credentials to the server. rkt supports different authentication regimes with configuration files. The [configuration documentation][configdoc] describes the file format and gives examples of setting up authentication with HTTP `basic` auth, OAuth bearer tokens, and other methods. 221 222 ### The image in the local store 223 224 For the curious, it is possible to list the hash-identified files written to disk in rkt's CAS: 225 226 ``` 227 $ find /var/lib/rkt/cas/blob/ 228 /var/lib/rkt/cas/blob/ 229 /var/lib/rkt/cas/blob/sha512 230 /var/lib/rkt/cas/blob/sha512/1e 231 /var/lib/rkt/cas/blob/sha512/1e/sha512-7d28419b27d5ae56cca97f4c6ccdd309c95b967ca0119f6962b187d1287ec9967f49e367c36b0e44ecd73675bc06d112dec86386d0e9b84c2265cddd45d15020 232 ``` 233 234 According to the [App Container specification][aci-archives], the SHA-512 hash is that of the `tar` file compressed in the ACI, and can be examined with standard tools: 235 236 ``` 237 $ wget https://github.com/coreos/etcd/releases/download/v3.1.7/etcd-v3.1.7-linux-amd64.aci 238 ... 239 $ gzip -dc etcd-v3.1.7-linux-amd64.aci > etcd-v3.1.7-linux-amd64.tar 240 $ sha512sum etcd-v3.1.7-linux-amd64.tar 241 7d28419b27d5ae56cca97f4c6ccdd309c95b967ca0119f6962b187d1287ec9967f49e367c36b0e44ecd73675bc06d112dec86386d0e9b84c2265cddd45d15020 etcd-v3.1.7-linux-amd64.tar 242 ``` 243 244 ### Running an ACI with rkt 245 246 After it has been retrieved and stored locally, an ACI can be run by pointing [`rkt run`][rkt-run] at either the original image reference (in this case, `coreos.com/etcd:v3.1.7`), the ACI hash, or the full URL of the ACI. Therefore the following three examples are equivalent: 247 248 #### Running the container by ACI name and version 249 250 ``` 251 $ sudo rkt run coreos.com/etcd:v3.1.7 252 ... 253 Press ^] three times to kill container 254 ``` 255 256 #### Running the container by ACI hash 257 258 ``` 259 $ sudo rkt run sha512-1eba37d9b344b33d272181e176da111e 260 ... 261 ^]]] 262 ``` 263 264 #### Running the container by ACI URL 265 266 ``` 267 $ sudo rkt run https://github.com/coreos/etcd/releases/download/v3.1.7/etcd-v3.1.7-linux-amd64.aci 268 ... 269 ^]]] 270 ``` 271 272 When given an ACI URL, `rkt` will do the appropriate ETag checking to fetch the latest version of the container image. 273 274 ### Exiting rkt pods 275 276 As shown above, repeating the `^]` escape character three times kills the pod and detaches from its console to return to the user's shell. 277 278 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, or ```Ctrl-^``` on Windows, to generate the ```^]``` escape character. 279 280 281 [acbuild]: https://github.com/containers/build 282 [aci-archives]: https://github.com/appc/spec/blob/master/spec/aci.md#image-archives 283 [aci-discovery]: https://github.com/appc/spec/blob/master/spec/discovery.md 284 [appc]: app-container.md 285 [appc-build-repo]: https://github.com/appc/build-repository 286 [build-aci]: https://github.com/coreos/etcd/blob/master/scripts/build-aci 287 [contained-network]: networking/overview.md#contained-mode 288 [coreos-pubkey]: https://coreos.com/dist/pubkeys/aci-pubkeys.gpg 289 [configdoc]: configuration.md 290 [disable-selinux]: https://www.centos.org/docs/5/html/5.1/Deployment_Guide/sec-sel-enable-disable.html 291 [distlist]: distributions.md 292 [distro-pkg-help]: https://github.com/rkt/rkt/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3Aarea%2Fdistribution++label%3Adependency%2Fexternal 293 [docker2aci]: https://github.com/appc/docker2aci 294 [docker-nginx]: https://hub.docker.com/_/nginx/ 295 [etcd]: https://coreos.com/etcd/ 296 [getstart]: getting-started-guide.md 297 [host-network]: networking/overview.md#host-mode 298 [id-config-rkt]: #configuring-a-rkt-host 299 [id-lin-rkt-bin]: #running-the-latest-rkt-binary 300 [id-lin-rkt-pkg]: #installing-rkt-from-a-linux-distribution-package 301 [id-privsep]: #optional-set-up-privilege-separation 302 [id-rkt-fetch]: #downloading-an-aci 303 [id-rkt-run]: #running-an-aci-with-rkt 304 [id-rkt-run-by-name]: #running-the-container-by-aci-name-and-version 305 [id-vagrant-rkt]: #running-rkt-in-a-vagrant-virtual-machine 306 [rktdocker]: running-docker-images.md 307 [rkt-fetch]: subcommands/fetch.md 308 [rkt-run]: subcommands/run.md 309 [rkt-trust]: subcommands/trust.md 310 [run-cl]: https://coreos.com/os/docs/latest/#running-coreos 311 [setup-data-dir]: https://github.com/rkt/rkt/blob/master/dist/scripts/setup-data-dir.sh 312 [signguide]: signing-and-verification-guide.md 313 [signguide-establishing-trust]: signing-and-verification-guide.md#establishing-trust 314 [vagrant]: https://www.vagrantup.com/