mirror of
https://github.com/aljazceru/kata-containers.git
synced 2025-12-27 02:54:27 +01:00
6107694930
As agreed in [the kata containers API design](https://github.com/kata-containers/documentation/blob/master/design/kata-api-design.md), we need to rename pod notion to sandbox. The patch is a bit big but the actual change is done through the script: ``` sed -i -e 's/pod/sandbox/g' -e 's/Pod/Sandbox/g' -e 's/POD/SB/g' ``` The only expections are `pod_sandbox` and `pod_container` annotations, since we already pushed them to cri shims, we have to use them unchanged. Fixes: #199 Signed-off-by: Peng Tao <bergwolf@gmail.com>
241 lines
8.4 KiB
Markdown
241 lines
8.4 KiB
Markdown
# virtc
|
|
|
|
`virtc` is a simple command-line tool that serves to demonstrate typical usage of the virtcontainers API.
|
|
This is example software; unlike other projects like runc, runv, or rkt, virtcontainers is not a full container runtime.
|
|
|
|
## Virtc example
|
|
|
|
Here we explain how to use the sandbox and container API from `virtc` command line.
|
|
|
|
### Prepare your environment
|
|
|
|
#### Get your kernel
|
|
|
|
_Fedora_
|
|
```
|
|
$ sudo -E dnf config-manager --add-repo http://download.opensuse.org/repositories/home:clearlinux:preview:clear-containers-2.1/Fedora_25/home:clearlinux:preview:clear-containers-2.1.repo
|
|
$ sudo dnf install linux-container
|
|
```
|
|
|
|
_Ubuntu_
|
|
```
|
|
$ sudo sh -c "echo 'deb http://download.opensuse.org/repositories/home:/clearlinux:/preview:/clear-containers-2.1/xUbuntu_16.10/ /' >> /etc/apt/sources.list.d/cc-oci-runtime.list"
|
|
$ sudo apt install linux-container
|
|
```
|
|
|
|
#### Get your image
|
|
|
|
Retrieve a recent Clear Containers image to make sure it contains a recent version of hyperstart agent.
|
|
|
|
To download and install the latest image:
|
|
|
|
```
|
|
$ latest_version=$(curl -sL https://download.clearlinux.org/latest)
|
|
$ curl -LO "https://download.clearlinux.org/current/clear-${latest_version}-containers.img.xz"
|
|
$ unxz clear-${latest_version}-containers.img.xz
|
|
$ sudo mkdir -p /usr/share/clear-containers/
|
|
$ sudo install --owner root --group root --mode 0644 clear-${latest_version}-containers.img /usr/share/clear-containers/
|
|
$ sudo ln -fs /usr/share/clear-containers/clear-${latest_version}-containers.img /usr/share/clear-containers/clear-containers.img
|
|
```
|
|
|
|
#### Get virtc
|
|
|
|
_Download virtcontainers project_
|
|
```
|
|
$ go get github.com/kata-containers/runtime/virtcontainers
|
|
```
|
|
|
|
_Build and setup your environment_
|
|
```
|
|
$ cd $GOPATH/src/github.com/kata-containers/runtime/virtcontainers
|
|
$ go build -o virtc hack/virtc/main.go
|
|
$ sudo -E bash ./utils/virtcontainers-setup.sh
|
|
```
|
|
|
|
`virtcontainers-setup.sh` setup your environment performing different tasks. Particularly, it creates a __busybox__ bundle, and it creates CNI configuration files needed to run `virtc` with CNI plugins.
|
|
|
|
### Get cc-proxy (optional)
|
|
|
|
If you plan to start `virtc` with the hyperstart agent, you will have to use [cc-proxy](https://github.com/clearcontainers/proxy) as a proxy, meaning you have to perform extra steps to setup your environment.
|
|
|
|
```
|
|
$ go get github.com/clearcontainers/proxy
|
|
$ cd $GOPATH/src/github.com/clearcontainers/proxy
|
|
$ make
|
|
$ sudo make install
|
|
```
|
|
If you want to see the traces from the proxy when `virtc` will run, you can manually start it with appropriate debug level:
|
|
|
|
```
|
|
$ sudo /usr/libexec/clearcontainers/cc-proxy -v 3
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
I0410 08:58:49.058881 5384 proxy.go:521] listening on /var/run/clearcontainers/proxy.sock
|
|
I0410 08:58:49.059044 5384 proxy.go:566] proxy started
|
|
```
|
|
The proxy socket specified in the example log output has to be used as `virtc`'s `--proxy-url` option.
|
|
|
|
### Get cc-shim (optional)
|
|
|
|
If you plan to start `virtc` with the hyperstart agent (implying the use of `cc-proxy` as a proxy), you will have to rely on [cc-shim](https://github.com/clearcontainers/shim) in order to interact with the process running inside your container.
|
|
First, you will have to perform extra steps to setup your environment.
|
|
|
|
```
|
|
$ go get github.com/clearcontainers/shim
|
|
$ cd $GOPATH/src/github.com/clearcontainers/shim && ./autogen.sh
|
|
$ make
|
|
$ sudo make install
|
|
```
|
|
|
|
The shim will be installed at the following location: `/usr/libexec/clear-containers/cc-shim`. There will be three cases where you will be able to interact with your container's process through `cc-shim`:
|
|
|
|
_Start a new container_
|
|
|
|
```
|
|
# ./virtc container start --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
_Execute a new process on a running container_
|
|
```
|
|
# ./virtc container enter --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
_Start a sandbox with container(s) previously created_
|
|
```
|
|
# ./virtc sandbox start --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
Notice that in both cases, the `--sandbox-id` and `--id` options have been defined when previously creating a sandbox and a container.
|
|
|
|
### Run virtc
|
|
|
|
All following commands __MUST__ be run as root. By default, and unless you decide to modify it and rebuild it, `virtc` starts empty sandboxes (no container started).
|
|
|
|
#### Run a new sandbox (Create + Start)
|
|
```
|
|
# ./virtc sandbox run --agent="hyperstart" --network="CNI" --proxy="ccProxy" --proxy-url="unix:///var/run/clearcontainers/proxy.sock" --shim="ccShim" --shim-path="/usr/libexec/cc-shim"
|
|
```
|
|
#### Create a new sandbox
|
|
```
|
|
# ./virtc sandbox run --agent="hyperstart" --network="CNI" --proxy="ccProxy" --proxy-url="unix:///var/run/clearcontainers/proxy.sock" --shim="ccShim" --shim-path="/usr/libexec/cc-shim"
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 created
|
|
```
|
|
|
|
#### Start an existing sandbox
|
|
```
|
|
# ./virtc sandbox start --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 started
|
|
```
|
|
|
|
#### Stop an existing sandbox
|
|
```
|
|
# ./virtc sandbox stop --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 stopped
|
|
```
|
|
|
|
#### Get the status of an existing sandbox and its containers
|
|
```
|
|
# ./virtc sandbox status --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following (assuming the sandbox has been started):
|
|
```
|
|
SB ID STATE HYPERVISOR AGENT
|
|
306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 running qemu hyperstart
|
|
|
|
CONTAINER ID STATE
|
|
```
|
|
|
|
#### Delete an existing sandbox
|
|
```
|
|
# ./virtc sandbox delete --id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Sandbox 306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 deleted
|
|
```
|
|
|
|
#### List all existing sandboxes
|
|
```
|
|
# ./virtc sandbox list
|
|
```
|
|
This should generate that kind of output
|
|
```
|
|
SB ID STATE HYPERVISOR AGENT
|
|
306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 running qemu hyperstart
|
|
92d73f74-4514-4a0d-81df-db1cc4c59100 running qemu hyperstart
|
|
7088148c-049b-4be7-b1be-89b3ae3c551c ready qemu hyperstart
|
|
6d57654e-4804-4a91-b72d-b5fe375ed3e1 ready qemu hyperstart
|
|
```
|
|
|
|
#### Create a new container
|
|
```
|
|
# ./virtc container create --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 --rootfs="/tmp/bundles/busybox/rootfs" --cmd="/bin/ifconfig" --console="/dev/pts/30"
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Container 1 created
|
|
```
|
|
__Note:__ The option `--console` can be any existing console.
|
|
Don't try to provide `$(tty)` as it is your current console, and you would not be
|
|
able to get your console back as the shim would be listening to this indefinitely.
|
|
Instead, you would prefer to open a new shell and get the `$(tty)` from this shell.
|
|
That way, you make sure you have a dedicated input/output terminal.
|
|
|
|
#### Start an existing container
|
|
```
|
|
# ./virtc container start --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Container 1 started
|
|
```
|
|
|
|
#### Run a new process on an existing container
|
|
```
|
|
# ./virtc container enter --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8 --cmd="/bin/ps" --console="/dev/pts/30"
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Container 1 entered
|
|
```
|
|
__Note:__ The option `--console` can be any existing console.
|
|
Don't try to provide `$(tty)` as it is your current console, and you would not be
|
|
able to get your console back as the shim would be listening to this indefinitely.
|
|
Instead, you would prefer to open a new shell and get the `$(tty)` from this shell.
|
|
That way, you make sure you have a dedicated input/output terminal.
|
|
|
|
#### Stop an existing container
|
|
```
|
|
# ./virtc container stop --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Container 1 stopped
|
|
```
|
|
|
|
#### Delete an existing container
|
|
```
|
|
# ./virtc container delete --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following:
|
|
```
|
|
Container 1 deleted
|
|
```
|
|
|
|
#### Get the status of an existing container
|
|
```
|
|
# ./virtc container status --id=1 --sandbox-id=306ecdcf-0a6f-4a06-a03e-86a7b868ffc8
|
|
```
|
|
This will generate output similar to the following (assuming the container has been started):
|
|
```
|
|
CONTAINER ID STATE
|
|
1 running
|
|
```
|