Skip to content

Commit aeee093

Browse files
mikebrowdmcgowan
mikebrow
authored and
dmcgowan
committed
adds description for hosts.toml
Signed-off-by: Mike Brown <[email protected]> (cherry picked from commit b59e297) Signed-off-by: Derek McGowan <[email protected]>
1 parent eebc914 commit aeee093

1 file changed

Lines changed: 273 additions & 0 deletions

File tree

‎docs/hosts.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
2+
# Registry Configuration - Introduction
3+
4+
Configuring registries will be done by specifying (optionally) a `hosts.toml` file for
5+
each desired registry host in a configuration directory. **Updates under this directory
6+
do not require restarting the containerd daemon.**
7+
8+
## Specifying the Configuration Directory
9+
10+
## Using Host Namespace Configs with CTR
11+
12+
When pulling via `ctr` use the `--hosts-dir` option:
13+
```
14+
ctr images pull --hosts-dir "/etc/containerd/certs.d"
15+
```
16+
17+
## CRI
18+
_The old CRI config pattern for specifying registry.mirrors and registry.configs has
19+
been **DEPRECATED**._ You should now point your registry `config_path` to path where your
20+
`hosts.toml` files are located.
21+
22+
Modify your `config.toml` (default location: `/etc/containerd/config.toml`) as follows:
23+
```toml
24+
[plugins."io.containerd.grpc.v1.cri".registry]
25+
config_path = "/etc/containerd/certs.d"
26+
```
27+
28+
## Support for Docker's Certificate File Pattern
29+
30+
If no hosts.toml configuration exists in the host directory, it will fallback to check
31+
certificate files based on [Docker's certificate file pattern](https://docs.docker.com/engine/reference/commandline/dockerd/#insecure-registries)
32+
(".crt" files for CA certificates and ".cert"/".key" files for client certificates).
33+
34+
## Registry Host Namespace
35+
36+
A registry host is the location where container images and artifacts are sourced. These
37+
registry hosts may be local or remote and are typically accessed via http/https using the
38+
[OCI distribution specification](https://github.com/opencontainers/distribution-spec/blob/main/spec.md).
39+
A registry mirror is not a registry host but these mirrors can also be used to pull content.
40+
Registry hosts are typically refered to by their internet domain names, aka. registry
41+
host names. For example, docker.io, quay.io, gcr.io, and ghcr.io.
42+
43+
A registry host namespace is, for the purpose of containerd registry configuration, a
44+
path to the `hosts.toml` file specified by the registry host name, or ip address, and an
45+
optional port identifier. When makeing a pull request for an image the format is
46+
typically as follows:
47+
```
48+
pull [registry_host_name|IP address][:port][/v2][/org_path]<image_name>[:tag|@DIGEST]
49+
```
50+
51+
The registry host namespace portion is `[registry_host_name|IP address][:port]`. Example
52+
tree for docker.io:
53+
54+
```
55+
$ tree /etc/containerd/certs.d
56+
/etc/containerd/certs.d
57+
└── docker.io
58+
└── hosts.toml
59+
```
60+
61+
The `/v2` portion of the pull request format shown above refers to the version of the
62+
distribution api. If not included in the pull request, `/v2` is added by default for all
63+
clients compliant to the distribution specification linked above.
64+
65+
For example when pulling image_name:tag from a private registry named myregistry.io over
66+
port 5000:
67+
```
68+
pull myregistry.io:5000/image_name:tag
69+
```
70+
The pull will resolve to `https://myregistry.io:5000/v2/image_name:tag`
71+
72+
# Registry Configuration - Examples
73+
74+
### Simple (default) Host Config for Docker
75+
Here is a simple example for a default registry hosts configuration. Set
76+
`config_path = "/etc/containerd/certs.d"` in your config.toml for containerd.
77+
Make a directory tree at the config path that includes `docker.io` as a directory
78+
representing the host namespace to be configured. Then add a `hosts.toml` file
79+
in the `docker.io` to configure the host namespace. It should look like this:
80+
81+
```
82+
$ tree /etc/containerd/certs.d
83+
/etc/containerd/certs.d
84+
└── docker.io
85+
└── hosts.toml
86+
87+
$ cat /etc/containerd/certs.d/docker.io/hosts.toml
88+
server = "https://docker.io"
89+
90+
[host."https://registry-1.docker.io"]
91+
capabilities = ["pull", "resolve"]
92+
```
93+
94+
### Setup a Local Mirror for Docker
95+
96+
```
97+
server = "https://registry-1.docker.io" # Exclude this to not use upstream
98+
99+
[host."https://public-mirror.example.com"]
100+
capabilities = ["pull"] # Requires less trust, won't resolve tag to digest from this host
101+
[host."https://docker-mirror.internal"]
102+
capabilities = ["pull", "resolve"]
103+
ca = "docker-mirror.crt" # Or absolute path /etc/containerd/certs.d/docker.io/docker-mirror.crt
104+
```
105+
106+
### Bypass TLS Verification Example
107+
108+
To bypass the TLS verification for a private registry at `192.168.31.250:5000`
109+
110+
Create a path and `hosts.toml` text at the path "/etc/containerd/certs.d/docker.io/hosts.toml" with following or similar contents:
111+
112+
```toml
113+
server = "https://registry-1.docker.io"
114+
115+
[host."http://192.168.31.250:5000"]
116+
capabilities = ["pull", "resolve", "push"]
117+
skip_verify = true
118+
```
119+
120+
# hosts.toml Content Description - Detail
121+
122+
For each registry host namespace directory in your registry `config_path` you may
123+
include a `hosts.toml` configuration file. The following root level toml fields
124+
apply to the registry host namespace:
125+
126+
*** Note: All paths specified in the `hosts.toml` file may be absolute or relative
127+
to the `hosts.toml` file.
128+
129+
## server field
130+
`server` specifies the default server for this registry host namespace. When
131+
`host`(s) are specified, the hosts are tried first in the order listed.
132+
```
133+
server = "https://docker.io"
134+
```
135+
136+
## capabilities field
137+
138+
`capabilities` is an optional setting for specifying what operations a host is
139+
capable of performing. Include only the values that apply.
140+
```
141+
capabilities = ["pull", "resolve", "push"]
142+
```
143+
144+
capabilities (or Host capabilities) represent the capabilities of the registry host.
145+
This also represents the set of operations for which the registry host may be trusted
146+
to perform.
147+
148+
For example, pushing is a capability which should only be performed on an upstream
149+
source, not a mirror.
150+
151+
Resolving (the process of converting a name into a digest)
152+
must be considered a trusted operation and only done by
153+
a host which is trusted (or more preferably by secure process
154+
which can prove the provenance of the mapping).
155+
156+
A public mirror should never be trusted to do a resolve action.
157+
158+
| Registry Type | Pull | Resolve | Push |
159+
|------------------|------|---------|------|
160+
| Public Registry | yes | yes | yes |
161+
| Private Registry | yes | yes | yes |
162+
| Public Mirror | yes | no | no |
163+
| Private Mirror | yes | yes | no |
164+
165+
## ca field
166+
167+
`ca` (Certificate Authority Certification) can be set to a path or an array of
168+
paths each pointing to a ca file for use in authenticating with the registry
169+
namespace.
170+
```
171+
ca = "/etc/certs/mirror.pem"
172+
```
173+
or
174+
```
175+
ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"]
176+
```
177+
178+
## client field
179+
180+
`client` certificates are configured as follows
181+
182+
`a path`:
183+
```
184+
client = "/etc/certs/client.pem"
185+
```
186+
187+
`an array of paths`:
188+
```
189+
client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"]
190+
```
191+
192+
`an array of pairs of paths`:
193+
```
194+
client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]]
195+
```
196+
197+
## skip_verify field
198+
199+
`skip_verify` set this flag to `true` to skip the registry certificate
200+
verification for this registry host namespace. (Defaults to `false`)
201+
```
202+
skip_verify = false
203+
```
204+
205+
## header fields (in the toml table format)
206+
207+
`[header]` contains some number of keys where each key is to one of a string or
208+
209+
`an array of strings as follows`:
210+
```
211+
[header]
212+
x-custom-1 = "custom header"
213+
```
214+
215+
`or`
216+
```
217+
[header]
218+
x-custom-1 = ["custom header part a","part b"]
219+
```
220+
221+
`or`
222+
```
223+
[header]
224+
x-custom-1 = "custom header",
225+
x-custom-1-2 = "another custom header"
226+
```
227+
228+
## host field(s) (in the toml table format)
229+
230+
`[host]."https://namespace"` and `[host].http://namespace` entries in the
231+
`hosts.toml` configuration are registry namespaces used in lieu of the default
232+
registry host namespace. These hosts are sometimes called mirrors because they
233+
may contain a copy of the container images and artifacts you are attempting to
234+
retrieve from the default registry. Each `host`/`mirror` namespace is also
235+
configured in much the same way as the default registry namespace. Notably the
236+
`server` is not specified in the `host` description because it is specified in
237+
the namespace. Here are a few rough examples configuring host mirror namespaces
238+
for this registry host namespace:
239+
```
240+
[host."https://mirror.registry"]
241+
capabilities = ["pull"]
242+
ca = "/etc/certs/mirror.pem"
243+
skip_verify = false
244+
[host."https://mirror.registry".header]
245+
x-custom-2 = ["value1", "value2"]
246+
247+
[host."https://mirror-bak.registry/us"]
248+
capabilities = ["pull"]
249+
skip_verify = true
250+
251+
[host."http://mirror.registry"]
252+
capabilities = ["pull"]
253+
254+
[host."https://test-1.registry"]
255+
capabilities = ["pull", "resolve", "push"]
256+
ca = ["/etc/certs/test-1-ca.pem", "/etc/certs/special.pem"]
257+
client = [["/etc/certs/client.cert", "/etc/certs/client.key"],["/etc/certs/client.pem", ""]]
258+
259+
[host."https://test-2.registry"]
260+
client = "/etc/certs/client.pem"
261+
262+
[host."https://test-3.registry"]
263+
client = ["/etc/certs/client-1.pem", "/etc/certs/client-2.pem"]
264+
```
265+
266+
**Further, recursion is not supported in the specification of host mirror
267+
namespaces in the hosts.toml file. Thus the following is not allowed/supported:**
268+
```
269+
[host."http://mirror.registry"]
270+
capabilities = ["pull"]
271+
[host."http://double-mirror.registry"]
272+
capabilities = ["pull"]
273+
```

0 commit comments

Comments
 (0)