Merge pull request #905 from crosbymichael/update-readme
Update readme for create start
This commit is contained in:
Daniel, Dao Quang Minh
GitHub
commit
8fbe19e020
206
README.md
206
README.md
|
|
@ -4,40 +4,42 @@
|
|||
|
||||
`runc` is a CLI tool for spawning and running containers according to the OCI specification.
|
||||
|
||||
## State of the project
|
||||
## Releases
|
||||
|
||||
Currently `runc` is an implementation of the OCI specification. We are currently sprinting
|
||||
to have a v1 of the spec out. So the `runc` config format will be constantly changing until
|
||||
the spec is finalized. However, we encourage you to try out the tool and give feedback.
|
||||
`runc` depends on and tracks the [specs](https://github.com/opencontainers/runtime-spec) repository.
|
||||
We will try to make sure that `runc` and the OCI specification major versions stay in lockstep.
|
||||
This means that `runc` 1.0.0 should implement the 1.0 version of the specification.
|
||||
|
||||
### OCI
|
||||
You can find officials releases of `runc` on the [release](https://github.com/opencontainers/runc/releases) page.
|
||||
|
||||
How does `runc` integrate with the Open Container Initiative Specification?
|
||||
`runc` depends on the types specified in the
|
||||
[specs](https://github.com/opencontainers/runtime-spec) repository. Whenever the
|
||||
specification is updated and ready to be versioned `runc` will update its dependency
|
||||
on the specs repository and support the update spec.
|
||||
## Building
|
||||
|
||||
### Building:
|
||||
|
||||
At the time of writing, runc only builds on the Linux platform and requires go version 1.6 or higher.
|
||||
`runc` currently supports the Linux platform with various architecture support.
|
||||
It must be built with Go version 1.6 or higher in order for some features to function properly.
|
||||
|
||||
```bash
|
||||
# create a 'github.com/opencontainers' in your GOPATH/src
|
||||
cd github.com/opencontainers
|
||||
git clone https://github.com/opencontainers/runc
|
||||
cd runc
|
||||
|
||||
make
|
||||
sudo make install
|
||||
```
|
||||
|
||||
`runc` will be installed to `/usr/local/sbin/runc` on your system.
|
||||
|
||||
In order to enable seccomp support you will need to install libseccomp on your platform.
|
||||
If you do not want to build `runc` with seccomp support you can add `BUILDTAGS=""` when running make.
|
||||
|
||||
#### Build Tags
|
||||
|
||||
`runc` supports optional build tags for compiling in support for various features.
|
||||
`runc` supports optional build tags for compiling support of various features.
|
||||
To add build tags to the make option the `BUILDTAGS` variable must be set.
|
||||
|
||||
```bash
|
||||
make BUILDTAGS='seccomp apparmor'
|
||||
```
|
||||
|
||||
| Build Tag | Feature | Dependency |
|
||||
|-----------|------------------------------------|-------------|
|
||||
|
|
@ -45,98 +47,142 @@ If you do not want to build `runc` with seccomp support you can add `BUILDTAGS="
|
|||
| selinux | selinux process and mount labeling | <none> |
|
||||
| apparmor | apparmor profile support | libapparmor |
|
||||
|
||||
### Testing:
|
||||
|
||||
You can run tests for runC by using command:
|
||||
### Running the test suite
|
||||
|
||||
`runc` currently supports running its test suite via Docker.
|
||||
To run the suite just type `make test`.
|
||||
|
||||
```bash
|
||||
# make test
|
||||
make test
|
||||
```
|
||||
|
||||
Note that test cases are run in Docker container, so you need to install
|
||||
`docker` first. And test requires mounting cgroups inside container, it's
|
||||
done by docker now, so you need a docker version newer than 1.8.0-rc2.
|
||||
There are additional make targets for running the tests outside of a container but this is not recommended as the tests are written with the expectation that they can write and remove anywhere.
|
||||
|
||||
You can also run specific test cases by:
|
||||
You can run a specific test case by setting the `TESTFLAGS` variable.
|
||||
|
||||
```bash
|
||||
# make test TESTFLAGS="-run=SomeTestFunction"
|
||||
```
|
||||
|
||||
### Using:
|
||||
## Using runc
|
||||
|
||||
To run a container with the id "test", execute `runc run` with the containers id as arg one
|
||||
in the bundle's root directory:
|
||||
### Creating an OCI Bundle
|
||||
|
||||
In order to use runc you must have your container in the format of an OCI bundle.
|
||||
If you have Docker installed you can use its `export` method to acquire a root filesystem from an existing Docker container.
|
||||
|
||||
```bash
|
||||
runc run test
|
||||
/ $ ps
|
||||
PID USER COMMAND
|
||||
1 daemon sh
|
||||
5 daemon sh
|
||||
/ $
|
||||
```
|
||||
# create the top most bundle directory
|
||||
mkdir /mycontainer
|
||||
cd /mycontainer
|
||||
|
||||
### OCI Container JSON Format:
|
||||
|
||||
OCI container JSON format is based on OCI [specs](https://github.com/opencontainers/runtime-spec).
|
||||
You can generate JSON files by using `runc spec`.
|
||||
It assumes that the file-system is found in a directory called
|
||||
`rootfs` and there is a user with uid and gid of `0` defined within that file-system.
|
||||
|
||||
### Examples:
|
||||
|
||||
#### Using a Docker image (requires version 1.3 or later)
|
||||
|
||||
To test using Docker's `busybox` image follow these steps:
|
||||
* Install `docker` and download the `busybox` image: `docker pull busybox`
|
||||
* Create a container from that image and export its contents in a directory:
|
||||
```
|
||||
# create the rootfs directory
|
||||
mkdir rootfs
|
||||
|
||||
# export busybox via Docker into the rootfs directory
|
||||
docker export $(docker create busybox) | tar -C rootfs -xvf -
|
||||
```
|
||||
* Create `config.json` by using `runc spec`.
|
||||
* Execute `runc run` and you should be placed into a shell where you can run `ps`:
|
||||
```
|
||||
$ runc run test
|
||||
/ # ps
|
||||
PID USER COMMAND
|
||||
1 root sh
|
||||
9 root ps
|
||||
|
||||
After a root filesystem is populated you just generate a spec in the format of a `config.json` file inside your bundle.
|
||||
`runc` provides a `spec` command to generate a base template spec that you are then able to edit.
|
||||
To find features and documentation for fields in the spec please refer to the [specs](https://github.com/opencontainers/runtime-spec) repository.
|
||||
|
||||
```bash
|
||||
runc spec
|
||||
```
|
||||
|
||||
#### Using runc with systemd
|
||||
### Running Containers
|
||||
|
||||
To use runc with systemd, you can create a unit file
|
||||
`/usr/lib/systemd/system/minecraft.service` as below (edit your
|
||||
own Description or WorkingDirectory or service name as you need).
|
||||
Assuming you have an OCI bundle from the previous step you can execute the container in two different ways.
|
||||
|
||||
```service
|
||||
The first way is to use the convenience command `run` that will handle creating, starting, and deleting the container after it exits.
|
||||
|
||||
```bash
|
||||
cd /mycontainer
|
||||
|
||||
runc run mycontainerid
|
||||
```
|
||||
|
||||
If you used the unmodified `runc spec` template this should give you a `sh` session inside the container.
|
||||
|
||||
The second way to start a container is using the specs lifecycle operations.
|
||||
This gives you move power of how the container is created and managed while it is running.
|
||||
This will also launch the container in the background so you will have to edit the `config.json` to remove the `terminal` setting for the simple examples here.
|
||||
Your process field in the `config.json` should look like this below with `"terminal": false` and `"args": ["sleep", "5"]`.
|
||||
|
||||
|
||||
```json
|
||||
"process": {
|
||||
"terminal": false,
|
||||
"user": {
|
||||
"uid": 0,
|
||||
"gid": 0
|
||||
},
|
||||
"args": [
|
||||
"sleep", "5"
|
||||
],
|
||||
"env": [
|
||||
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
|
||||
"TERM=xterm"
|
||||
],
|
||||
"cwd": "/",
|
||||
"capabilities": [
|
||||
"CAP_AUDIT_WRITE",
|
||||
"CAP_KILL",
|
||||
"CAP_NET_BIND_SERVICE"
|
||||
],
|
||||
"rlimits": [
|
||||
{
|
||||
"type": "RLIMIT_NOFILE",
|
||||
"hard": 1024,
|
||||
"soft": 1024
|
||||
}
|
||||
],
|
||||
"noNewPrivileges": true
|
||||
},
|
||||
```
|
||||
|
||||
Now we can go though the lifecycle operations in your shell.
|
||||
|
||||
|
||||
```bash
|
||||
cd /mycontainer
|
||||
|
||||
runc create mycontainerid
|
||||
|
||||
# view the container is created and in the "created" state
|
||||
runc list
|
||||
|
||||
# start the process inside the container
|
||||
runc start mycontainerid
|
||||
|
||||
# after 5 seconds view that the container has exited and is now in the stopped state
|
||||
runc list
|
||||
|
||||
# now delete the container
|
||||
runc delete mycontainerid
|
||||
```
|
||||
|
||||
This adds more complexity but allows higher level systems to manage runc and provides points in the containers creation to setup various settings after the container has created and/or before it is deleted.
|
||||
This is commonly used to setup the container's network stack after `create` but before `start` where the user's defined process will be running.
|
||||
|
||||
#### Supervisors
|
||||
|
||||
`runc` can be used with process supervisors and init systems to ensure that containers are restarted when they exit.
|
||||
An example systemd unit file looks something like this.
|
||||
|
||||
```systemd
|
||||
[Unit]
|
||||
Description=Minecraft Build Server
|
||||
Documentation=http://minecraft.net
|
||||
After=network.target
|
||||
Description=Start My Container
|
||||
|
||||
[Service]
|
||||
CPUQuota=200%
|
||||
MemoryLimit=1536M
|
||||
ExecStart=/usr/local/sbin/runc run minecraft
|
||||
Restart=on-failure
|
||||
WorkingDirectory=/containers/minecraftbuild
|
||||
Type=forking
|
||||
ExecStart=/usr/local/sbin/runc run -d --pid-file /run/mycontainerid.pid mycontainerid
|
||||
ExecStopPost=/usr/local/sbin/runc delete mycontainerid
|
||||
WorkingDirectory=/mycontainer
|
||||
PIDFile=/run/mycontainerid.pid
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
Make sure you have the bundle's root directory and JSON configs in
|
||||
your WorkingDirectory, then use systemd commands to start the service:
|
||||
|
||||
```bash
|
||||
systemctl daemon-reload
|
||||
systemctl start minecraft.service
|
||||
```
|
||||
|
||||
Note that if you use JSON configs by `runc spec`, you need to modify
|
||||
`config.json` and change `process.terminal` to false so runc won't
|
||||
create tty, because we can't set terminal from the stdin when using
|
||||
systemd service.
|
||||
|
|
|
|||
Loading…
Reference in New Issue