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

Updates to the image registry doc

Browse Source 
Signed-off-by: Martin Hickey <martin.hickey@ie.ibm.com>
This commit is contained in:
Martin Hickey 2020-09-30 14:31:03 +00:00
parent 2e3bebb297
commit 70a56ae327
1 changed files with 48 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

75
docs/registry.md
View File

@ -1,4 +1,5 @@
# Configure Image Registry # Configure Image Registry
This document describes the method to configure the image registry for `containerd` for use with the `cri` plugin. This document describes the method to configure the image registry for `containerd` for use with the `cri` plugin.
NOTE: The configuration syntax used in this doc is in version 2 which is the NOTE: The configuration syntax used in this doc is in version 2 which is the
@ -6,9 +7,11 @@ recommended since `containerd` 1.3. If your configuration is still in version 1,
you can replace `"io.containerd.grpc.v1.cri"` with `cri`. you can replace `"io.containerd.grpc.v1.cri"` with `cri`.
## Configure Registry Endpoint ## Configure Registry Endpoint
With containerd, `docker.io` is the default image registry. You can also set up other image registries similar to docker. With containerd, `docker.io` is the default image registry. You can also set up other image registries similar to docker.
To configure image registries create/modify the `/etc/containerd/config.toml` as follows: To configure image registries create/modify the `/etc/containerd/config.toml` as follows:
```toml ```toml
# Config file is parsed as version 1 by default. # Config file is parsed as version 1 by default.
# To use the long form of plugin names set "version = 2" # To use the long form of plugin names set "version = 2"
@ -35,6 +38,7 @@ that if the default registry endpoint is not already specified in the endpoint l
tried at the end with scheme `https` and path `v2`, e.g. `https://gcr.io/v2` for `gcr.io`. tried at the end with scheme `https` and path `v2`, e.g. `https://gcr.io/v2` for `gcr.io`.
As an example, for the image `gcr.io/library/busybox:latest`, the endpoints are: 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`. * `gcr.io` is configured: endpoints for `gcr.io` + default endpoint `https://gcr.io/v2`.
* `*` is configured, and `gcr.io` is not: endpoints for `*` + default * `*` is configured, and `gcr.io` is not: endpoints for `*` + default
endpoint `https://gcr.io/v2`. endpoint `https://gcr.io/v2`.
@ -43,9 +47,11 @@ As an example, for the image `gcr.io/library/busybox:latest`, the endpoints are:
After modify this config, you need restart the `containerd` service. After modify this config, you need restart the `containerd` service.
## Configure Registry TLS Communication ## Configure Registry TLS Communication
`cri` plugin also supports configuring TLS settings when communicating with a registry. `cri` plugin also supports configuring TLS settings when communicating with a registry.
To configure the TLS settings for a specific registry, create/modify the `/etc/containerd/config.toml` as follows: To configure the TLS settings for a specific registry, create/modify the `/etc/containerd/config.toml` as follows:
```toml ```toml
# explicitly use v2 config format # explicitly use v2 config format
version = 2 version = 2
@ -58,7 +64,7 @@ version = 2
key_file = "key.pem" key_file = "key.pem"
``` ```
In the config example shown above, TLS mutual authentication will be used for communications with the registry endpoint located at https://my.custom.registry. In the config example shown above, TLS mutual authentication will be used for communications with the registry endpoint located at <https://my.custom.registry>.
`ca_file` is file name of the certificate authority (CA) certificate used to authenticate the x509 certificate/key pair specified by the files respectively pointed to by `cert_file` and `key_file`. `ca_file` is file name of the certificate authority (CA) certificate used to authenticate the x509 certificate/key pair specified by the files respectively pointed to by `cert_file` and `key_file`.
`cert_file` and `key_file` are not needed when TLS mutual authentication is unused. `cert_file` and `key_file` are not needed when TLS mutual authentication is unused.
@ -86,6 +92,7 @@ version = 2
To configure a credential for a specific registry, create/modify the To configure a credential for a specific registry, create/modify the
`/etc/containerd/config.toml` as follows: `/etc/containerd/config.toml` as follows:
```toml ```toml
# explicitly use v2 config format # explicitly use v2 config format
version = 2 version = 2
@ -98,40 +105,51 @@ version = 2
auth = "" auth = ""
identitytoken = "" identitytoken = ""
``` ```
The meaning of each field is the same with the corresponding field in `.docker/config.json`. The meaning of each field is the same with the corresponding field in `.docker/config.json`.
Please note that auth config passed by CRI takes precedence over this config. Please note that auth config passed by CRI takes precedence over this config.
The registry credential in this config will only be used when auth config is The registry credential in this config will only be used when auth config is
not specified by Kubernetes via CRI. not specified by Kubernetes via CRI.
After modify this config, you need restart the `containerd` service. After modifying this config, you need to restart the `containerd` service.
### Configure Registry Credentials Example - GCR with _json_key Authentication ### Configure Registry Credentials Example - GCR with service account key authentication
Create a gcp account with gcr, do all the steps to enable receiving a If you don't already have Google Container Registry (GCR) set-up then you need to do the following steps:
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 * Create a Google Cloud Platform (GCP) account and project if not already created (see [GCP getting started](https://cloud.google.com/gcp/getting-started))
$ docker login -u _json_key -p "$(cat key.json)" gcr.io * Enable GCR for your project (see [Quickstart for Container Registry](https://cloud.google.com/container-registry/docs/quickstart))
$ docker push gcr.io/your-gcr-instance-id/busybox * For authentication to GCR: Create [service account and JSON key](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key)
$ docker logout gcr.io * The JSON key file needs to be downloaded to your system from the GCP console
* For access to the GCR storage: Add service account to the GCR storage bucket with storage admin access rights (see [Granting permissions](https://cloud.google.com/container-registry/docs/access-control#grant-bucket))
Refer to [Pushing and pulling images](https://cloud.google.com/container-registry/docs/pushing-and-pulling) for detailed information on the above steps.
> Note: The JSON key file is a multi-line file and can be cumbersome to use its contents as a key outside of file. It is worthwhile generating a single line format output of the file. One way of doing this is using the `jq` tool as follows: `jq -c . key.json`
It is beneficial to first confirm that from your terminal you can authenticate with your GCR and have access to the storage before hooking it into containerd. This can be verified by performing a login to your GCR and
pushing an image to it as follows:
```console
docker login -u _json_key -p "$(cat key.json)" gcr.io
docker pull busybox
docker tag busybox gcr.io/your-gcp-project-id/busybox
docker push gcr.io/your-gcp-project-id/busybox
docker logout gcr.io
``` ```
Generate a single line for the _json_key file that you downloaded: Now that you know you can access your GCR from your terminal, it is now time to try out containerd.
```bash Edit the containerd config (default location is at `/etc/containerd/config.toml`)
jq -c . key.json to add your JSON key for `gcr.io` domain image pull
```
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: requests:
``` ```toml
version = 2 version = 2
[plugins."io.containerd.grpc.v1.cri".registry] [plugins."io.containerd.grpc.v1.cri".registry]
@ -146,16 +164,19 @@ version = 2
password = 'paste output from jq' password = 'paste output from jq'
``` ```
Restart containerd > Note: `username` of `_json_key` signifies that JSON key authentication will be used.
```bash Restart containerd:
$ service containerd restart
```console
service containerd restart
``` ```
Pull an image from your gcr instance with crictl: Pull an image from your GCR with `crictl`:
```console
$ sudo crictl pull gcr.io/your-gcp-project-id/busybox
```bash
$ sudo crictl pull gcr.io/your-gcr-instance-id/busybox
DEBU[0000] get image connection DEBU[0000] get image connection
DEBU[0000] connect using endpoint 'unix:///run/containerd/containerd.sock' with '3s' timeout 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] connected successfully using endpoint: unix:///run/containerd/containerd.sock