Skip to content

Commit 658a97c

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

File tree

1 file changed

+45
-24
lines changed

1 file changed

+45
-24
lines changed

‎spec.md‎

Lines changed: 45 additions & 24 deletions
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)
@@ -901,6 +902,21 @@ 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 Proxying
906+
907+
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).
908+
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.
909+
A `ns` query parameter on pull operations is OPTIONAL, but when used specifies the host in a repository name used by a client.
910+
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.
911+
The host in the repository name SHOULD be the first component of the full repository name used by a client.
912+
This original host component used by the client is referred to as the source host in the API documentation.
913+
A proxy registry MAY use the `ns` query parameter to resolve an upstream registry host.
914+
A proxy registry MAY choose to ignore the `ns` query parameter.
915+
916+
A client SHOULD be aware of whether a registry host is being used is a proxy.
917+
A client SHOULD avoid sending `ns` query parameters to non-proxy registries.
918+
A client SHOULD NOT unintentionally send authorization credentials for an upstream registry to a proxy registry.
919+
904920
## Detail
905921

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

10821098
The following parameters SHOULD be specified on the request:
10831099

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. |
1100+
| Name | Kind | Description |
1101+
|-----------------|--------|-------------------------------------------------------------------|
1102+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1103+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1104+
| `name` | path | Name of the target repository. |
1105+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
10891106

10901107
###### On Success: OK
10911108

@@ -1260,6 +1277,7 @@ The following parameters SHOULD be specified on the request:
12601277
| `name` | path | Name of the target repository. |
12611278
| `n` | query | Limit the number of entries in each response. It not present, all entries will be returned. |
12621279
| `last` | query | Result set will include values lexically after last. |
1280+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
12631281

12641282
###### On Success: OK
12651283

@@ -1438,12 +1456,13 @@ Authorization: <scheme> <token>
14381456

14391457
The following parameters SHOULD be specified on the request:
14401458

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. |
1459+
| Name | Kind | Description |
1460+
|-----------------|--------|-------------------------------------------------------------------|
1461+
| `Host` | header | Standard HTTP Host Header. SHOULD be set to the registry host. |
1462+
| `Authorization` | header | An RFC7235 compliant authorization header. |
1463+
| `name` | path | Name of the target repository. |
1464+
| `reference` | path | Tag or digest of the target manifest. |
1465+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
14471466

14481467
###### On Success: OK
14491468

@@ -2158,12 +2177,13 @@ Authorization: <scheme> <token>
21582177

21592178
The following parameters SHOULD be specified on the request:
21602179

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. |
2180+
| Name | Kind | Description |
2181+
|-----------------|--------|-------------------------------------------------------------------|
2182+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2183+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2184+
| `name` | path | Name of the target repository. |
2185+
| `digest` | path | Digest of desired blob. |
2186+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
21672187

21682188
###### On Success: OK
21692189

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

24092429
The following parameters SHOULD be specified on the request:
24102430

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. |
2431+
| Name | Kind | Description |
2432+
|-----------------|--------|-------------------------------------------------------------------|
2433+
| `Host` | header | Standard HTTP Host Header.SHOULD be set to the registry host. |
2434+
| `Authorization` | header | An RFC7235 compliant authorization header. |
2435+
| `Range` | header | HTTP Range header specifying blob chunk. |
2436+
| `name` | path | Name of the target repository. |
2437+
| `digest` | path | Digest of desired blob. |
2438+
| `ns` | query | (OPTIONAL) Namespace of repository. SHOULD be set to source host. |
24182439

24192440
###### On Success: Partial Content
24202441

0 commit comments

Comments
 (0)