github/containerd
4
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity

docs update for cri-containerd to cri move

Browse Source 
Signed-off-by: Mike Brown <brownwm@us.ibm.com>
This commit is contained in:
Mike Brown
2018-03-13 17:38:04 -05:00
parent 0c87604068
commit 0ee7614785
8 changed files with 104 additions and 147 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/architecture.md
View File

@@ -1,18 +1,18 @@
# Architecture of CRI-Containerd
This document describes the architecture of `cri-containerd`.
# Architecture of The CRI Plugin
This document describes the architecture of the `cri` plugin for `containerd`.
Cri-containerd is a containerd based implementation of Kubernetes [container runtime interface (CRI)](https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/apis/cri/runtime/v1alpha2/api.proto). It operates on the same node as the [Kubelet](https://kubernetes.io/docs/reference/generated/kubelet/) and [containerd](https://github.com/containerd/containerd). Layered between Kubernetes and containerd, cri-containerd handles all CRI service requests from the Kubelet and uses containerd to manage containers and container images.
This plugin is an implementation of Kubernetes [container runtime interface (CRI)](https://github.com/kubernetes/kubernetes/blob/master/pkg/kubelet/apis/cri/runtime/v1alpha2/api.proto). Containerd operates on the same node as the [Kubelet](https://kubernetes.io/docs/reference/generated/kubelet/). The `cri` plugin inside containerd handles all CRI service requests from the Kubelet and uses containerd internals to manage containers and container images.
Cri-containerd uses containerd to manage the full container lifecycle and all container images. As also shown below, cri-containerd manages pod networking via [CNI](https://github.com/containernetworking/cni) (another CNCF project).
The `cri` plugin uses containerd to manage the full container lifecycle and all container images. As also shown below, `cri` manages pod networking via [CNI](https://github.com/containernetworking/cni) (another CNCF project).
![architecture](./architecture.png)
Let's use an example to demonstrate how cri-containerd works for the case when Kubelet creates a single-container pod:
* Kubelet calls cri-containerd, via the CRI runtime service API, to create a pod;
* cri-containerd uses containerd to create and start a special [pause container](https://www.ianlewis.org/en/almighty-pause-container) (the sandbox container) and put that container inside the pod’s cgroups and namespace (steps omitted for brevity);
* cri-containerd configures the pod’s network namespace using CNI;
* Kubelet subsequently calls cri-containerd, via the CRI image service API, to pull the application container image;
* cri-containerd further uses containerd to pull the image if the image is not present on the node;
* Kubelet then calls cri-containerd, via the CRI runtime service API, to create and start the application container inside the pod using the pulled container image;
* cri-containerd finally calls containerd to create the application container, put it inside the pod’s cgroups and namespace, then to start the pod’s new application container.
Let's use an example to demonstrate how the `cri` plugin works for the case when Kubelet creates a single-container pod:
* Kubelet calls the `cri` plugin, via the CRI runtime service API, to create a pod;
* `cri` uses containerd internal to create and start a special [pause container](https://www.ianlewis.org/en/almighty-pause-container) (the sandbox container) and put that container inside the pod’s cgroups and namespace (steps omitted for brevity);
* `cri` configures the pod’s network namespace using CNI;
* Kubelet subsequently calls the `cri` plugin, via the CRI image service API, to pull the application container image;
* `cri` further uses containerd to pull the image if the image is not present on the node;
* Kubelet then calls `cri`, via the CRI runtime service API, to create and start the application container inside the pod using the pulled container image;
* `cri` finally uses containerd internal to create the application container, put it inside the pod’s cgroups and namespace, then to start the pod’s new application container.
After these steps, a pod and its corresponding application container is created and running.

0
docs/cri-containerd.png → docs/cri.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 22 KiB

After

Width:  |  Height:  |  Size: 22 KiB

62
docs/crictl.md
View File

@@ -1,17 +1,16 @@
CRICTL User Guide
=================
This document presumes you already have `containerd` and `cri-containerd`
installed and running.
This document presumes you already have `containerd` with the `cri` plugin installed and running.
This document is for developers who wish to debug, inspect, and manage their pods,
containers, and container images.
Before generating issues against this document, `containerd`, `cri-containerd`,
Before generating issues against this document, `containerd`, `containerd/cri`,
or `crictl` please make sure the issue has not already been submitted.
## Install crictl
If you have not already installed crictl please install the version compatible
with the `cri-containerd` you are using. If you are a user, your deployment
with the `cri` plugin you are using. If you are a user, your deployment
should have installed crictl for you. If not, get it from your release tarball.
If you are a developer the current version of crictl is specified [here](../hack/utils.sh).
A helper command has been included to install the dependencies at the right version:
@@ -23,8 +22,8 @@ so you don't have to repeatedly specify the runtime sock used to connect crictl
to the container runtime:
```console
$ cat /etc/crictl.yaml
runtime-endpoint: /var/run/cri-containerd.sock
image-endpoint: /var/run/cri-containerd.sock
runtime-endpoint: /run/containerd/containerd.sock
image-endpoint: /run/containerd/containerd.sock
timeout: 10
debug: true
```
@@ -95,20 +94,8 @@ $ crictl inspectp e1c8
* Other commands to manage the pod include `stops ID` to stop a running pod and
`rmp ID` to remove a pod sandbox.
## Create and Run a Container in a Pod Sandbox (using a config file)
## Create and Run a Container in the Pod Sandbox (using a config file)
```console
$ cat sandbox-config.json
{
"metadata": {
"name": "nginx-sandbox",
"namespace": "default",
"attempt": 1,
"uid": "hdishd83djaidwnduwk28bcsb"
},
"linux": {
}
}
$ cat container-config.json
{
"metadata": {
@@ -126,7 +113,7 @@ $ cat container-config.json
$ crictl create e1c83 container-config.json sandbox-config.json
0a2c761303163f2acaaeaee07d2ba143ee4cea7e3bde3d32190e2a36525c8a05
$ crictl ps
$ crictl ps -a
CONTAINER ID IMAGE CREATED STATE NAME ATTEMPT
0a2c761303163 docker.io/busybox 2 hours ago CONTAINER_CREATED busybox 0
$ crictl start 0a2c
@@ -145,8 +132,8 @@ bin dev etc home proc root sys tmp usr var
## Display Stats for the Container
```console
$ crictl stats
CONTAINER CPU % MEM DISK INODES
0a2c761303163f 0.00 991.2kB 16.38kB 6
CONTAINER CPU % MEM DISK INODES
0a2c761303163f 0.00 983kB 16.38kB 6
```
* Other commands to manage the container include `stop ID` to stop a running
container and `rm ID` to remove a container.
@@ -154,11 +141,11 @@ container and `rm ID` to remove a container.
```console
$ crictl version
Version: 0.1.0
RuntimeName: cri-containerd
RuntimeVersion: 1.0.0-alpha.1-167-g737efe7-dirty
RuntimeApiVersion: 0.0.0
RuntimeName: containerd
RuntimeVersion: 1.0.0-beta.1-186-gdd47a72-TEST
RuntimeApiVersion: v1alpha2
```
## Display Status & Configuration Information about Containerd & CRI-Containerd
## Display Status & Configuration Information about Containerd & The CRI Plugin
```console
$ crictl info
{
@@ -180,25 +167,30 @@ $ crictl info
},
"config": {
"containerd": {
"rootDir": "/var/lib/containerd",
"snapshotter": "overlayfs",
"endpoint": "/run/containerd/containerd.sock",
"runtime": "io.containerd.runtime.v1.linux"
},
"cni": {
"binDir": "/opt/cni/bin",
"confDir": "/etc/cni/net.d"
},
"socketPath": "/var/run/cri-containerd.sock",
"rootDir": "/var/lib/cri-containerd",
"registry": {
"mirrors": {
"docker.io": {
"endpoint": [
"https://registry-1.docker.io"
]
}
}
},
"streamServerPort": "10010",
"sandboxImage": "gcr.io/google_containers/pause:3.0",
"statsCollectPeriod": 10,
"oomScore": -999,
"enableProfiling": true,
"profilingPort": "10011",
"profilingAddress": "127.0.0.1"
}
"containerdRootDir": "/var/lib/containerd",
"containerdEndpoint": "/run/containerd/containerd.sock",
"rootDir": "/var/lib/containerd/io.containerd.grpc.v1.cri"
},
"golang": "go1.10"
}
```
## More Information

32
docs/installation.md
View File

@@ -9,12 +9,11 @@ For each release, we'll publish a release tarball. The release tarball contains
### Content
<!-- TODO(random-liu): Update the release tarball information -->
As shown below, the release tarball contains:
1) `cri-containerd`: cri-containerd binary.
2) `containerd`, `containerd-shim`, `containerd-stress`, `containerd-release`, `ctr`: binaries for containerd.
3) `runc`: runc binary.
4) `crictl`: command line tools for CRI container runtime.
5) `containerd.service`, `cri-containerd.service`: Systemd units for cri-containerd and containerd.
6) `/opt/cri-containerd/cluster/`: scripts for `kube-up.sh`.
1) `containerd`, `containerd-shim`, `containerd-stress`, `containerd-release`, `ctr`: binaries for containerd.
2) `runc`: runc binary.
3) `crictl`: command line tools for CRI container runtime.
4) `containerd.service`: Systemd unit for containerd.
5) `/opt/cri-containerd/cluster/`: scripts for `kube-up.sh`.
```console
$ tar -tf cri-containerd-1.0.0-beta.0.linux-amd64.tar.gz
./
@@ -40,29 +39,29 @@ $ tar -tf cri-containerd-1.0.0-beta.0.linux-amd64.tar.gz
./usr/local/bin/containerd-release
./usr/local/bin/containerd-shim
./usr/local/bin/ctr
./usr/local/bin/cri-containerd
./etc/
./etc/systemd/
./etc/systemd/system/
./etc/systemd/system/containerd.service
./etc/systemd/system/cri-containerd.service
./etc/crictl.yaml
```
### Binary Information
Information about the binaries in the release tarball:
| Binary Name | Support | OS | Architecture |
|:------------------------------:|:-----------------:|:-----:|:------------:|
| cri-containerd | seccomp, apparmor | linux | amd64 |
| runc | seccomp, apparmor | linux | amd64 |
| containerd/containerd-shim | overlay, btrfs | linux | amd64 |
| Binary Name | Support | OS | Architecture |
|:------------------------------:|:------------------:|:-----:|:------------:|
| containerd | seccomp, apparmor, | linux | amd64 |
| | overlay, btrfs | | |
| containerd-shim | overlay, btrfs | linux | amd64 |
| runc | seccomp, apparmor | linux | amd64 |
If you have other requirements for the binaries, e.g. selinux support, another architecture support etc., you need to build the binaries yourself following [the instructions](../README.md#getting-started-for-developers).
### Download
The release tarball could be downloaded from either of the following sources:
1. Release on github (see [here](https://github.com/containerd/cri-containerd/releases));
1. Release on github (see [here](https://github.com/containerd/cri/releases));
2. Release GCS bucket https://storage.googleapis.com/cri-containerd-release/.
## Step 0: Install Dependent Libraries
@@ -94,16 +93,15 @@ sudo tar -C / -xzf cri-containerd-${VERSION}.linux-amd64.tar.gz
sudo mkdir -p /opt/cni/bin/
sudo mkdir -p /etc/cni/net.d
sudo systemctl start containerd
sudo systemctl start cri-containerd
```
If you are not using systemd, please unpack all binaries into a directory in your `PATH`, and start `cri-containerd` and `containerd` as monitored long runnig services with the service manager you are using e.g. `supervisord`, `upstart` etc.
If you are not using systemd, please unpack all binaries into a directory in your `PATH`, and start `containerd` as monitored long running services with the service manager you are using e.g. `supervisord`, `upstart` etc.
## Step 3: Install Kubeadm, Kubelet and Kubectl
Follow [the instructions](https://kubernetes.io/docs/setup/independent/install-kubeadm/) to install kubeadm, kubelet and kubectl.
## Step 4: Create Systemd Drop-In for CRI-Containerd
Create the systemd drop-in file `/etc/systemd/system/kubelet.service.d/0-cri-containerd.conf`:
```
[Service]
Environment="KUBELET_EXTRA_ARGS=--container-runtime=remote --runtime-request-timeout=15m --container-runtime-endpoint=/var/run/cri-containerd.sock"
Environment="KUBELET_EXTRA_ARGS=--container-runtime=remote --runtime-request-timeout=15m --container-runtime-endpoint=/run/containerd/containerd.sock"
```
And reload systemd configuration:
```bash

45
docs/registry.md
View File

@@ -1,44 +1,9 @@
# Configure Image Registry for CRI-containerd
This document describes the methods to configure the image registry for `cri-containerd`.
# Configure Image Registry
This document describes the method to configure the image registry for `containerd` for use with the `cri` plugin.
In `cri-containerd`, `docker.io` is the default image registry. You can also set up other image registries similar to docker. `cri-containerd` provides two ways to set up the image registry.
With containerd, `docker.io` is the default image registry. You can also set up other image registries similar to docker.
<!-- TODO: will remove the document for standalone mode, ref `containerd/containerd#2120` -->
## Configure Image Registry with `--registry` Option
Start `cri-containerd` with `--registry` option like:
```bash
$ cri-containerd \
--registry=test.secure-registry.io=https://HostIP1:Port1 \
--registry=test.insecure-registry.io=http://HostIP2:Port2
```
If you want configure a insecure registry, you need set the endpoint with `http://` prefix. If you want to configure a secure registry, you need set the endpoint with `https://` prefix.
This method is only suitable for standalone mode.
## Configure Image Registry with Config File in Standalone Mode
In standalone mode, `cri-containerd` also specifies registris using the configuration file located in `/etc/cri-containerd/config.toml`. You can set registries in the configuration file as follows:
```toml
[registry.mirrors]
[registry.mirrors."docker.io"]
endpoint = ["https://registry-1.docker.io"]
[registry.mirrors."test.secure-registry.io"]
endpoint = ["https://HostIP1:Port1"]
[registry.mirrors."test.insecure-registry.io"]
endpoint = ["http://HostIP2:Port2"]
```
In the same way, the default configuration also can be generated by `cri-containerd default-config > /etc/cri-containerd/config.toml`.
The endpoint is a list that can contain multiple image registry URLs splited by commas.
After modify the config file, you need restart the `cri-containerd` service.
## Configure Image Registry with Config File in CRI Plugin Mode
Today, `cri-containerd` can also be used as a native plugin of `containerd`. In this mode, you should set registries in `/etc/containerd/config.toml` as follows:
To configure image registries create/modify the `/etc/containerd/config.toml` as follows:
```toml
[plugins.cri.registry.mirrors]
[plugins.cri.registry.mirrors."docker.io"]
@@ -51,6 +16,6 @@ Today, `cri-containerd` can also be used as a native plugin of `containerd`. In
The default configuration can be generated by `containerd config default > /etc/containerd/config.toml`.
The endpoint is a list that can contain multiple image registry URLs splited by commas.
The endpoint is a list that can contain multiple image registry URLs split by commas.
After modify the config file, you need restart the `containerd` service.

18
docs/testing.md
View File

@@ -1,7 +1,7 @@
CRI-Containerd Testing Guide
============================
This document assumes you have already setup the development environment (go, git, `cri-containerd` repo etc.).
CRI Plugin Testing Guide
========================
This document assumes you have already setup the development environment (go, git, `containerd/cri` repo etc.).
Before sending pull requests you should at least make sure your changes have passed code verification, unit, integration and CRI validation tests.
## Code Verification
Code verification includes lint, code formatting, boilerplate check etc.
@@ -14,23 +14,23 @@ make install.tools
make verify
```
## Unit Test
Run all unit tests in `cri-containerd` repo.
Run all unit tests in `containerd/cri` repo.
```bash
make test
```
## Integration Test
Run all integration tests in `cri-containerd` repo.
Run all integration tests in `containerd/cri` repo.
* [Install dependencies](../README.md#install-dependencies).
* Run integration test:
```bash
make test-integration
```
## CRI Validation Test
[CRI validation test](https://github.com/kubernetes/community/blob/master/contributors/devel/cri-validation.md) is a test framework for validating that a Container Runtime Interface (CRI) implementation such as `cri-containerd` meets all the requirements necessary to manage pod sandboxes, containers, images etc.
[CRI validation test](https://github.com/kubernetes/community/blob/master/contributors/devel/cri-validation.md) is a test framework for validating that a Container Runtime Interface (CRI) implementation such as containerd with the `cri` plugin meets all the requirements necessary to manage pod sandboxes, containers, images etc.
CRI validation test makes it possible to verify CRI conformance of `cri-containerd` without setting up Kubernetes components or running Kubernetes end-to-end tests.
CRI validation test makes it possible to verify CRI conformance of `containerd/cri` without setting up Kubernetes components or running Kubernetes end-to-end tests.
* [Install dependencies](../README.md#install-dependencies).
* Build `cri-containerd`:
* Build containerd with the `cri` plugin:
```bash
make
```