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

Merge pull request #9495 from jamesorlakin/chore/hosts-documentation-ns

Browse Source 
Document `ns` query string added to mirror requests
This commit is contained in:
Derek McGowan 2023-12-15 19:54:00 +00:00 committed by GitHub
commit 2c8a996330
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 28 additions and 7 deletions
Show Stats 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"
```