-
Notifications
You must be signed in to change notification settings - Fork 99
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add initial draft for registry specification
Signed-off-by: Radu M <[email protected]>
- Loading branch information
Radu M
committed
Jun 10, 2020
1 parent
af4d555
commit 7a1078a
Showing
4 changed files
with
194 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,147 @@ | ||
--- | ||
title: Representing CNAB bundles in OCI Registries | ||
weight: 201 | ||
--- | ||
|
||
# Representing CNAB bundles in OCI Registries | ||
|
||
This section describes how the bundle file and the information represented in the bundle MUST be represented when distributing bundles using OCI registries. | ||
|
||
A CNAB is made up of a descriptor file (`bundle.json`), one or more invocation images, and a list of zero or more component images. Each of these objects can be individually packaged into an OCI manifest or OCI index. An OCI index can then be used to combine these all into a single object. | ||
|
||
Runtimes and registries MAY choose to _relocate_ the images and invocation images referenced in the bundle to registry where the bundle is pushed, but in its simplest form, a CNAB bundle MAY be represented in an OCI registry by the canonical `bundle.json` file descriptor, referenced in an OCI index (or manifest list). | ||
|
||
![](https://i.imgur.com/PfTcKOm.png) | ||
|
||
### `bundle.json` manifest | ||
|
||
> xxx can adapt some of what's written here, will need to see that it's up to date: https://github.com/cnabio/cnab-to-oci#cnab-to-oci | ||
> xxx registries that don't support layers: null? ECR | ||
> xxx registries that don't support OCI? fallback to docker distribution? | ||
> xxx annotations? we'll need these specifically when we can't use the right media type | ||
The `bundle.json` MUST be serialized as canonical JSON and MUST be stored in the registry as a blob. This blob MUST be referenced by its digest in an OCI manifest. The manifest media type SHOULD be `application/vnd.cnab.bundle.config.v1+json` but MAY be a standard container image config type (`application/vnd.oci.image.config.v1+json`) if the target registry does not support the CNAB media type. | ||
|
||
### Example | ||
|
||
The following non-canonical `bundle.json` file will be used as an example: | ||
|
||
```json | ||
{ | ||
"schemaVersion": "v1.0.0", | ||
"name": "helloworld", | ||
"version": "0.1.1", | ||
"description": "A short description of your bundle", | ||
"keywords": ["helloworld", "cnab", "tutorial"], | ||
"maintainers": [ | ||
{ | ||
"name": "Jane Doe", | ||
"email": "[email protected]", | ||
"url": "https://example.com" | ||
} | ||
], | ||
"invocationImages": [ | ||
{ | ||
"imageType": "docker", | ||
"image": "cnab/helloworld:0.1.1", | ||
"size": 942, | ||
"contentDigest": "sha256:a59a4e74d9cc89e4e75dfb2cc7ea5c108e4236ba6231b53081a9e2506d1197b6", | ||
"mediaType": "application/vnd.docker.distribution.manifest.v2+json" | ||
} | ||
], | ||
"images": null, | ||
"parameters": null, | ||
"credentials": null | ||
} | ||
``` | ||
|
||
The `bundle.json` is serialized into canonical JSON and is pushed as a blob to the registry. This blob is then referenced by its digest (for example `sha256:e91b9dfcbbb3b88bac94726f276b89de46e4460b55f6e6d6f876e666b150ec5b`) as the object config. | ||
|
||
The bundle is encapsulated in an OCI manifest which is then referenced as part of an OCI index (or manifest list): | ||
|
||
```json | ||
{ | ||
"schemaVersion": 2, | ||
"config": { | ||
"mediaType": "application/vnd.cnab.bundle.config.v1+json", | ||
"digest": "sha256:e91b9dfcbbb3b88bac94726f276b89de46e4460b55f6e6d6f876e666b150ec5b", | ||
"size": 498 | ||
}, | ||
"layers": null | ||
} | ||
``` | ||
|
||
The bundle file MUST be stored in the OCI registry, as it is the canonical representation of a CNAB bundle, and is the object that is used to compute the signature for a thin bundle. | ||
While implementations MAY choose to surface information from the bundle as top-level annotations in the OCI representations, they MUST store the unmodified bundle file as a blob. | ||
|
||
The bundle file and registry location MAY be used by implementations to generate relocation maps at runtime. | ||
|
||
### Invocation images | ||
|
||
> xxx annotations? | ||
> xxx packaging non-container invocation images? ORAS? | ||
> xxx punt: do we want to support multiarch AND multimethod? e.g.: multiarch container image + VM. Issue I see is that we might land up with OCI index referencing OCI index (deep hierarchy). | ||
> xxx registries that don't support OCI? fallback to docker distribution? | ||
> In practice most images are built as Docker v2 images so we should allow these | ||
Each invocation image SHOULD be packaged as an OCI image but MAY be packaged as a Docker v2 image. If there are multiple invocation images, these SHOULD be referenced by an OCI index but MAY be referenced by a Docker manifest list. | ||
|
||
### Component images | ||
|
||
> xxx packaging non-container component images? ORAS? | ||
> xxx multiarch? | ||
> xxx annotations? | ||
> In practice most images are built as Docker v2 images so we should allow these | ||
Each component image SHOULD be packaged as an OCI image but MAY be packaged as a Docker v2 image. In the case that a component has multiple equivalent forms, such as a multiarch container image, each component MUST be packaged and then SHOULD be referenced by an OCI index but MAY be referenced by a Docker manifest list. | ||
|
||
## Top-level representation | ||
|
||
> xxx annotations | ||
The top-level representation of the CNAB SHOULD be an OCI index but may be a Docker manifest list. | ||
|
||
The `manifests` list MUST be filled in the following order: | ||
|
||
- A reference to packaged `bundle.json` manifest | ||
- References to the invocation images | ||
- References to the component images | ||
|
||
### Example | ||
|
||
> xxx something simple | ||
```json | ||
{ | ||
"schemaVersion": 2, | ||
"manifests": [ | ||
{ | ||
"mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
"digest": "sha256:6ec4fd695cace0e3d4305838fdf9fcd646798d3fea42b3abb28c117f903a6a5f", | ||
"size": 188, | ||
"annotations": { | ||
"io.cnab.manifest.type": "config" | ||
} | ||
}, | ||
{ | ||
"mediaType": "application/vnd.docker.distribution.manifest.v2+json", | ||
"digest": "sha256:a59a4e74d9cc89e4e75dfb2cc7ea5c108e4236ba6231b53081a9e2506d1197b6", | ||
"size": 942, | ||
"annotations": { | ||
"io.cnab.manifest.type": "invocation" | ||
} | ||
} | ||
], | ||
"annotations": { | ||
"io.cnab.keywords": "[\"helloworld\",\"cnab\",\"tutorial\"]", | ||
"io.cnab.runtime_version": "v1.0.0", | ||
"org.opencontainers.artifactType": "application/vnd.cnab.manifest.v1", | ||
"org.opencontainers.image.authors": "[{\"name\":\"Jane Doe\",\"email\":\"[email protected]\",\"url\":\"https://example.com\"}]", | ||
"org.opencontainers.image.description": "A short description of your bundle", | ||
"org.opencontainers.image.title": "helloworld", | ||
"org.opencontainers.image.version": "0.1.1" | ||
} | ||
} | ||
``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
--- | ||
title: Implementations of CNAB Registry | ||
weight: 202 | ||
--- | ||
|
||
TODO | ||
|
||
> xxx info about `cnab-to-oci` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,11 @@ | ||
--- | ||
title: On Disk Representation of a CNAB bundle | ||
weight: 210 | ||
--- | ||
|
||
# On Disk Representation of a CNAB bundle | ||
|
||
TODO: | ||
|
||
xxx we may be able to punt this to later | ||
xxx https://github.com/opencontainers/image-spec/blob/master/image-layout.md |