registry.md
1
# Configure Image Registry
3
This document describes the method to configure the image registry for `containerd` for use with the `cri` plugin.
5
> **_NOTE:_** registry.mirrors and registry.configs as previously described in this document
6
> have been DEPRECATED. As described in [the cri config](./config.md#registry-configuration) you
7
> should now use the following configuration
8
+ In containerd 2.x
10
[plugins."io.containerd.cri.v1.images".registry]
11
config_path = "/etc/containerd/certs.d"
12
```
13
+ In containerd 1.x
14
```toml
15
[plugins."io.containerd.grpc.v1.cri".registry]
16
config_path = "/etc/containerd/certs.d"
17
```
19
If no registry-specific options are set, `config_path` will default to
20
`/etc/containerd/certs.d:/etc/docker/certs.d`, which enables compatibility with
21
[the docker method of adding registry configuration](https://docs.docker.com/registry/insecure/#use-self-signed-certificates).
22
23
## Configure Registry Credentials
24
25
> **_NOTE:_** registry.configs.*.auth is DEPRECATED and will NOT have an equivalent way to store
26
> unencrypted secrets in the host configuration files. However, it will not be removed until
27
> a suitable secret management alternative is available as a plugin. It remains supported
28
> in 1.x releases, including the 1.6 LTS release.
30
To configure a credential for a specific registry, create/modify the
31
`/etc/containerd/config.toml` as follows:
33
+ In containerd 2.x
35
# explicitly use v3 config format
36
version = 3
38
# The registry host has to be a domain name or IP. Port number is also
39
# needed if the default HTTPS or HTTP port is not used.
40
[plugins."io.containerd.cri.v1.images".registry.configs."gcr.io".auth]
41
username = ""
42
password = ""
43
auth = ""
44
identitytoken = ""
46
+ In containerd 1.x
47
```toml
48
# explicitly use v2 config format
49
version = 2
50
51
# The registry host has to be a domain name or IP. Port number is also
52
# needed if the default HTTPS or HTTP port is not used.
53
[plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io".auth]
54
username = ""
55
password = ""
56
auth = ""
57
identitytoken = ""
58
```
60
The meaning of each field is the same with the corresponding field in `.docker/config.json`.
61
62
Please note that auth config passed by CRI takes precedence over this config.
63
The registry credential in this config will only be used when auth config is
64
not specified by Kubernetes via CRI.
65
66
After modifying this config, you need to restart the `containerd` service.
68
### Configure Registry Credentials Example - GCR with Service Account Key Authentication
70
If you don't already have Google Container Registry (GCR) set up then you need to do the following steps:
72
* Create a Google Cloud Platform (GCP) account and project if not already created (see [GCP getting started](https://cloud.google.com/gcp/getting-started))
73
* Enable GCR for your project (see [Quickstart for Container Registry](https://cloud.google.com/container-registry/docs/quickstart))
74
* For authentication to GCR: Create [service account and JSON key](https://cloud.google.com/container-registry/docs/advanced-authentication#json-key)
75
* The JSON key file needs to be downloaded to your system from the GCP console
76
* 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))
77
78
Refer to [Pushing and pulling images](https://cloud.google.com/container-registry/docs/pushing-and-pulling) for detailed information on the above steps.
80
> Note: The JSON key file is a multi-line file and it can be cumbersome to use the contents as a key outside of the 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`
82
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
83
pushing an image to it as follows:
84
85
```console
86
docker login -u _json_key -p "$(cat key.json)" gcr.io
87
88
docker pull busybox
89
90
docker tag busybox gcr.io/your-gcp-project-id/busybox
91
92
docker push gcr.io/your-gcp-project-id/busybox
93
94
docker logout gcr.io
95
```
96
97
Now that you know you can access your GCR from your terminal, it is now time to try out containerd.
98
99
Edit the containerd config (default location is at `/etc/containerd/config.toml`)
100
to add your JSON key for `gcr.io` domain image pull
101
requests:
102
+ In containerd 2.x
103
```toml
104
version = 3
105
106
[plugins."io.containerd.cri.v1.images".registry]
107
[plugins."io.containerd.cri.v1.images".registry.mirrors]
108
[plugins."io.containerd.cri.v1.images".registry.mirrors."docker.io"]
109
endpoint = ["https://registry-1.docker.io"]
110
[plugins."io.containerd.cri.v1.images".registry.mirrors."gcr.io"]
111
endpoint = ["https://gcr.io"]
112
[plugins."io.containerd.cri.v1.images".registry.configs]
113
[plugins."io.containerd.cri.v1.images".registry.configs."gcr.io".auth]
114
username = "_json_key"
115
password = 'paste output from jq'
116
```
117
+ In containerd 1.x
118
```toml
119
version = 2
120
121
[plugins."io.containerd.grpc.v1.cri".registry]
122
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
123
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
124
endpoint = ["https://registry-1.docker.io"]
125
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
126
endpoint = ["https://gcr.io"]
127
[plugins."io.containerd.grpc.v1.cri".registry.configs]
128
[plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io".auth]
129
username = "_json_key"
130
password = 'paste output from jq'
131
```
133
> Note: `username` of `_json_key` signifies that JSON key authentication will be used.
135
Restart containerd:
136
137
```console
138
service containerd restart
139
```
140
141
Pull an image from your GCR with `crictl`:
142
143
```console
144
$ sudo crictl pull gcr.io/your-gcp-project-id/busybox
145
146
DEBU[0000] get image connection
147
DEBU[0000] connect using endpoint 'unix:///run/containerd/containerd.sock' with '3s' timeout
148
DEBU[0000] connected successfully using endpoint: unix:///run/containerd/containerd.sock
149
DEBU[0000] PullImageRequest: &PullImageRequest{Image:&ImageSpec{Image:gcr.io/your-gcr-instance-id/busybox,},Auth:nil,SandboxConfig:nil,}
150
DEBU[0001] PullImageResponse: &PullImageResponse{ImageRef:sha256:78096d0a54788961ca68393e5f8038704b97d8af374249dc5c8faec1b8045e42,}
151
Image is up to date for sha256:78096d0a54788961ca68393e5f8038704b97d8af374249dc5c8faec1b8045e42
152
```
153
154
---
155
156
NOTE: The configuration syntax used in this doc is in version 2 which is the recommended since `containerd` 1.3. For the previous config format you can reference [https://github.com/containerd/cri/blob/release/1.2/docs/registry.md](https://github.com/containerd/cri/blob/release/1.2/docs/registry.md).