Skip to content

Commit a44d24e

Browse files
vbattsstevvooeAaron Gouletmikebrowsamuelkarp
committed
extensions: pulling in latest feedback
Co-authored-by: Stephen Day <stephen.day@getcruise.com> Co-authored-by: Aaron Goulet <gluten@amazon.com> Co-authored-by: Lachie Evenson <laevenso@microsoft.com Co-authored-by: Mike Brown <brownwm@us.ibm.com> Co-authored-by: Samuel Karp <me@samuelkarp.com> Co-authored-by: Sajay Antony <sajaya@microsoft.com> Signed-off-by: Vincent Batts <vbatts@hashbangbash.com>
1 parent 83a789c commit a44d24e

File tree

5 files changed

+208
-139
lines changed

5 files changed

+208
-139
lines changed

‎ext/README.md

-81
This file was deleted.

‎ext/ext.md

-58
This file was deleted.

‎extensions/README.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
tags: oci,distribution
3+
breaks: false
4+
---
5+
6+
# Extensions API for Distribution
7+
8+
Extensions, in general, to the distribution-spec API are allowed by the distribution-spec, with certain reservations disclosed herein.
9+
This document outlines a path for registry implementations and clients to iterate on new APIs, establish them, and propose them to OCI for canonical reference.
10+
11+
The basis of the Extension API (`_oci`) should be emulated for all extensions.
12+
13+
## Table
14+
15+
_notice_: All new `/extensions/_<extention>.md` docs MUST be added to this table.
16+
17+
| Extension | Summary |
18+
|:------------------------:|:----------------------------------------------------:|
19+
| [`_oci`](./_oci.md) | Extensions discovering extensions on registry server |
20+
| `_catalog` | Reserved prior extension |
21+
22+
## Name
23+
24+
Extension names MUST be unique.
25+
Extensions recorded in this distribution-spec are considered canonical definitions.
26+
27+
Extensions are specified by extension name (`<extension>`) aligning with the project, followed by the `<component>`, and last by by the `<module>`.
28+
This constitutes the URI segments of the extension endpoint.
29+
Additional options may be passed as parameters to the endpoint.
30+
31+
```http
32+
_<extension>/<component>/<module>[?<key>=<value>&...]
33+
```
34+
35+
The values of `<extension>`, `<component>`, and `<module>` MUST conform to the following regular expression:
36+
37+
`[a-z0-9]+([._-][a-z0-9]+)`
38+
39+
Note: the leading `_` on the extension is a prefix before this regular expression.
40+
41+
### Registry-Level Extensions
42+
43+
Registry-level extensions are nested under `/v2`.
44+
45+
```http
46+
GET /v2/_<extension>/<component>/<module>[?<key>=<value>&...]
47+
```
48+
49+
A contrived example of a search extension may be of the form `/v2/_oci/catalog/search?pattern=foo?n=10`
50+
51+
### Repository-Level Extensions
52+
53+
Repository-level extension endpoints are scoped under a repository name.
54+
55+
Repository-level extensions follow the same naming rules as the [registry-level endpoints](#registry-level-extensions).
56+
57+
```http
58+
GET /v2/<name>/_<extension>/<component>/<module>[?<key>=<value>&...]
59+
```
60+
61+
### Reserved Namespaces
62+
63+
As of current, `_oci` and `_catalog` are considered as reserved namespaces and cannot be used by other extensions.
64+
65+
### Versioning
66+
67+
Data payloads being exchanged from extensions SHOULD handle versioned data structures this with `Accepts` and `Content-type` HTTP headers (LINK TO RFC).
68+
69+
If an extension has fundamentally changed enough, then it SHOULD be introduced as a new `<component>` and/or `<component>/<module>`.
70+
Whether or not there is versioning built into those names is up to the extension maintainer.
71+
72+
## Filename
73+
74+
Extension definitions SHOULD be placed under `./extensions/` in the specification repository.
75+
Extension files SHOULD follow the `_<extension>.md` pattern.
76+
Refer [_oci.md](./_oci.md) for more details.
77+
78+
## Detail
79+
80+
Extensions details MAY describe more endpoints and APIs that it MAY support.
81+
It is also recommended to call out error codes encountered and enumerated as in the
82+
in the following table:
83+
84+
| Code | Message | Description |
85+
|---------------------|----------------------|-----------------------------------------------------|
86+
| `EXTENSION_UNKNOWN` | Extension is unknown | This error MAY be returned when a extension is unknown to the registry in a specified repository. This can be returned with a standard get or if a manifest references an unknown layer during upload. |
87+
88+
## Pagination
89+
90+
Extensions implementing pagination and SHOULD align with the [pagination](./spec.md#pagination) specification.
91+
92+
Extension MAY provide enumeration without lexical ordering and in this case, it is not required to support the `last` parameter.
93+
Clients are NOT RECOMMENDED to construct the `link` and SHOULD treat the URL as opaque.
94+
95+
## Prior Art
96+
97+
When considering the proposal structure for these extensions, the following processes were considered:
98+
99+
* [Python PEP](https://www.python.org/dev/peps/)
100+
* [Kubernetes KEP](https://github.com/kubernetes/enhancements/tree/master/keps)

‎extensions/_oci.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# _oci Extension Endpoints
2+
3+
## Summary
4+
5+
This base extension namespace for OCI namespaced extension endpoints.
6+
7+
## Reference Explanation
8+
9+
### Component: `ext`
10+
11+
This component is for endpoints relating to extensions on the registry API being queried.
12+
13+
#### Module: `discover`
14+
15+
This endpoint may be queried to discover extensions available on this registry API.
16+
17+
Registry-level extensions may be discovered with a standard `GET` as follows.
18+
19+
```HTTP
20+
GET /v2/_oci/ext/discover
21+
```
22+
23+
Repository-level extensions may be discovered with a standard GET as follows.
24+
25+
```HTTP
26+
GET /v2/{name}/_oci/ext/discover
27+
```
28+
29+
The base extension returns an array of supported extensions with details of the endpoints as shown below.
30+
31+
```HTTP
32+
200 OK
33+
Content-Length: <length>
34+
Content-Type: application/json
35+
36+
{
37+
"extensions": [
38+
{
39+
"name": "_<extension>",
40+
"description": "",
41+
"url": "..."
42+
}
43+
]
44+
}
45+
```
46+
47+
### *Extensions* Property Descriptions
48+
49+
- **`extensions`** *array of extension objects*, REQUIRED
50+
51+
This property contains a list of supported extension endpoints.
52+
53+
- **`name`** *string*, REQUIRED
54+
55+
The name of the extension (i.e. '`_oci`') as it will appear in the URL path.
56+
57+
- **`url`** *string*, REQUIRED
58+
59+
URL link to the documentation defining this extension and its endpoints.
60+
61+
- **`description`** *string*, OPTIONAL
62+
63+
Human readable description of this endpoint.
64+
65+
- **`endpoints`** *array of strings*, REQUIRED
66+
67+
Enumeration of the endpoints provided on this registry (as not all "OPTIONAL" endpoints may be present in all registries)
68+
69+
## Code representations
70+
71+
Golang structures for these JSON structures is available at [`github.com/opencontainers/distribution-spec/specs-go/v1/extensions`](https://github.com/opencontainers/distribution-spec/tree/main/specs-go/v1/extensions/)
72+
73+
## Error Codes
74+
75+
Registry implementations MAY chose to not support any extension and the base extension MAY return the following error message.
76+
77+
| Code | Message | Description |
78+
|---------------|-------------------------------|---------------------------------------------------------------------------------------------|
79+
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. |

‎specs-go/v1/extensions/ext.go

+29
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Copyright 2022 The Linux Foundation
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package extensions
16+
17+
// ExtensionList is the structure returned from discover endpoint defined in /extensions/_oci.md
18+
type ExtensionList struct {
19+
Extensions []Extension `json:"extensions"`
20+
}
21+
22+
// Extension provides information on extensions provided on a Registry.
23+
// defined further in /extensions/_oci.md
24+
type Extension struct {
25+
Name string `json:"name"`
26+
URL string `json:"url"`
27+
Description string `json:"description,omitempty"`
28+
Endpoints []string `json:"endpoints"`
29+
}

0 commit comments

Comments
 (0)