From 4e11c958e67867af15e75085289a7253b189229e Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Tue, 8 Nov 2016 09:55:43 -0800 Subject: [PATCH 1/2] manifest: Require unpackers to create a config.json from the referenced config The image-tools framework has attempted this since d3ffc1ce (oci-image-tool: implement create-runtime-bundle, 2016-06-02, #114), but we didn't specify whether the translation was required or what the output of the translation should be. That means downstream consumers of an unpacked image couldn't be sure if they'd find a config.json or (if they found one) which runtime-spec versions it would be compatible with. With this commit, the config output becomes specified, so consumers can post-process their config.json and/or invoke a runtime-spec 1.0.0-rc2-compatible runtime on it without worrying about the presence or version of the unpacked config.json. I've picked 1.0.0-rc2 as the most recent runtime-spec commit. As the runtime-spec moves forward with more RCs, I expect we'll want to bump this to keep up. Once runtime-spec hits 1.0, we can probably freeze the target, since post 1.0 releases in runtime-spec's 1.x line are unlikely to make translation from the config format easier, and any 1.x-compatible runtime will be able to handle 1.0 configs. Signed-off-by: W. Trevor King --- config.md | 2 ++ manifest.md | 3 +++ 2 files changed, 5 insertions(+) diff --git a/config.md b/config.md index a5dccebd4..d7efb2a12 100644 --- a/config.md +++ b/config.md @@ -4,6 +4,7 @@ An OCI *Image* is an ordered collection of root filesystem changes and the corre This specification outlines the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets, described in [Layers](layer.md). This section defines the `application/vnd.oci.image.config.v1+json` [media type](media-types.md). +Implementations unpacking this type MUST generate a [version 1.0.0-rc2 runtime-spec configuration][runtime-config]. ## Terminology @@ -232,4 +233,5 @@ Here is an example image configuration JSON document: } ``` +[runtime-config]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md [runtime-platform]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform diff --git a/manifest.md b/manifest.md index 900162b08..daecdad2a 100644 --- a/manifest.md +++ b/manifest.md @@ -28,6 +28,7 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a - **`config`** *[descriptor](descriptor.md)* This REQUIRED property references a configuration object for a container, by digest. + Implementations unpacking manifests MUST generate a [`config.json`][bundle-format] from the referenced configuration. Beyond the [descriptor requirements](descriptor.md#properties), the value has the following additional restrictions: - **`mediaType`** *string* @@ -118,3 +119,5 @@ This specification defines the following annotation keys, which MAY be used by m * **org.opencontainers.authors** contact details of the people or organization responsible for the image (freeform string) * **org.opencontainers.homepage** URL to find more information on the image (string, must be a URL with scheme HTTP or HTTPS) * **org.opencontainers.documentation** URL to get documentation on the image (string, must be a URL with scheme HTTP or HTTPS) + +[bundle-format]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/bundle.md#container-format From 0a4687126327e7e373b1f12437e852c155249a13 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Sat, 5 Nov 2016 21:53:28 -0700 Subject: [PATCH 2/2] manifest: Require support for runtime-spec configurations We probably need to keep application/vnd.oci.image.config.v1+json untouched, since e94aa35a (schema: add a docker v2.2 backwards compat test, 2016-06-15, #145) and other maintainer activity suggest a goal of bit-for-bit compatibility with the current Docker schemas (excepting media types). However, requiring Docker support doesn't mean we can't *also* require support for configuration formats that are easier for image authors to use. Of course, with the (greatly) increased flexibility comes a lot more risk. Image consumers in general, and runtime-spec-based-image consumers in particular, should use a sanitization tool like [1]. The runtime-spec config also lacks support for diffIDs, but local image tooling is still welcome to record the digests of uncompressed layers and use that for local optimizations. You have to fetch the compressed layer at least once to perform the uncompression, but you'd have to do that to verify the old diffID anyway. [1]: https://github.com/opencontainers/runtime-tools/pull/219 Signed-off-by: W. Trevor King --- manifest.md | 1 + 1 file changed, 1 insertion(+) diff --git a/manifest.md b/manifest.md index daecdad2a..2e88f6341 100644 --- a/manifest.md +++ b/manifest.md @@ -37,6 +37,7 @@ Unlike the [Manifest List](manifest-list.md), which contains information about a Implementations MUST support at least the following media types: - [`application/vnd.oci.image.config.v1+json`](config.md) + - [`application/vnd.oci.runtime.config.v1+json`](https://github.com/opencontainers/runtime-spec/blob/master/config.md), which MUST be unpacked to `config.json` without alteration. Manifests concerned with portability SHOULD use one of the above media types.