Skip to content
This repository has been archived by the owner on Jul 18, 2023. It is now read-only.

Commit

Permalink
Add artifact authors how-to info
Browse files Browse the repository at this point in the history
Signed-off-by: Steven Lasker <[email protected]>
  • Loading branch information
SteveLasker committed Aug 29, 2019
1 parent e5043d0 commit 760bceb
Show file tree
Hide file tree
Showing 14 changed files with 848 additions and 44 deletions.
50 changes: 39 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,17 +2,17 @@

Container registries, implementing the [distribution-spec][distribution-spec], provide reliable, highly scalable, secured storage services for container images. Customers either use a cloud provider implementation, vendor implementations, or instance the open source implementation of [distribution][distribution]. They configure security and networking to assure the images in the registry are locked down and accessible by the resources required. Cloud providers and vendors often provide additional values atop their registry implementations from security to productivity features.

Applications and services typically require additional artifacts to deploy and manage, including [helm](https://helm.sh) for deployment and [Open Policy Agent (OPA)](https://github.com/open-policy-agent/opa/issues/1413) for policy enforcement.
Applications and services typically require additional artifacts to deploy and manage, including [helm](https://helm.sh) for deployment and [Open Policy Agent (OPA)](https://github.com/open-policy-agent/opa/issues/1413) for policy enforcement.

Utilizing the [manifest][image-manifest] and [index][image-index] definitions, new artifacts, such as the [Singularity project][singularity], can be stored and served using the [distribution-spec][distribution-spec].
Utilizing the [manifest][image-manifest] and [index][image-index] definitions, new artifacts, such as the [Singularity project][singularity], can be stored and served using the [distribution-spec][distribution-spec].

This repository provides a reference for artifact authors and registry implementors for supporting new artifact types with the existing implementations of distribution.

By providing an OCI artifact definition, the community can continue to innovate, focusing on new artifact types without having to build yet another storage solution ([YASS][def-yass]).
By providing an OCI artifact definition, the community can continue to innovate, focusing on new artifact types without having to build yet another storage solution ([YASS][def-yass]).

## OCI Artifact Table of Contents

* [What Is an OCI Artifact](#what-is-an-oci-artifact)
* [Overview of Registry Content Delivery](#overview-of-registry-content-delivery)
* [Defining OCI Artifact Types](#defining-oci-artifact-types)
* [Definitions & Terms](definitions-terms.md)
* [OCI Artifact Implementations](implementors.md)
Expand All @@ -25,17 +25,45 @@ By providing an OCI artifact definition, the community can continue to innovate,
* [Project governance](GOVERNANCE.md)
* [Release procedures](RELEASES.md)

## What Is an OCI Artifact
## Overview of Registry Content Delivery

An OCI Artifact is a generic reference to an object that can be stored in an instance of [OCI Distribution][distribution-spec]. The artifact can be [def-well known types][well-known-types], such as [OCI-Image][image-spec] and [Singularity][singularity], or customer or vendor specific types.
Registry content delivery can be broken down into 3 distinct components:

| | |
|-|:-:|
| [Registry](#registry) |<img src=./media/registry-layer.png height=100> |
| [Manifest Schemas](#manifest-schemas) |<img src=./media/manifest-layer.png height=40> |
| [Artifacts](#artifacts) |<img src=./media/artifact-layer.png height=100> |

### Registry

A registry, as an implementation of the [OCI Distribution Spec][distribution-spec], serves a few primary roles:

* Persistence of content, stored as blobs
* Aggregation of blobs, defined by manifests
* A REST endpoint for content discovery
* Content delivery
* Authentication & authorization

### Manifest Schemas

For a registry to store collections of content, it must have well known schemas to uniquely describe each content addressable object. The [OCI Manifest][image-manifest] and [OCI Index][image-index] are two well known schemas that implementations of the [OCI Distribution Spec][distribution-spec] MUST support.

While it's possible for registries to implement additional manifest schemas, the authors of the OCI manifest and index had the forethought of flexibility, enabling the majority of scenarios we know today.

### Artifacts

Artifacts, like docker and OCI images are well known types of artifacts. Using the same schemas and persistence, additional artifacts can be defined, persisted and served with OCI distribution spec compliant registries.

OCI Artifacts generalizes registries from uniquely storing OCI Images, to generic means storing additional artifact types.

## Defining OCI Artifact Types

[Registries][def-registry], vulnerability scanners and artifact tooling must understand the types of artifacts they support. Registry scanning tools may only support a subset of artifact types, or they may need to apply different scanning methods based on the artifact type.
[Registries][def-registry], vulnerability scanners and artifact tooling must understand the types of artifacts they support. Registry scanning tools may only support a subset of artifact types, or they may need to apply different scanning methods based on the artifact type.

If a security scanning solution were to scan all types, it would fail when it encounters unsupported types, representing false negatives. By differentiating types, a registry scanning solution can ignore unknown types, representing a known state. As new artifact types become [well known][def-well-known-types], scanners can expand the types they offer, providing a more complete known state.
If a security scanning solution were to scan all types, it would fail when it encounters unsupported types, representing false negatives. By differentiating types, a registry scanning solution can ignore unknown types, representing a known state. As new artifact types become [well known][def-well-known-types], scanners can expand the types they offer, providing a more complete known state.

Artifact tooling must also know the types they support. The docker and containerD client know how to instance container images. However, they are not intended to instance Helm Charts or Singularity images. By defining the artifact type, registries can present the type to their users, and tools pulling artifacts from a registry can determine if they can support the specific type before encountering a runtime error.
Artifact tooling must also know the types they support. The docker and containerD client know how to instance container images. However, they are not intended to instance Helm Charts or Singularity images. By defining the artifact type, registries can present the type to their users, and tools pulling artifacts from a registry can determine if they can support the specific type before encountering a runtime error.

Artifacts are defined by setting the `manifest.config.mediaType` to a globally unique value. The `config.mediaType` of `application/vnd.oci.image.config.v1+json` is reserved for artifacts intended to be instanced by docker and [containerD][containerd].

Expand All @@ -53,13 +81,13 @@ This project would continue to use existing channels in use by the [OCI develope

### Versioning / Roadmap

Artifacts will reference specific [distribution][distribution-spec], [index][image-index] and [manifest][image-manifest] versions in its examples, identifying any dependencies required.
Artifacts will reference specific [distribution][distribution-spec], [index][image-index] and [manifest][image-manifest] versions in its examples, identifying any dependencies required.

## Frequently Asked Questions (FAQ)

**Q: Does this change the OCI Charter or Scope Table?**

A: No. Artifacts are a prescriptive means of storing [index][image-index] and [manifest][image-manifest] within [distribution][distribution-spec] implementations.
A: No. Artifacts are a prescriptive means of storing [index][image-index] and [manifest][image-manifest] within [distribution][distribution-spec] implementations.

[containerd]: https://containerd.io/
[code-of-conduct]: CODE_OF_CONDUCT.md
Expand Down
173 changes: 173 additions & 0 deletions artifactTypes/artifactTypeSchema.0.1.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,173 @@
{
"definitions": {},
"type": "object",
"title": "The Root Schema",
"required": [
"mediaType",
"title",
"description",
"layerMediaTypes"
],
"properties": {
"mediaType": {
"$id": "#/properties/mediaType",
"type": "string",
"description": "Collection of localized titles, which may be displayed in registry and tool artifact listing.",
"default": "application/vnd.unknown.config.v1+json",
"examples": [
"application/vnd.unknown.config.v1+json"
],
"minLength": 35,
"maxLength": 100
},
"title": {
"$id": "#/properties/title",
"type": "object",
"description": "Collection of localized titles, which may be displayed in registry and tool artifact listing.",
"required": [
"locale",
"title"
],
"properties": {
"locale": {
"$id": "#/properties/title/items/properties/locale",
"type": "string",
"description": "language-locale ISO code",
"default": "en-US",
"examples": [
"en-US"
],
"minLength": 5,
"maxLength": 5
},
"title": {
"$id": "#/properties/title/items/properties/title",
"type": "string",
"description": "Localized title of the artifact type.",
"default": "",
"examples": [
"Unknown type"
],
"minLength": 3,
"maxLength": 30
}
}
},
"description": {
"$id": "#/properties/description",
"type": "object",
"description": "Provides a short description of the type for human consumption.",
"required": [
"locale",
"description"
],
"properties": {
"locale": {
"$id": "#/properties/title/properties/locale",
"type": "string",
"description": "language-locale ISO code",
"default": "en-US",
"examples": [
"en-US"
],
"minLength": 5,
"maxLength": 5
},
"description": {
"$id": "#/properties/description/properties/description",
"type": "string",
"description": "Localized description of the artifact type.",
"examples": [
"Unknown type"
],
"minLength": 5,
"maxLength": 255
}
}
},
"specUrl": {
"$id": "#/properties/specUrl",
"type": "string",
"description": "References a spec, providing additional details on the type.",
"format": "url"
},
"moreInfoUrl": {
"$id": "#/properties/moreInfoUrl",
"type": "string",
"description": "Provides additional details, intended for consumers of the type.",
"format": "url"
},
"tools": {
"$id": "#/properties/tools",
"type": "array",
"description": "Provides a collection of tools that may be used with artifact type.",
"items": {
"$id": "#/properties/tools/items",
"type": "object",
"required": [
"url",
"title"
],
"properties": {
"url": {
"$id": "#/properties/tools/items/properties/url",
"type": "string",
"description": "Links to a page where users can download the tool."
},
"title": {
"$id": "#/properties/tools/items/properties/title",
"type": "object",
"description": "Represents the name of the tool, displayed for human consumption.",
"required": [
"locale",
"title"
],
"properties": {
"locale": {
"$id": "#/properties/tools/items/properties/title/items/properties/locale",
"type": "string",
"description": "language-locale ISO code",
"default": "en-US",
"examples": [
"en-US"
],
"minLength": 5,
"maxLength": 5
},
"title": {
"$id": "#/properties/tools/items/properties/title/items/properties/title",
"type": "string",
"description": "Localized name of the tool, displayed for human consumption.",
"minLength": 3,
"maxLength": 30
}
}
}
}
}
},
"configSchemaReference": {
"$id": "#/properties/configSchemaReference",
"type": "string",
"description": "provides a schema reference for the artifact config object.",
"format": "url"
},
"layerMediaTypes": {
"$id": "#/properties/layerMediaTypes",
"type": "array",
"description": "Represents one or more layer mediaTypes, defined by the artifact.",
"items": {
"$id": "#/properties/layerMediaTypes/items",
"type": "string",
"default": "application/vnd.oci.unknown.layer.v1.tar",
"examples": [
"application/vnd.oci.unknown.layer.v1.bin",
"application/vnd.oci.unknown.layer.v1.json",
"application/vnd.oci.unknown.layer.v1.tar",
"application/vnd.oci.unknown.layer.v1.txt",
"application/vnd.oci.unknown.layer.v1.yaml"
]
}
}
}
}
26 changes: 26 additions & 0 deletions artifactTypes/vnd.oci.image.1/artifactType.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
{
"mediaType": "application/vnd.oci.image.config.v1+json",
"spec": "https://github.com/opencontainers/image-spec/blob/master/layer.md#gzip-media-types",
"title": {
"locale": "en-US",
"title": "OCI Image"
},
"description": {
"locale": "en-US",
"description": "OCI Image"
},
"url": "https://www.opencontainers.org/",
"tools":[
{
"title": {
"locale": "en-US",
"title": "OCI Runtime"
},
"url": "https://github.com/opencontainers/runtime-tools"
}
],
"configSchemaReference": "https://raw.githubusercontent.com/opencontainers/image-spec/master/schema/config-schema.json",
"layerMediaTypes": [
"application/vnd.oci.image.layer.v1.tar"
]
}
22 changes: 22 additions & 0 deletions artifactTypes/vnd.oci.image.1/logo.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
30 changes: 30 additions & 0 deletions artifactTypes/vnd.unknown.1/artifactType.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"mediaType": "application/vnd.unknown.config.v1+json",
"spec": "https://github.com/opencontainers/artifacts",
"title": {
"locale": "en-US",
"title": "An unknown type"
},
"description": {
"locale": "en-US",
"description": "An undefined type - USE ONLY FOR DEVELOPMENT"
},
"url": "https://github.com/opencontainers/artifacts",
"tools":[
{
"title": {
"locale": "en-US",
"title": "ORAS"
},
"url": "https://github.com/deislabs/oras"
}
],
"configSchemaReference": "",
"layerMediaTypes": [
"application/vnd.oci.unknown.layer.v1.bin",
"application/vnd.oci.unknown.layer.v1.json",
"application/vnd.oci.unknown.layer.v1.tar",
"application/vnd.oci.unknown.layer.v1.txt",
"application/vnd.oci.unknown.layer.v1.yaml"
]
}
Loading

0 comments on commit 760bceb

Please sign in to comment.