clearlinux/rkt
2
0
Fork 0
mirror of https://github.com/clearlinux/rkt.git synced 2026-09-01 02:44:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

*: rework documentation

Browse Source 
- Update README to include contributing/contact sections
- Split out appc description into its own document
- Split out stages description into architecture document (will soon be
  in need of more updates)
- Standardise on "Rocket" instead of "rocket"
- Add godoc link
This commit is contained in:
Jonathan Boulle
2015-01-30 14:06:49 +01:00
parent 17a3e8e8a7
commit 546e96641e
5 changed files with 114 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/app-container.md
+23
View File
@@ -0,0 +1,23 @@
## App Container basics
[App Container][appc-repo] is a [specification][appc-spec] of an image format, runtime, and discovery protocol for running applications in containers.
Rocket implements the two runtime components of the specification: the [Application Container Executor (ACE)][appc-ace] and the [Metadata Service][appc-meta].
It also leverages schema and code from the upstream [appc/spec][appc-spec] repo to manipulate ACIs, work with manifests, and perform image discovery.
## Validating Rocket
To validate that `rkt` successfully implements the ACE part of the spec, use the App Container [validation ACIs][appc-readme]:
```
$ sudo rkt run -volume database,kind=host,source=/tmp \
https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-main.aci \
https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-sidekick.aci
```
[appc-repo]: https://github.com/appc/spec/
[appc-spec]: https://github.com/appc/spec/blob/master/SPEC.md
[appc-readme]: https://github.com/appc/spec/blob/master/README.md
[appc-ace]: https://github.com/appc/spec/blob/master/SPEC.md#app-container-executor
[appc-meta]: https://github.com/appc/spec/blob/master/SPEC.md#app-container-metadata-service
Documentation/architecture.md
+71
View File
@@ -0,0 +1,71 @@
# Rocket architecture
## Overview
Rocket consists only of a command-line tool, `rkt`, and does not have a daemon. This architecture allows Rocket to be updated in-place without affecting containers which are currently running. It also means that levels of privilege can be separated out between different operations.
All state in Rocket is communicated via the filesystem. Facilities like file-locking are used to ensure co-operation and mutual exclusion between concurrent invocations of the `rkt` command.
## Stages
Execution with Rocket is divided into several distinct stages.
### Stage 0
The first stage is the actual `rkt` binary itself. When running a container, this binary is responsible for performing a number of initial preparatory tasks:
- Fetching the specified ACIs, including the stage 1 ACI of --stage1-image if specified.
- Generating a Container UUID
- Generating a Container Runtime Manifest
- Creating a filesystem for the container
- Setting up stage 1 and stage 2 directories in the filesystem
- Unpacking the stage 1 ACI into the container filesystem
- Unpacking the ACIs and copying each app into the stage2 directories
Given a run command such as:
```
$ sudo rkt run \
sha512-8a30f14877cd8065939e3912542a17d1a5fd9b4c \
sha512-abcd29837d89389s9d0898ds908ds890df890908
```
a container manifest compliant with the ACE spec will be generated, and the filesystem created by stage0 should be:
```
/container
/stage1
/stage1/manifest
/stage1/rootfs/init
/stage1/rootfs/opt
/stage1/rootfs/opt/stage2/sha512-648db489d57363b29f1597d4312b2129
/stage1/rootfs/opt/stage2/sha512-0c45e8c0ab2b3cdb9ec6649073d5c6c4
```
where:
- `container` is the container manifest file
- `stage1` is a copy of the stage1 ACI that is safe for read/write
- `stage1/manifest` is the manifest of the stage1 ACI
- `stage1/rootfs` is the rootfs of the stage1 ACI
- `stage1/rootfs/init` is the actual stage1 binary to be executed (this path may vary according to the `coreos.com/rocket/stage1/init` Annotation of the stage1 ACI)
- `stage1/rootfs/opt/stage2` are copies of the unpacked ACIs
At this point the stage0 execs `/stage1/rootfs/init` with the current working directory set to the root of the new filesystem.
### Stage 1
The next stage is a binary that the user trusts to set up cgroups, execute processes, and perform other operations as root on the host. This stage has the responsibility of taking the execution group filesystem that was created by stage 0 and creating the necessary cgroups, namespaces and mounts to launch the execution group:
- Generate systemd unit files from the Image and Container Runtime Manifests. The Image Manifest defines the default `exec` specifications of each application; the Container Runtime Manifest defines the ordering of the units, as well as any `exec` overrides.
- (containing, respectively, the exec specifications of each container and the ordering given by the user)
- Set up any external volumes (undefined at this point)
- nspawn attaching to the bridge and launch the execution group systemd
- Launch the root systemd
- Have the root systemd
This process is slightly different for the qemu-kvm stage1 but a similar workflow starting at `exec()`'ing kvm instead of an nspawn.
### Stage 2
The final stage is executing the actual application. The responsibilities of the stage2 include:
- Launch the init process described in the Application Manifest
Documentation/getting-started-ubuntu-trusty.md
+3 -3
View File
@@ -16,9 +16,9 @@ vagrant up --provider virtualbox
vagrant ssh
sudo su
wget https://github.com/coreos/rocket/releases/download/v0.2.0/rocket-v0.2.0.tar.gz
tar xzvf rocket-v0.2.0.tar.gz
cd rocket-v0.2.0
wget https://github.com/coreos/rocket/releases/download/v0.3.1/rocket-v0.3.1.tar.gz
tar xzvf rocket-v0.3.1.tar.gz
cd rocket-v0.3.1
./rkt help
```
## Trust the CoreOS signing key
Documentation/hacking.md
+2 -2
View File
@@ -1,6 +1,6 @@
# Hacking Guide
## Building rocket
## Building Rocket
### Requirements
@@ -15,7 +15,7 @@
* Go 1.3+
* github.com/appc/spec (not yet vendored as it's in a continuous improvement phase)
Once the requirements have been met you can build rocket by running the following commands:
Once the requirements have been met you can build Rocket by running the following commands:
```
git clone https://github.com/coreos/rocket.git
README.md
+15 -83
View File
@@ -1,10 +1,11 @@
# Rocket - App Container runtime
[![Build Status](https://travis-ci.org/coreos/rocket.png?branch=master)](https://travis-ci.org/coreos/rocket)
[![godoc](https://godoc.org/github.com/coreos/rocket?status.svg)](http://godoc.org/github.com/coreos/rocket)
_Release early, release often: Rocket is currently a prototype and we are seeking your feedback via issues and pull requests_
Rocket is a CLI for running App Containers. The goal of rocket is to be composable, secure, and fast.
Rocket is a CLI for running app containers, and an implementation of the [App Container Spec](Documentation/app-container.md). The goal of Rocket is to be composable, secure, and fast.
[Read more about Rocket in the launch announcement](https://coreos.com/blog/rocket).
@@ -12,9 +13,9 @@ Rocket is a CLI for running App Containers. The goal of rocket is to be composab
## Trying out Rocket
`rkt` is currently supported on amd64 Linux. We recommend booting up a fresh virtual machine to test out rocket.
The CLI for Rocket is called `rkt`, 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 Rocket.
To install the `rkt` binary, grab the release directly from GitHub:
To install the `rkt` binary, grab the latest release directly from GitHub:
```
wget https://github.com/coreos/rocket/releases/download/v0.3.1/rocket-v0.3.1.tar.gz
@@ -81,7 +82,7 @@ fa1cb92dc276b0f9bedf87981e61ecde93cc16432d2441f23aa006a42bb873dfc67480dafb0dfb33
### Launching an ACI
An ACI can be run by pointing `rkt` at either the ACI's hash or URL.
After it has been retrieved and stored locally, an ACI can be run by pointing `rkt` at either the ACI's hash or URL.
```
# Example of running via ACI hash
@@ -97,87 +98,18 @@ $ sudo rkt run https://github.com/coreos/etcd/releases/download/v2.0.0/etcd-v2.0
Press ^] three times to kill container
```
`rkt` will do the appropriate ETag checking on the URL to make sure it has the most up to date version of the image.
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.
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.
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.
## App Container basics
## Contributing to Rocket
[App Container][appc-repo] is a [specification][appc-spec] of an image format, runtime, and discovery protocol for running a container. We anticipate app container will be adopted by other runtimes outside of Rocket itself. Read more about it [here][appc-repo].
Rocket is an open source project under the Apache 2.0 [license](LICENSE), and contributions are gladly welcomed!
See the [Hacking Guide](Documentation/hacking.md) for more information on how to build and work on Rocket.
See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
To validate the `rkt` with the App Container [validation ACIs][appc-readme] run:
## Contact
```
$ sudo ./rkt run --volume database,kind=host,source=/tmp \
https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-main.aci \
https://github.com/appc/spec/releases/download/v0.1.1/ace-validator-sidekick.aci
```
[appc-repo]: https://github.com/appc/spec/
[appc-spec]: https://github.com/appc/spec/blob/master/SPEC.md
[appc-readme]: https://github.com/appc/spec/blob/master/README.md
## Rocket internals
Rocket is designed to be modular and pluggable by default. To do this we have a concept of "stages" of execution of the container.
Execution with Rocket is divided into a number of distinct stages. The motivation for this is to separate the concerns of initial filesystem setup, execution environment, and finally the execution of the apps themselves.
### Stage 0
The first step of the process, stage 0, is the actual `rkt` binary itself. This binary is in charge of doing a number of initial preparatory tasks:
- Fetching the specified ACIs, including the stage 1 ACI of --stage1-image if specified.
- Generating a Container UUID
- Generating a Container Runtime Manifest
- Creating a filesystem for the container
- Setting up stage 1 and stage 2 directories in the filesystem
- Unpacking the stage 1 ACI into the container filesystem
- Unpacking the ACIs and copying each app into the stage2 directories
Given a run command such as:
```
$ sudo ./rkt run --volume data,kind=host,source=/opt/tenant1/database \
sha512-8a30f14877cd8065939e3912542a17d1a5fd9b4c \
sha512-abcd29837d89389s9d0898ds908ds890df890908
```
a container manifest compliant with the ACE spec will be generated, and the filesystem created by stage0 should be:
```
/container
/stage1
/stage1/manifest
/stage1/rootfs/init
/stage1/rootfs/opt
/stage1/rootfs/opt/stage2/sha512-648db489d57363b29f1597d4312b2129
/stage1/rootfs/opt/stage2/sha512-0c45e8c0ab2b3cdb9ec6649073d5c6c4
```
where:
- `container` is the container manifest file
- `stage1` is a copy of the stage1 ACI that is safe for read/write
- `stage1/manifest` is the manifest of the stage1 ACI
- `stage1/rootfs` is the rootfs of the stage1 ACI
- `stage1/rootfs/init` is the actual stage1 binary to be executed (this path may vary according to the `coreos.com/rocket/stage1/run` Annotation of the stage1 ACI)
- `stage1/rootfs/opt/stage2` are copies of the unpacked ACIs
At this point the stage0 execs `/stage1/rootfs/init` with the current working directory set to the root of the new filesystem.
### Stage 1
The next stage is a binary that the user trusts to set up cgroups, execute processes, and other operations as root. This stage has the responsibility to take the execution group filesystem that was created by stage 0 and create the necessary cgroups, namespaces and mounts to launch the execution group:
- Generate systemd unit files from the Application and Container Manifests (containing, respectively, the exec specifications of each container and the ordering given by the user)
- Set up any external volumes (undefined at this point)
- nspawn attaching to the bridge and launch the execution group systemd
- Launch the root systemd
- Have the root systemd
This process is slightly different for the qemu-kvm stage1 but a similar workflow starting at `exec()`'ing kvm instead of an nspawn.
### Stage 2
The final stage is executing the actual application. The responsibilities of the stage2 include:
- Launch the init process described in the Application Manifest
- Mailing list: [rocket-dev](https://groups.google.com/forum/?hl=en#!forum/rocket-dev)
- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) on freenode.org
- Planning/Roadmap: [milestones](https://github.com/coreos/rocket/milestones)