Skip to content

Commit 42589cd

Browse files
dmcgowandmcgowan
committed
Add registry mirroring section
Define repository namespace query parameter for mirroring. Signed-off-by: Derek McGowan <[email protected]>
1 parent e815f30 commit 42589cd

File tree

1 file changed

+44
-24
lines changed

1 file changed

+44
-24
lines changed

‎spec.md

+44-24
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ The goal of this specification is to standardize container image distribution ba
3333
- [Listing Repositories](#listing-repositories)
3434
- [Listing Image Tags](#listing-image-tags)
3535
- [Deleting an Image](#deleting-an-image)
36+
- [Mirroring](#registry-mirroring)
3637
- [Detail](#detail)
3738
- [Errors](#errors-2)
3839
- [Base](#base)
@@ -901,6 +902,20 @@ If the image had already been deleted or did not exist, a `404 Not Found` respon
901902

902903
> for more details, see: [compatibility.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#backward-compatibility)
903904
905+
### Registry Mirroring
906+
907+
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).
908+
In this case, the `Host` HTTP Header passed to the mirror likely does not match the repository's namespace used by the client.
909+
The `ns` query parameter on fetch operations is OPTIONAL and specifies the repository's namespace used by a client.
910+
The repository's namespace is normally the first component of a full repository name used by a client.
911+
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.
912+
A mirrored registry MAY use the `ns` query parameter to resolve an upstream registry host.
913+
A mirrored registry MAY choose to use a single upstream registry and ignore the `ns` query parameter.
914+
915+
A client SHOULD be aware of whether a registry host being used is a mirror.
916+
A client SHOULD avoid sending `ns` query parameters to non-mirrored registries.
917+
A client SHOULD NOT send authorization credentials for upstream registries to mirrored registries.
918+
904919
## Detail
905920

906921
> **Note**: This section is still under construction.
@@ -1081,11 +1096,12 @@ Return all tags for the repository
10811096

10821097
The following parameters SHOULD be specified on the request:
10831098

1084-
| Name | Kind | Description |
1085-
|-----------------|--------|----------------------------------------------------------------|
1086-
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1087-
| `Authorization` | header | An RFC7235 compliant authorization header. |
1088-
| `name` | path | Name of the target repository. |
1099+
| Name | Kind | Description |
1100+
|-----------------|--------|---------------------------------------------------------------------|
1101+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1102+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1103+
| `name` | path | Name of the target repository. |
1104+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
10891105

10901106
###### On Success: OK
10911107

@@ -1260,6 +1276,7 @@ The following parameters SHOULD be specified on the request:
12601276
| `name` | path | Name of the target repository. |
12611277
| `n` | query | Limit the number of entries in each response. It not present, all entries will be returned. |
12621278
| `last` | query | Result set will include values lexically after last. |
1279+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
12631280

12641281
###### On Success: OK
12651282

@@ -1438,12 +1455,13 @@ Authorization: <scheme> <token>
14381455

14391456
The following parameters SHOULD be specified on the request:
14401457

1441-
| Name | Kind | Description |
1442-
|-----------------|--------|----------------------------------------------------------------|
1443-
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1444-
| `Authorization` | header | An RFC7235 compliant authorization header. |
1445-
| `name` | path | Name of the target repository. |
1446-
| `reference` | path | Tag or digest of the target manifest. |
1458+
| Name | Kind | Description |
1459+
|-----------------|--------|---------------------------------------------------------------------|
1460+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1461+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1462+
| `name` | path | Name of the target repository. |
1463+
| `reference` | path | Tag or digest of the target manifest. |
1464+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
14471465

14481466
###### On Success: OK
14491467

@@ -2158,12 +2176,13 @@ Authorization: <scheme> <token>
21582176

21592177
The following parameters SHOULD be specified on the request:
21602178

2161-
| Name | Kind | Description |
2162-
|-----------------|--------|---------------------------------------------------------------|
2163-
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2164-
| `Authorization` | header | An RFC7235 compliant authorization header. |
2165-
| `name` | path | Name of the target repository. |
2166-
| `digest` | path | Digest of desired blob. |
2179+
| Name | Kind | Description |
2180+
|-----------------|--------|---------------------------------------------------------------------|
2181+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2182+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2183+
| `name` | path | Name of the target repository. |
2184+
| `digest` | path | Digest of desired blob. |
2185+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
21672186

21682187
###### On Success: OK
21692188

@@ -2408,13 +2427,14 @@ If the header `Accept-Range: bytes` is returned, range requests can be used to f
24082427

24092428
The following parameters SHOULD be specified on the request:
24102429

2411-
| Name | Kind | Description |
2412-
|-----------------|--------|---------------------------------------------------------------|
2413-
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2414-
| `Authorization` | header | An RFC7235 compliant authorization header. |
2415-
| `Range` | header | HTTP Range header specifying blob chunk. |
2416-
| `name` | path | Name of the target repository. |
2417-
| `digest` | path | Digest of desired blob. |
2430+
| Name | Kind | Description |
2431+
|-----------------|--------|---------------------------------------------------------------------|
2432+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2433+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2434+
| `Range` | header | HTTP Range header specifying blob chunk. |
2435+
| `name` | path | Name of the target repository. |
2436+
| `digest` | path | Digest of desired blob. |
2437+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to mirrored host. |
24182438

24192439
###### On Success: Partial Content
24202440

0 commit comments

Comments
 (0)