Add registry mirroring section

Define repository namespace query parameter for mirroring. Signed-off-by: Derek McGowan <[email protected]>
opencontainers · Jul 26, 2019 · e5df360 · e5df360
1 parent e815f30
commit e5df360
Showing 1 changed file with 44 additions and 24 deletions.
diff --git a/spec.md b/spec.md
@@ -33,6 +33,7 @@ The goal of this specification is to standardize container image distribution ba
   - [Listing Repositories](#listing-repositories)
   - [Listing Image Tags](#listing-image-tags)
   - [Deleting an Image](#deleting-an-image)
+  - [Mirroring](#registry-mirroring)
 - [Detail](#detail)
   - [Errors](#errors-2)
   - [Base](#base)
@@ -901,6 +902,20 @@ If the image had already been deleted or did not exist, a `404 Not Found` respon
 
 > for more details, see: [compatibility.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#backward-compatibility)
 
+### Registry Mirroring
+
+A registry MAY operate as a mirror for an upstream registry to support pull-through caching or proxying of fetch operations (such as fetching tags, manifest, or blobs).
+In this case, the `Host` HTTP Header passed to the mirror likely does not match the repository's namespace used by the client.
+The `ns` query parameter on fetch operations is OPTIONAL and specifies the repository's namespace used by a client.
+The repository's namespace is normally the first component of a full repository name used by a client.
+This namespace is often used to determine the registry host a client will interact with, however, a client MAY be configured to use a different host.
+A mirrored registry MAY use the `ns` query parameter to resolve an upstream registry host.
+A mirrored registry MAY choose to use a single upstream registry and ignore the `ns` query parameter.
+
+A client SHOULD be aware of whether a registry host being used is a mirror.
+A client SHOULD avoid sending `ns` query parameters to non-mirrored registries.
+A client SHOULD NOT send authorization credentials for an upstream registry to a mirrored registry.
+
 ## Detail
 
 > **Note**: This section is still under construction.
@@ -1081,11 +1096,12 @@ Return all tags for the repository
 
 The following parameters SHOULD be specified on the request:
 
-| Name            | Kind   | Description                                                    |
-|-----------------|--------|----------------------------------------------------------------|
-| `Host`          | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
-| `Authorization` | header | An RFC7235 compliant authorization header.                     |
-| `name`          | path   | Name of the target repository.                                 |
+| Name            | Kind   | Description                                                         |
+|-----------------|--------|---------------------------------------------------------------------|
+| `Host`          | header | Standard HTTP Host Header. SHOULD be set to the registry host.      |
+| `Authorization` | header | An RFC7235 compliant authorization header.                          |
+| `name`          | path   | Name of the target repository.                                      |
+| `ns`            | query  | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
 
 ###### On Success: OK
 
@@ -1260,6 +1276,7 @@ The following parameters SHOULD be specified on the request:
 | `name` | path  | Name of the target repository.                                                              |
 | `n`    | query | Limit the number of entries in each response. It not present, all entries will be returned. |
 | `last` | query | Result set will include values lexically after last.                                        |
+| `ns`   | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host.                         |
 
 ###### On Success: OK
 
@@ -1438,12 +1455,13 @@ Authorization: <scheme> <token>
 
 The following parameters SHOULD be specified on the request:
 
-| Name            | Kind   | Description                                                    |
-|-----------------|--------|----------------------------------------------------------------|
-| `Host`          | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
-| `Authorization` | header | An RFC7235 compliant authorization header.                     |
-| `name`          | path   | Name of the target repository.                                 |
-| `reference`     | path   | Tag or digest of the target manifest.                          |
+| Name            | Kind   | Description                                                         |
+|-----------------|--------|---------------------------------------------------------------------|
+| `Host`          | header | Standard HTTP Host Header. SHOULD be set to the registry host.      |
+| `Authorization` | header | An RFC7235 compliant authorization header.                          |
+| `name`          | path   | Name of the target repository.                                      |
+| `reference`     | path   | Tag or digest of the target manifest.                               |
+| `ns`            | query  | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
 
 ###### On Success: OK
 
@@ -2158,12 +2176,13 @@ Authorization: <scheme> <token>
 
 The following parameters SHOULD be specified on the request:
 
-| Name            | Kind   | Description                                                   |
-|-----------------|--------|---------------------------------------------------------------|
-| `Host`          | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
-| `Authorization` | header | An RFC7235 compliant authorization header.                    |
-| `name`          | path   | Name of the target repository.                                |
-| `digest`        | path   | Digest of desired blob.                                       |
+| Name            | Kind   | Description                                                         |
+|-----------------|--------|---------------------------------------------------------------------|
+| `Host`          | header | Standard HTTP Host Header.SHOULD be set to the registry host.       |
+| `Authorization` | header | An RFC7235 compliant authorization header.                          |
+| `name`          | path   | Name of the target repository.                                      |
+| `digest`        | path   | Digest of desired blob.                                             |
+| `ns`            | query  | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
 
 ###### On Success: OK
 
@@ -2408,13 +2427,14 @@ If the header `Accept-Range: bytes` is returned, range requests can be used to f
 
 The following parameters SHOULD be specified on the request:
 
-| Name            | Kind   | Description                                                   |
-|-----------------|--------|---------------------------------------------------------------|
-| `Host`          | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
-| `Authorization` | header | An RFC7235 compliant authorization header.                    |
-| `Range`         | header | HTTP Range header specifying blob chunk.                      |
-| `name`          | path   | Name of the target repository.                                |
-| `digest`        | path   | Digest of desired blob.                                       |
+| Name            | Kind   | Description                                                         |
+|-----------------|--------|---------------------------------------------------------------------|
+| `Host`          | header | Standard HTTP Host Header.SHOULD be set to the registry host.       |
+| `Authorization` | header | An RFC7235 compliant authorization header.                          |
+| `Range`         | header | HTTP Range header specifying blob chunk.                            |
+| `name`          | path   | Name of the target repository.                                      |
+| `digest`        | path   | Digest of desired blob.                                             |
+| `ns`            | query  | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
 
 ###### On Success: Partial Content