Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add registry proxying section #66

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+47 −24
Open

Add registry proxying section #66

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
71 changes: 47 additions & 24 deletions spec.md
View file
Open in desktop
Expand Up @@ -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)
- [Proxying](#registry-Proxying)
- [Detail](#detail)
- [Errors](#errors-2)
- [Base](#base)
Expand Down Expand Up @@ -840,6 +841,23 @@ 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 Proxying

A registry MAY operate as a proxy to another registry to delegate functionality or implement additional functionality.
An example of delegating functionality is proxying pull operations to another registry.
An example of adding functionality is implementing a pull-through cache of pulls to another registry.
When operating as a proxy, the `Host` header passed to the registry will be the host of the PROXY and NOT the host in the repository name used by the client.
A `ns` query parameter on pull operations is OPTIONAL, but when used specifies the host in a repository name used by a client.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is the key piece - we should document at least this query param

The host in the repository name SHOULD be the first component of the full repository name used by a client.
dmcgowan marked this conversation as resolved.
Show resolved Hide resolved
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.
This original host component used by the client is referred to as the source host in the API documentation.
A proxy registry MAY use the `ns` query parameter to resolve an upstream registry host.
A registry MAY choose to ignore the `ns` query parameter.

A client SHOULD be aware of whether a registry host is being used is a proxy, such as when the `ns` query parameter differs from the `Host` header.
A client SHOULD avoid sending `ns` query parameters to non-proxy registries.
A client SHOULD NOT unintentionally send authorization credentials for an upstream registry to a proxy registry.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop "unintentionally", replace with "... except when explicitly indicated (e.g. via configuration)"

Security sensitive requirements being labeled as SHOULD / SHOULD NOT, SHOULD also give you pause. Can this be upgraded to a MUST?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alternative wording:

Clients SHOULD NOT assume that proxy registries can handle authentication credentials issued by an upstream registry. Authentication credentials MUST NOT be sent to different hostnames except when prior knowledge or a configuration signal of authentication support is present.


## Detail

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

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 |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we lost these tables in the spec.md rewrite

|-----------------|--------|-------------------------------------------------------------------|
| `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 source host. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

should we clarify that if ns is not provided, there is a default assumption for the source host? or is that implied in the configuration of registry-proxy?


###### On Success: OK

Expand Down Expand Up @@ -1199,6 +1218,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. If 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 source host. |

###### On Success: OK

Expand Down Expand Up @@ -1377,12 +1397,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 source host. |

###### On Success: OK

Expand Down Expand Up @@ -2098,12 +2119,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 source host. |

###### On Success: OK

Expand Down Expand Up @@ -2348,13 +2370,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 source host. |

###### On Success: Partial Content

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quickly please!

Expand Down