Merge pull request containerd#9495 from jamesorlakin/chore/hosts-docu…

…mentation-ns

Document `ns` query string added to mirror requests

docs/hosts.md

@@ -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,19 +168,28 @@ 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
 └── _default
     └── 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"
 ```