github/containerd
4
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
parent 23978a158f 6bb81ee577
commit 2c8a996330
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 distribution api. If not included in the pull request, `/v2` is added by default for all
clients compliant to the distribution specification linked above. 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: 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 ## 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 ### 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 $ tree /etc/containerd/certs.d
/etc/containerd/certs.d /etc/containerd/certs.d
@@ -169,12 +178,18 @@ $ tree /etc/containerd/certs.d
└── hosts.toml └── hosts.toml
$ cat /etc/containerd/certs.d/_default/hosts.toml $ cat /etc/containerd/certs.d/_default/hosts.toml
server = "https://registry.example.com"
[host."https://registry.example.com"] [host."https://registry.example.com"]
capabilities = ["pull", "resolve"] 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 ### Bypass TLS Verification Example
To bypass the TLS verification for a private registry at `192.168.31.250:5000` 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. to the `hosts.toml` file.
## server field ## 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" server = "https://docker.io"
``` ```