-
Notifications
You must be signed in to change notification settings - Fork 205
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.
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
extension proposal #111
extension proposal #111
Changes from all commits
b501a83
0e4c0e6
6fd88c3
97e3aef
83a789c
12ffe00
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,100 @@ | ||
--- | ||
tags: oci,distribution | ||
breaks: false | ||
--- | ||
|
||
# Extensions API for Distribution | ||
|
||
Extensions, in general, to the distribution-spec API are allowed by the distribution-spec, with certain reservations disclosed herein. | ||
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. | ||
|
||
The basis of the Extension API (`_oci`) should be emulated for all extensions. | ||
|
||
## Table | ||
|
||
_notice_: All new `/extensions/_<extention>.md` docs MUST be added to this table. | ||
|
||
| Extension | Summary | | ||
|:------------------------:|:----------------------------------------------------:| | ||
| [`_oci`](./_oci.md) | Extensions discovering extensions on registry server | | ||
| `_catalog` | Reserved prior extension | | ||
|
||
## Name | ||
|
||
Extension names MUST be unique. | ||
Extensions recorded in this distribution-spec are considered canonical definitions. | ||
|
||
Extensions are specified by extension name (`<extension>`) aligning with the project, followed by the `<component>`, and last by by the `<module>`. | ||
This constitutes the URI segments of the extension endpoint. | ||
Additional options may be passed as parameters to the endpoint. | ||
|
||
```http | ||
_<extension>/<component>/<module>[?<key>=<value>&...] | ||
``` | ||
|
||
The values of `<extension>`, `<component>`, and `<module>` MUST conform to the following regular expression: | ||
|
||
`[a-z0-9]+([._-][a-z0-9]+)` | ||
|
||
Note: the leading `_` on the extension is a prefix before this regular expression. | ||
|
||
### Registry-Level Extensions | ||
|
||
Registry-level extensions are nested under `/v2`. | ||
|
||
```http | ||
GET /v2/_<extension>/<component>/<module>[?<key>=<value>&...] | ||
``` | ||
|
||
A contrived example of a search extension may be of the form `/v2/_oci/catalog/search?pattern=foo&n=10` | ||
|
||
### Repository-Level Extensions | ||
|
||
Repository-level extension endpoints are scoped under a repository name. | ||
|
||
Repository-level extensions follow the same naming rules as the [registry-level endpoints](#registry-level-extensions). | ||
|
||
```http | ||
GET /v2/<name>/_<extension>/<component>/<module>[?<key>=<value>&...] | ||
``` | ||
|
||
### Reserved Namespaces | ||
|
||
As of current, `_oci` and `_catalog` are considered as reserved namespaces and cannot be used by other extensions. | ||
|
||
### Versioning | ||
|
||
Data payloads being exchanged from extensions SHOULD handle versioned data structures this with `Accepts` and `Content-type` HTTP headers (LINK TO RFC). | ||
|
||
If an extension has fundamentally changed enough, then it SHOULD be introduced as a new `<component>` and/or `<component>/<module>`. | ||
Whether or not there is versioning built into those names is up to the extension maintainer. | ||
|
||
## Filename | ||
|
||
Extension definitions SHOULD be placed under `./extensions/` in the specification repository. | ||
Extension files SHOULD follow the `_<extension>.md` pattern. | ||
Refer [_oci.md](./_oci.md) for more details. | ||
|
||
## Detail | ||
|
||
Extensions details MAY describe more endpoints and APIs that it MAY support. | ||
It is also recommended to call out error codes encountered and enumerated as in the | ||
in the following table: | ||
|
||
| Code | Message | Description | | ||
|---------------------|----------------------|-----------------------------------------------------| | ||
| `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. | | ||
|
||
## Pagination | ||
|
||
Extensions implementing pagination and SHOULD align with the [pagination](./spec.md#pagination) specification. | ||
|
||
Extension MAY provide enumeration without lexical ordering and in this case, it is not required to support the `last` parameter. | ||
Clients are NOT RECOMMENDED to construct the `link` and SHOULD treat the URL as opaque. | ||
|
||
## Prior Art | ||
|
||
When considering the proposal structure for these extensions, the following processes were considered: | ||
|
||
* [Python PEP](https://www.python.org/dev/peps/) | ||
* [Kubernetes KEP](https://github.com/kubernetes/enhancements/tree/master/keps) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,79 @@ | ||
# _oci Extension Endpoints | ||
|
||
## Summary | ||
|
||
This base extension namespace for OCI namespaced extension endpoints. | ||
|
||
## Reference Explanation | ||
|
||
### Component: `ext` | ||
|
||
This component is for endpoints relating to extensions on the registry API being queried. | ||
|
||
#### Module: `discover` | ||
|
||
This endpoint may be queried to discover extensions available on this registry API. | ||
|
||
Registry-level extensions may be discovered with a standard `GET` as follows. | ||
|
||
```HTTP | ||
GET /v2/_oci/ext/discover | ||
``` | ||
|
||
Repository-level extensions may be discovered with a standard GET as follows. | ||
|
||
```HTTP | ||
GET /v2/{name}/_oci/ext/discover | ||
``` | ||
|
||
The base extension returns an array of supported extensions with details of the endpoints as shown below. | ||
|
||
```HTTP | ||
200 OK | ||
Content-Length: <length> | ||
Content-Type: application/json | ||
|
||
{ | ||
"extensions": [ | ||
{ | ||
"name": "_<extension>", | ||
"description": "", | ||
"url": "..." | ||
} | ||
] | ||
} | ||
``` | ||
|
||
### *Extensions* Property Descriptions | ||
|
||
- **`extensions`** *array of extension objects*, REQUIRED | ||
|
||
This property contains a list of supported extension endpoints. | ||
|
||
- **`name`** *string*, REQUIRED | ||
|
||
The name of the extension (i.e. '`_oci`') as it will appear in the URL path. | ||
|
||
- **`url`** *string*, REQUIRED | ||
|
||
URL link to the documentation defining this extension and its endpoints. | ||
|
||
- **`description`** *string*, OPTIONAL | ||
|
||
Human readable description of this endpoint. | ||
|
||
- **`endpoints`** *array of strings*, REQUIRED | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Are "endpoints" a reference to "components"? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. ah ok. we need examples There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. For anyone that wasn't on the call today, endpoints refers to |
||
|
||
Enumeration of the endpoints provided on this registry (as not all "OPTIONAL" endpoints may be present in all registries) | ||
|
||
## Code representations | ||
|
||
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/) | ||
|
||
## Error Codes | ||
|
||
Registry implementations MAY chose to not support any extension and the base extension MAY return the following error message. | ||
|
||
| Code | Message | Description | | ||
|---------------|-------------------------------|---------------------------------------------------------------------------------------------| | ||
| `UNSUPPORTED` | The operation is unsupported. | The operation was unsupported due to a missing implementation or invalid set of parameters. | |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,29 @@ | ||
// Copyright 2022 The Linux Foundation | ||
// | ||
// Licensed under the Apache License, Version 2.0 (the "License"); | ||
// you may not use this file except in compliance with the License. | ||
// You may obtain a copy of the License at | ||
// | ||
// http://www.apache.org/licenses/LICENSE-2.0 | ||
// | ||
// Unless required by applicable law or agreed to in writing, software | ||
// distributed under the License is distributed on an "AS IS" BASIS, | ||
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | ||
// See the License for the specific language governing permissions and | ||
// limitations under the License. | ||
|
||
package extensions | ||
|
||
// ExtensionList is the structure returned from discover endpoint defined in /extensions/_oci.md | ||
type ExtensionList struct { | ||
Extensions []Extension `json:"extensions"` | ||
} | ||
|
||
// Extension provides information on extensions provided on a Registry. | ||
// defined further in /extensions/_oci.md | ||
type Extension struct { | ||
Name string `json:"name"` | ||
URL string `json:"url"` | ||
Description string `json:"description,omitempty"` | ||
Endpoints []string `json:"endpoints"` | ||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
... or as part of repository names.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
oh for sure. In the updated push I include some string formatting regular expression. With the
_
prefix on the extension name, that differentiates all extensions, from any<name>
of a manifest reference.