From 9ee7722611cf27ce417f89a8bf05dd21cfff1c09 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Fri, 29 Jan 2021 17:18:46 -0800 Subject: [PATCH 1/3] An initial structure for a set of listing APIs Signed-off-by: Steve Lasker --- requirements/listing-api-requirements.md | 40 ++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 requirements/listing-api-requirements.md diff --git a/requirements/listing-api-requirements.md b/requirements/listing-api-requirements.md new file mode 100644 index 00000000..bcc94b01 --- /dev/null +++ b/requirements/listing-api-requirements.md @@ -0,0 +1,40 @@ +# Listing API Requirements + +Registries provide the basic means to push, pull, discover and manage content. While push and pull are generally feature-rich and standardized, the discover and manage APIs are extremely limited. Each registry project and operator have had to implement discover (list) and manage APIs, and each of them are unique to that particular registry. + +To foster consistency across registries, enabling the community to build tooling that works consistently across all [OCI distribution-spec conformant registries][oci-compliance], we propose a common set of listing APIs. + +To facilitate discussions, prioritization and phased implementations, we will capture a list of scenarios and requirements. Once the requirements are felt complete and prioritized, we can transition to a design that implements the agreed prioritized items, while reserving space for the future enhancements. + +For the purposes of examples within a scenario, we'll assume an `oci-reg` cli exists. The purpose is not to design the specific CLI, rather provide concrete examples whos specific names and parameters will evolve. + +## Scenarios + +1. A user can get a list of repositories within a given registry, within a specified org and/or namespace. + - `oci-reg list acme-rockets.io/` + - `oci-reg list acme-rockets.io/org1/` +2. A user can get a list of tags within a given registry/namespace. +3. A user can get a list of manifests, within a given registry/namespace. +4. A user can get a list of artifacts that reference a specified digest. Example: (a list of Notary v2 signatures) +5. A user can get a list of tags for a specified digest. + +## Requirements + +1. Provide paging of results +2. Provide for registry specific extensions. +3. Provide filtering by `artifactType` +4. Provide filtering by annotation +5. Provide sorting + +## Prioritization + +To deliver on an incremental phased delivery, the following requirements and scenarios are identified for the following phases + +### Phase 1 + +### Phase 2 + +### Backlog + + +[oci-compliance]: https://github.com/opencontainers/oci-conformance/tree/master/distribution-spec From 64d64d5018add1a4564d42bface742fbf7610726 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 2 Feb 2021 12:20:09 -0800 Subject: [PATCH 2/3] Show/get-info API requirements Signed-off-by: Steve Lasker --- requirements/show-api-requirements.md | 79 +++++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 requirements/show-api-requirements.md diff --git a/requirements/show-api-requirements.md b/requirements/show-api-requirements.md new file mode 100644 index 00000000..146d1c96 --- /dev/null +++ b/requirements/show-api-requirements.md @@ -0,0 +1,79 @@ +# Show/GetInfo API Requirements + +Registries provide the basic means to push, pull, discover and manage content. While push and pull are generally feature-rich and standardized, the discover and manage APIs are extremely limited. Each registry project and operator have had to implement discover (list), show (get-info) and manage APIs, and each of them are unique to that particular registry. + +To foster consistency across registries, enabling the community to build tooling that works consistently across all [OCI distribution-spec conformant registries][oci-compliance], we propose a common set of `Show` APIs. + +To facilitate discussions, prioritization and phased implementations, we will capture a list of scenarios and requirements. Once the requirements are felt complete and prioritized, we can transition to a design that implements the agreed prioritized items, while reserving space for the future enhancements. + +For the purposes of examples within a scenario, we'll assume an `oci-reg` cli exists. The purpose is not to design the specific CLI, rather provide concrete examples whose specific names and parameters will evolve. + +## Scenarios + +For illustrative purposes, consider a registry with the following content. A repository may have a collection of tags, with associated digests, and untagged content. The untagged content may represent an older version of tagged content, or enhancing content like Notary v2, SBoM, GPL source artifacts. + +```bash +acme-rockets.io/ + +-hello-world: + | |─latest @sha256:latestaaa... + | |─v1 @sha256:latestaaa... + | └─── @sha256:12sab3121... + +-org1/ + | └─artifact-a: + | |─v1 @sha256:v1abcd... + | |─v2 @sha256:v2defg... + | |─── @sha256:129a52... + | └─── @sha256:129a52... + +-org2/ + | |─team-a/ + | | └─image-a1: + | | | |─v1 @sha256:v1qrst... + | | | |─v2 @sha256:v1fedc... + | | | └─── @sha256:ag2ad2... + | | └─image-a2: + | | └─v1 @sha256:v1s23a... + | └─team-b/ + | └─image-b1: + | |─v1 @sha256:v1qrst... + | |─v2 @sha256:v1fedc... + | └─── @sha256:ag2ad2... + +-org3/ + | └─team-c/ + | └─image-c1: + | |─v1 @sha256:v1f13is... + | └─── @sha256:210a113... +``` + +1. A user can get info on a specific repository within a given registry, within a specified org and/or namespace. + - `oci-reg show acme-rockets.io/hello-world` +2. A user can get info on a specific tag, within a namespace. + - `oci-reg show acme-rockets.io/hello-world:latest` +3. A user can get info on a specific digest, within a namespace. + - `oci-reg show acme-rockets.io/org2/team-a/image-a1@sha256:v1qrst...` + +## Data Returned + +The type of data returned by the `show` API would need to support common elements, consistent across all OCI Conformant registries, and registry specific content. Whether we use annotations and namespaces to provide globally unique names is deferred from the requirements. Rather we wish to capture the types of data returned to understand what types of data structures we must support. + +Common elements, likely defined within an `oci.distribution` namespace: +|Property Name|Description| +|-|-| +| repoName | Name of the repository | +| dateCreated | The date the repository was created | +| manifestCount | The total number of manifests currently in the repository | +| tagCount | The total number of tags. This number would `<=` manifestCount as not all manifests are tagged. | + +Each registry likely has additional meta-data they wish to surface. Some are captured here for examples of extensibility, or possible consideration to a common set of elements. + +> **Note:** See an early proposal on a an [OCI Registry Meta-data][meta-data-service] enhancement. + +|Property Name|Description| +|-|-| +| deleteEnabled | Is delete enabled for the requesting users context | +| listEnabled | Is listing content enabled for the requesting users context | +| readEnabled | Is content read enabled for the requesting users context | +| writeEnabled | Is content write enabled for the requesting users context | +| totalPullCount | The total pull count of content within the repository | + +[oci-compliance]: https://github.com/opencontainers/oci-conformance/tree/master/distribution-spec +[meta-data-service]: https://github.com/SteveLasker/drafts/blob/meta-data-services/meta-data-services.md \ No newline at end of file From 306f55340eaff6d23204fab16799185b87ac16a5 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 2 Feb 2021 12:27:35 -0800 Subject: [PATCH 3/3] removing listing requirements from the show-info PR Signed-off-by: Steve Lasker --- requirements/listing-api-requirements.md | 40 ------------------------ 1 file changed, 40 deletions(-) delete mode 100644 requirements/listing-api-requirements.md diff --git a/requirements/listing-api-requirements.md b/requirements/listing-api-requirements.md deleted file mode 100644 index bcc94b01..00000000 --- a/requirements/listing-api-requirements.md +++ /dev/null @@ -1,40 +0,0 @@ -# Listing API Requirements - -Registries provide the basic means to push, pull, discover and manage content. While push and pull are generally feature-rich and standardized, the discover and manage APIs are extremely limited. Each registry project and operator have had to implement discover (list) and manage APIs, and each of them are unique to that particular registry. - -To foster consistency across registries, enabling the community to build tooling that works consistently across all [OCI distribution-spec conformant registries][oci-compliance], we propose a common set of listing APIs. - -To facilitate discussions, prioritization and phased implementations, we will capture a list of scenarios and requirements. Once the requirements are felt complete and prioritized, we can transition to a design that implements the agreed prioritized items, while reserving space for the future enhancements. - -For the purposes of examples within a scenario, we'll assume an `oci-reg` cli exists. The purpose is not to design the specific CLI, rather provide concrete examples whos specific names and parameters will evolve. - -## Scenarios - -1. A user can get a list of repositories within a given registry, within a specified org and/or namespace. - - `oci-reg list acme-rockets.io/` - - `oci-reg list acme-rockets.io/org1/` -2. A user can get a list of tags within a given registry/namespace. -3. A user can get a list of manifests, within a given registry/namespace. -4. A user can get a list of artifacts that reference a specified digest. Example: (a list of Notary v2 signatures) -5. A user can get a list of tags for a specified digest. - -## Requirements - -1. Provide paging of results -2. Provide for registry specific extensions. -3. Provide filtering by `artifactType` -4. Provide filtering by annotation -5. Provide sorting - -## Prioritization - -To deliver on an incremental phased delivery, the following requirements and scenarios are identified for the following phases - -### Phase 1 - -### Phase 2 - -### Backlog - - -[oci-compliance]: https://github.com/opencontainers/oci-conformance/tree/master/distribution-spec