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

Document ns query string added to mirror requests

Browse Source 
This also adds clarification to the `server` field being used as a fallback.

Signed-off-by: James Lakin <james@jameslakin.co.uk>
This commit is contained in:
James Lakin
2023-12-09 11:09:16 +00:00
parent a68efb1bad
commit 6bb81ee577
1 changed files with 28 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/hosts.md
View File

@@ -80,12 +80,18 @@ The `/v2` portion of the pull request format shown above refers to the version o
distribution api. If not included in the pull request, `/v2` is added by default for all
clients compliant to the distribution specification linked above.
For example when pulling image_name:tag from a private registry named myregistry.io over
If a host is configured that's different to the registry host namespace (e.g. a mirror), then
containerd will append the registry host namespace to requests as a query parameter called `ns`.
For example when pulling `image_name:tag_name` from a private registry named `myregistry.io` over
port 5000:
```
pull myregistry.io:5000/image_name:tag
pull myregistry.io:5000/image_name:tag_name
```
The pull will resolve to `https://myregistry.io:5000/v2/image_name:tag`
The pull will resolve to `https://myregistry.io:5000/v2/image_name/manifests/tag_name`.
The same pull with a host configuration for `mymirror.io` will resolve to
`https://mymirror.io/v2/image_name/manifests/tag_name?ns=myregistry.io:5000`.
## Specifying Registry Credentials
@@ -162,6 +168,9 @@ server = "https://registry-1.docker.io" # Exclude this to not use upstream
### Setup Default Mirror for All Registries
This is an example of using a mirror regardless of the intended registry.
The upstream registry will automatically be used after all defined hosts have been tried.
```
$ tree /etc/containerd/certs.d
/etc/containerd/certs.d
@@ -169,12 +178,18 @@ $ tree /etc/containerd/certs.d
└── hosts.toml
$ cat /etc/containerd/certs.d/_default/hosts.toml
server = "https://registry.example.com"
[host."https://registry.example.com"]
capabilities = ["pull", "resolve"]
```
If you wish to ensure *only* the mirror is utilised and the upstream not consulted, set the mirror as the `server` instead of a host.
You may still specify additional hosts if you'd like to use other mirrors first.
```
$ cat /etc/containerd/certs.d/_default/hosts.toml
server = "https://registry.example.com"
```
### Bypass TLS Verification Example
To bypass the TLS verification for a private registry at `192.168.31.250:5000`
@@ -199,8 +214,14 @@ apply to the registry host namespace:
to the `hosts.toml` file.
## server field
`server` specifies the default server for this registry host namespace. When
`host`(s) are specified, the hosts are tried first in the order listed.
`server` specifies the default server for this registry host namespace.
When `host`(s) are specified, the hosts will be tried first in the order listed.
If all `host`(s) are tried then `server` will be used as a fallback.
If `server` is not specified then the image's registry host namespace will automatically be used.
```
server = "https://docker.io"
```