Skip to content

Commit 1e3a9a4

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

File tree

1 file changed

+45
-24
lines changed

1 file changed

+45
-24
lines changed

‎spec.md

+45-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+
- [Proxying](#registry-Proxying)
3637
- [Detail](#detail)
3738
- [Errors](#errors-2)
3839
- [Base](#base)
@@ -840,6 +841,21 @@ If the image had already been deleted or did not exist, a `404 Not Found` respon
840841

841842
> for more details, see: [compatibility.md](https://github.com/docker/distribution/blob/master/docs/spec/manifest-v2-2.md#backward-compatibility)
842843
844+
### Registry Proxying
845+
846+
A registry MAY operate as a proxy to another registry to support pull-through caching or proxying of pull operations (such as fetching tags, manifests, or blobs).
847+
In this case, the `Host` header passed to the proxy registry WILL NOT be the same as the host in the repository name used by the client.
848+
A `ns` query parameter on pull operations is OPTIONAL, but when used specifies the host in a repository name used by a client.
849+
This host component in a repository name SHOULD be the registry host a client considers the primary source for a repository, however, a client MAY be configured to use a different host.
850+
The host in the repository name SHOULD be the first component of the full repository name used by a client.
851+
This original host component used by the client is referred to as the source host in the API documentation.
852+
A proxy registry MAY use the `ns` query parameter to resolve an upstream registry host.
853+
A proxy registry MAY choose to ignore the `ns` query parameter.
854+
855+
A client SHOULD be aware of whether a registry host is being used is a proxy.
856+
A client SHOULD avoid sending `ns` query parameters to non-proxy registries.
857+
A client SHOULD NOT unintentionally send authorization credentials for an upstream registry to a proxy registry.
858+
843859
## Detail
844860

845861
> **Note**: This section is still under construction.
@@ -1019,11 +1035,12 @@ The implementation MAY impose a maximum limit and return a partial set with pagi
10191035

10201036
The following parameters SHOULD be specified on the request:
10211037

1022-
| Name | Kind | Description |
1023-
|-----------------|--------|----------------------------------------------------------------|
1024-
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1025-
| `Authorization` | header | An RFC7235 compliant authorization header. |
1026-
| `name` | path | Name of the target repository. |
1038+
| Name | Kind | Description |
1039+
|-----------------|--------|-------------------------------------------------------------------|
1040+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1041+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1042+
| `name` | path | Name of the target repository. |
1043+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
10271044

10281045
###### On Success: OK
10291046

@@ -1199,6 +1216,7 @@ The following parameters SHOULD be specified on the request:
11991216
| `name` | path | Name of the target repository. |
12001217
| `n` | query | Limit the number of entries in each response. If not present, all entries will be returned. |
12011218
| `last` | query | Result set will include values lexically after last. |
1219+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
12021220

12031221
###### On Success: OK
12041222

@@ -1377,12 +1395,13 @@ Authorization: <scheme> <token>
13771395

13781396
The following parameters SHOULD be specified on the request:
13791397

1380-
| Name | Kind | Description |
1381-
|-----------------|--------|----------------------------------------------------------------|
1382-
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1383-
| `Authorization` | header | An RFC7235 compliant authorization header. |
1384-
| `name` | path | Name of the target repository. |
1385-
| `reference` | path | Tag or digest of the target manifest. |
1398+
| Name | Kind | Description |
1399+
|-----------------|--------|-------------------------------------------------------------------|
1400+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1401+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1402+
| `name` | path | Name of the target repository. |
1403+
| `reference` | path | Tag or digest of the target manifest. |
1404+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
13861405

13871406
###### On Success: OK
13881407

@@ -2098,12 +2117,13 @@ Authorization: <scheme> <token>
20982117

20992118
The following parameters SHOULD be specified on the request:
21002119

2101-
| Name | Kind | Description |
2102-
|-----------------|--------|---------------------------------------------------------------|
2103-
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2104-
| `Authorization` | header | An RFC7235 compliant authorization header. |
2105-
| `name` | path | Name of the target repository. |
2106-
| `digest` | path | Digest of desired blob. |
2120+
| Name | Kind | Description |
2121+
|-----------------|--------|-------------------------------------------------------------------|
2122+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2123+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2124+
| `name` | path | Name of the target repository. |
2125+
| `digest` | path | Digest of desired blob. |
2126+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
21072127

21082128
###### On Success: OK
21092129

@@ -2348,13 +2368,14 @@ If the header `Accept-Range: bytes` is returned, range requests can be used to f
23482368

23492369
The following parameters SHOULD be specified on the request:
23502370

2351-
| Name | Kind | Description |
2352-
|-----------------|--------|---------------------------------------------------------------|
2353-
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2354-
| `Authorization` | header | An RFC7235 compliant authorization header. |
2355-
| `Range` | header | HTTP Range header specifying blob chunk. |
2356-
| `name` | path | Name of the target repository. |
2357-
| `digest` | path | Digest of desired blob. |
2371+
| Name | Kind | Description |
2372+
|-----------------|--------|-------------------------------------------------------------------|
2373+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2374+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2375+
| `Range` | header | HTTP Range header specifying blob chunk. |
2376+
| `name` | path | Name of the target repository. |
2377+
| `digest` | path | Digest of desired blob. |
2378+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
23582379

23592380
###### On Success: Partial Content
23602381

0 commit comments

Comments
 (0)