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

Merge branch 'master' into update-config-syntax

Browse Source
This commit is contained in:
Mike Brown
2020-09-24 15:58:39 -05:00
committed by GitHub
parent ef7f327f2a b3678ddad2
commit 2c2dd59f32
1681 changed files with 144960 additions and 140070 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/config.md
View File

@@ -10,6 +10,7 @@ The explanation and default value of each configuration item are as follows:
```toml
# Use config version 2 to enable new configuration fields.
# Config file is parsed as version 1 by default.
# Version 2 uses long plugin names, i.e. "io.containerd.grpc.v1.cri" vs "cri".
version = 2
# The 'plugins."io.containerd.grpc.v1.cri"' table contains all of the server options.
@@ -34,8 +35,12 @@ version = 2
# enable_selinux indicates to enable the selinux support.
enable_selinux = false
# selinux_category_range allows the upper bound on the category range to be set.
# if not specified or set to 0, defaults to 1024 from the selinux package.
selinux_category_range = 1024
# sandbox_image is the image used by sandbox container.
sandbox_image = "k8s.gcr.io/pause:3.1"
sandbox_image = "k8s.gcr.io/pause:3.2"
# stats_collect_period is the period (in seconds) of snapshots stats collection.
stats_collect_period = 10
@@ -44,6 +49,16 @@ version = 2
# It generates a self-sign certificate unless the following x509_key_pair_streaming are both set.
enable_tls_streaming = false
# tolerate_missing_hugetlb_controller if set to false will error out on create/update
# container requests with huge page limits if the cgroup controller for hugepages is not present.
# This helps with supporting Kubernetes <=1.18 out of the box. (default is `true`)
tolerate_missing_hugetlb_controller = true
# ignore_image_defined_volumes ignores volumes defined by the image. Useful for better resource
# isolation, security and early detection of issues in the mount configuration when using
# ReadOnlyRootFilesystem since containers won't silently mount a temporary volume.
ignore_image_defined_volumes = false
# 'plugins."io.containerd.grpc.v1.cri".x509_key_pair_streaming' contains a x509 valid key pair to stream with tls.
[plugins."io.containerd.grpc.v1.cri".x509_key_pair_streaming]
# tls_cert_file is the filepath to the certificate paired with the "tls_key_file"
@@ -77,6 +92,10 @@ version = 2
# when using containerd with Kubernetes <=1.11.
disable_proc_mount = false
# unsetSeccompProfile is the profile containerd/cri will use if the provided seccomp profile is
# unset (`""`) for a container (default is `unconfined`)
unset_seccomp_profile = ""
# 'plugins."io.containerd.grpc.v1.cri".containerd' contains config related to containerd
[plugins."io.containerd.grpc.v1.cri".containerd]
@@ -87,6 +106,15 @@ version = 2
# This only works for runtime type "io.containerd.runtime.v1.linux".
no_pivot = false
# disable_snapshot_annotations disables to pass additional annotations (image
# related information) to snapshotters. These annotations are required by
# stargz snapshotter (https://github.com/containerd/stargz-snapshotter)
disable_snapshot_annotations = false
# discard_unpacked_layers allows GC to remove layers from the content store after
# successfully unpacking these layers to the snapshotter.
discard_unpacked_layers = false
# default_runtime_name is the default runtime name to use.
default_runtime_name = "runc"
@@ -130,6 +158,13 @@ version = 2
# i.e pass host devices through to privileged containers.
privileged_without_host_devices = false
# base_runtime_spec is a file path to a JSON file with the OCI spec that will be used as the base spec that all
# container's are created from.
# Use containerd's `ctr oci spec > /etc/containerd/cri-base.json` to output initial spec file.
# Spec files are loaded at launch, so containerd daemon must be restared on any changes to refresh default specs.
# Still running containers and restarted containers will still be using the original spec from which that container was created.
base_runtime_spec = ""
# 'plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options' is options specific to
# "io.containerd.runc.v1" and "io.containerd.runc.v2". Its corresponding options type is:
# https://github.com/containerd/containerd/blob/v1.3.2/runtime/v2/runc/options/oci.pb.go#L26 .
@@ -197,10 +232,36 @@ version = 2
# 'plugins."io.containerd.grpc.v1.cri".registry' contains config related to the registry
[plugins."io.containerd.grpc.v1.cri".registry]
# 'plugins."io.containerd.grpc.v1.cri.registry.headers sets the http request headers to send for all registry requests
[plugins."io.containerd.grpc.v1.cri".registry.headers]
Foo = ["bar"]
# 'plugins."io.containerd.grpc.v1.cri".registry.mirrors' are namespace to mirror mapping for all namespaces.
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://registry-1.docker.io", ]
# 'plugins."io.containerd.grpc.v1.cri".image_decryption' contains config related
# to handling decryption of encrypted container images.
[plugins."io.containerd.grpc.v1.cri".image_decryption]
# key_model defines the name of the key model used for how the cri obtains
# keys used for decryption of encrypted container images.
# The [decryption document](https://github.com/containerd/cri/blob/master/docs/decryption.md)
# contains additional information about the key models available.
#
# Set of available string options: {"", "node"}
# Omission of this field defaults to the empty string "", which indicates no key model,
# disabling image decryption.
#
# In order to use the decryption feature, additional configurations must be made.
# The [decryption document](https://github.com/containerd/cri/blob/master/docs/decryption.md)
# provides information of how to set up stream processors and the containerd imgcrypt decoder
# with the appropriate key models.
#
# Additional information:
# * Stream processors: https://github.com/containerd/containerd/blob/master/docs/stream_processors.md
# * Containerd imgcrypt: https://github.com/containerd/imgcrypt
key_model = "node"
```
## Untrusted Workload

31
docs/crictl.md
View File

@@ -38,35 +38,50 @@ $ crictl inspecti busybox
... displays information about the image.
```
***Note:*** If you get an error similar to the following when running a `crictl`
command (and your containerd instance is already running):
```console
crictl info
FATA[0000] getting status of runtime failed: rpc error: code = Unimplemented desc = unknown service runtime.v1alpha2.RuntimeService
```
This could be that you are using an incorrect containerd configuration (maybe
from a Docker install). You will need to update your containerd configuration
to the containerd instance that you are running. One way of doing this is as
follows:
```console
$ mv /etc/containerd/config.toml /etc/containerd/config.bak
$ containerd config default > /etc/containerd/config.toml
```
## Directly Load a Container Image
Another way to load an image into the container runtime is with the load
command. With the load command you inject a container image into the container
runtime from a file. First you need to create a container image tarball. For
example to create an image tarball for a pause container using Docker:
```console
$ docker pull k8s.gcr.io/pause-amd64:3.1
3.1: Pulling from pause-amd64
$ docker pull k8s.gcr.io/pause-amd64:3.2
3.2: Pulling from pause-amd64
67ddbfb20a22: Pull complete
Digest: sha256:59eec8837a4d942cc19a52b8c09ea75121acc38114a2c68b98983ce9356b8610
Status: Downloaded newer image for k8s.gcr.io/pause-amd64:3.1
$ docker save k8s.gcr.io/pause-amd64:3.1 -o pause.tar
Status: Downloaded newer image for k8s.gcr.io/pause-amd64:3.2
$ docker save k8s.gcr.io/pause-amd64:3.2 -o pause.tar
```
Then use [`ctr`](https://github.com/containerd/containerd/blob/master/docs/man/ctr.1.md)
to load the container image into the container runtime:
```console
# The cri plugin uses the "k8s.io" containerd namespace.
$ sudo ctr -n=k8s.io images import pause.tar
Loaded image: k8s.gcr.io/pause-amd64:3.1
Loaded image: k8s.gcr.io/pause-amd64:3.2
```
List images and inspect the pause image:
```console
$ sudo crictl images
IMAGE TAG IMAGE ID SIZE
docker.io/library/busybox latest f6e427c148a76 728kB
k8s.gcr.io/pause-amd64 3.1 da86e6ba6ca19 746kB
k8s.gcr.io/pause-amd64 3.2 da86e6ba6ca19 746kB
$ sudo crictl inspecti da86e6ba6ca19
... displays information about the pause image.
$ sudo crictl inspecti k8s.gcr.io/pause-amd64:3.1
$ sudo crictl inspecti k8s.gcr.io/pause-amd64:3.2
... displays information about the pause image.
```
@@ -186,7 +201,7 @@ $ crictl info
}
},
"streamServerPort": "10010",
"sandboxImage": "k8s.gcr.io/pause:3.1",
"sandboxImage": "k8s.gcr.io/pause:3.2",
"statsCollectPeriod": 10,
"containerdRootDir": "/var/lib/containerd",
"containerdEndpoint": "unix:///run/containerd/containerd.sock",

46
docs/decryption.md Normal file
View File

@@ -0,0 +1,46 @@
# Configure Image Decryption
This document describes the method to configure encrypted container image decryption for `containerd` for use with the `cri` plugin.
## Encrypted Container Images
Encrypted container images are OCI images which contain encrypted blobs. These encrypted images can be created through the use of [containerd/imgcrypt project](https://github.com/containerd/imgcrypt). To decrypt these images, the `containerd` runtime uses information passed from the `cri` such as keys, options and encryption metadata.
## The "node" Key Model
Encryption ties trust to an entity based on the model in which a key is associated with it. We call this the key model. One such usecase is when we want to tie the trust of a key to the node in a cluster. In this case, we call it the "node" or "host" Key Model. Future work will include more key models to facilitate other trust associations (i.e. for multi-tenancy).
### "node" Key Model Usecase
In this model encryption is tied to worker nodes. The usecase here revolves around the idea that an image should be decryptable only on trusted host. Using this model, various node based technologies which help bootstrap trust in worker nodes and perform secure key distribution (i.e. TPM, host attestation, secure/measured boot). In this scenario, runtimes are capable of fetching the necessary decryption keys. An example of this is using the [`--decryption-keys-path` flag in imgcrypt](https://github.com/containerd/imgcrypt).
### Configuring image decryption for "node" key model
The default configuration does not handle decrypting encrypted container images.
An example for configuring the "node" key model for container image decryption:
Configure `cri` to enable decryption with "node" key model
```toml
[plugins."io.containerd.grpc.v1.cri".image_decryption]
key_model = "node"
```
Configure `containerd` daemon [`stream_processors`](https://github.com/containerd/containerd/blob/master/docs/stream_processors.md) to handle the
encrypted mediatypes.
```toml
[stream_processors]
[stream_processors."io.containerd.ocicrypt.decoder.v1.tar.gzip"]
accepts = ["application/vnd.oci.image.layer.v1.tar+gzip+encrypted"]
returns = "application/vnd.oci.image.layer.v1.tar+gzip"
path = "/usr/local/bin/ctd-decoder"
args = ["--decryption-keys-path", "/keys"]
[stream_processors."io.containerd.ocicrypt.decoder.v1.tar"]
accepts = ["application/vnd.oci.image.layer.v1.tar+encrypted"]
returns = "application/vnd.oci.image.layer.v1.tar"
path = "/usr/local/bin/ctd-decoder"
args = ["--decryption-keys-path", "/keys"]
```
In this example, container image decryption is set to use the "node" key model. In addition, the decryption [`stream_processors`](https://github.com/containerd/containerd/blob/master/docs/stream_processors.md) are configured as specified in [containerd/imgcrypt project](https://github.com/containerd/imgcrypt), with the additional field `--decryption-keys-path` configured to specify where decryption keys are located locally in the node.
After modify this config, you need restart the `containerd` service.

62
docs/registry.md
View File

@@ -10,6 +10,8 @@ With containerd, `docker.io` is the default image registry. You can also set up
To configure image registries create/modify the `/etc/containerd/config.toml` as follows:
```toml
# Config file is parsed as version 1 by default.
# To use the long form of plugin names set "version = 2"
# explicitly use v2 config format
version = 2
@@ -36,7 +38,7 @@ As an example, for the image `gcr.io/library/busybox:latest`, the endpoints are:
* `gcr.io` is configured: endpoints for `gcr.io` + default endpoint `https://gcr.io/v2`.
* `*` is configured, and `gcr.io` is not: endpoints for `*` + default
endpoint `https://gcr.io/v2`.
* None of above is configured: default endpoint `https:/gcr.io/v2`.
* None of above is configured: default endpoint `https://gcr.io/v2`.
After modify this config, you need restart the `containerd` service.
@@ -103,3 +105,61 @@ The registry credential in this config will only be used when auth config is
not specified by Kubernetes via CRI.
After modify this config, you need restart the `containerd` service.
### Configure Registry Credentials Example - GCR with _json_key Authentication
Create a gcp account with gcr, do all the steps to enable receiving a
pushed image for a gcr instance, including the generation and download of a
new _json_key (for a new service account user.) To make sure your
gcr registry is working with _json_key authentication let's login and
push an image to your gcr instance: *This step is not necessary if you have
already pushed an image to your gcr instance.*
```bash
$ docker login -u _json_key -p "$(cat key.json)" gcr.io
$ docker push gcr.io/your-gcr-instance-id/busybox
$ docker logout gcr.io
```
Generate a single line for the _json_key file that you downloaded:
```bash
jq -c . key.json
```
Edit the containerd config (default location is at /etc/containerd/config.toml)
to add your _json_key authentication for gcr.io domain image pull
requests:
```
version = 2
[plugins."io.containerd.grpc.v1.cri".registry]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
endpoint = ["https://registry-1.docker.io"]
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
endpoint = ["https://gcr.io"]
[plugins."io.containerd.grpc.v1.cri".registry.configs]
[plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io".auth]
username = "_json_key"
password = 'paste output from jq'
```
Restart containerd
```bash
$ service containerd restart
```
Pull an image from your gcr instance with crictl:
```bash
$ sudo crictl pull gcr.io/your-gcr-instance-id/busybox
DEBU[0000] get image connection
DEBU[0000] connect using endpoint 'unix:///run/containerd/containerd.sock' with '3s' timeout
DEBU[0000] connected successfully using endpoint: unix:///run/containerd/containerd.sock
DEBU[0000] PullImageRequest: &PullImageRequest{Image:&ImageSpec{Image:gcr.io/your-gcr-instance-id/busybox,},Auth:nil,SandboxConfig:nil,}
DEBU[0001] PullImageResponse: &PullImageResponse{ImageRef:sha256:78096d0a54788961ca68393e5f8038704b97d8af374249dc5c8faec1b8045e42,}
Image is up to date for sha256:78096d0a54788961ca68393e5f8038704b97d8af374249dc5c8faec1b8045e42
```

3
docs/testing.md
View File

@@ -4,11 +4,12 @@ This document assumes you have already setup the development environment (go, gi
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.
Code verification includes lint, and code formatting check etc.
* Install tools used by code verification:
```bash
make install.tools
```
***Note:*** Some make actions (like `install.tools`) use the user's `GOPATH` and will otherwise not work when it is not set. Other make actions override it by setting it to a temporary directory for release build and testing purposes.
* Run code verification:
```bash
make verify