diff --git a/Makefile b/Makefile index 787e105fd..02c3245d9 100644 --- a/Makefile +++ b/Makefile @@ -28,7 +28,7 @@ DOC_FILES := \ descriptor.md \ image-layout.md \ layer.md \ - serialization.md \ + config.md \ manifest.md FIGURE_FILES := \ diff --git a/README.md b/README.md index 72c8fccd3..d16229a14 100644 --- a/README.md +++ b/README.md @@ -2,10 +2,10 @@ The OCI Image Format project creates and maintains the software shipping container image format spec (OCI Image Format). The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run. -This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](serialization.md). -At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more filesystem serialization archives that will be unpacked to make up the final runnable filesystem. +This specification defines how to create an OCI Image, which will generally be done by a build system, and output an [image manifest](manifest.md), a set of [filesystem layers](layer.md), and an [image configuration](config.md). +At a high level the image manifest contains metadata about the contents and dependencies of the image including the content-addressable identity of one or more [filesystem layer changeset](layer.md) archives that will be unpacked to make up the final runnable filesystem. The image configuration includes information such as application arguments, environments, etc. -The combination of the image manifest, image configuration, and one or more filesystem serializations is called the "OCI Image". +The combination of the image manifest, image configuration, and one or more filesystem layers is called the "OCI Image". The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](http://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). @@ -17,11 +17,11 @@ Once built the OCI Image can then be discovered by name, downloaded, verified by ## Understanding the Specification -The [Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification. This document outlines the OCI Image file format specifications, including the critical filesystem serialization and image manifest described above. +The [Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification. This document outlines the OCI Image file format specifications, including the [filesystem layer changesets](layer.md) and image manifest described above. The high level components of the spec include: -* An [image manifest](manifest.md), a set of [filesystem layers](layer.md), and [image configuration](serialization.md) (base layer) +* An [image manifest](manifest.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base layer) * A process of hashing the image format for integrity and content-addressing (base layer) * Signatures that are based on signing image content address (optional layer) * Naming that is federated based on DNS and can be delegated (optional layer) diff --git a/serialization.md b/config.md similarity index 99% rename from serialization.md rename to config.md index acb97308d..378f3d409 100644 --- a/serialization.md +++ b/config.md @@ -56,12 +56,12 @@ This specification uses the following terms: -## Image JSON Description +## Image Configuration -Here is an example image JSON file: +Here is an example image configuration JSON document: ```json,title=Image%20JSON&mediatype=application/vnd.oci.image.config.v1%2Bjson -{ +{ "created": "2015-10-31T22:22:56.015925234Z", "author": "Alyssa P. Hacker ", "architecture": "amd64", @@ -71,10 +71,10 @@ Here is an example image JSON file: "Memory": 2048, "MemorySwap": 4096, "CpuShares": 8, - "ExposedPorts": { + "ExposedPorts": { "8080/tcp": {} }, - "Env": [ + "Env": [ "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "FOO=oci_is_a", "BAR=well_written_spec" diff --git a/image-layout.md b/image-layout.md index 68bedb6eb..700108d2a 100644 --- a/image-layout.md +++ b/image-layout.md @@ -2,7 +2,7 @@ The OCI Image Layout is a slash separated layout of OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs). This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync). -Given an image layout a tool can convert a given ref into a runnable OCI Image Format by finding an appropriate manifest from the manifest list, unpacking the filesystem serializations in the correct order, and then converting the image configuration into an OCI Runtime config.json. +Given an image layout a tool can convert a given ref into a runnable OCI Image Format by finding an appropriate manifest from the manifest list, unpacking the [filesystem layers](layer.md) in the correct order, and then converting the image configuration into an OCI Runtime config.json. The image layout has two top level directories: diff --git a/manifest.md b/manifest.md index cfb84ea2c..010dab490 100644 --- a/manifest.md +++ b/manifest.md @@ -135,7 +135,7 @@ Unlike the [Manifest List](#manifest-list), which contains information about a s - **`config`** *[descriptor](descriptor.md)* This REQUIRED property references a configuration object for a container, by digest. - The referenced configuration object is a JSON blob that the runtime uses to set up the container, see [Image JSON Description](serialization.md#image-json-description). + The referenced configuration object is a JSON blob that the runtime uses to set up the container, see [Image JSON Description](config.md). - **`layers`** *array* diff --git a/media-types.md b/media-types.md index c720d7bba..041a209a2 100644 --- a/media-types.md +++ b/media-types.md @@ -5,7 +5,7 @@ The following media types identify the formats described here and their referenc - `application/vnd.oci.descriptor.v1+json`: [Content Descriptor](descriptor.md) - `application/vnd.oci.image.manifest.list.v1+json`: [Manifest list](manifest.md#manifest-list) - `application/vnd.oci.image.manifest.v1+json`: [Image manifest format](manifest.md#image-manifest) -- `application/vnd.oci.image.config.v1+json`: [Container config JSON](serialization.md) +- `application/vnd.oci.image.config.v1+json`: [Container config JSON](config.md) - `application/vnd.oci.image.layer.tar+gzip`: ["Layer", as a gzipped tar archive](layer.md) - `application/vnd.oci.image.layer.nondistributable.tar+gzip`: ["Layer", as a gzipped tar that has distribution restrictions](layer.md#non-distributable-layers) diff --git a/schema/manifest_test.go b/schema/manifest_test.go index a4da16e97..88d126612 100644 --- a/schema/manifest_test.go +++ b/schema/manifest_test.go @@ -44,7 +44,7 @@ func TestManifest(t *testing.T) { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "config": { - "mediaType": "application/vnd.oci.image.serialization.v1+json", + "mediaType": "application/vnd.oci.image.config.v1+json", "size": "1470", "digest": "sha256:c86f7763873b6c0aae22d963bab59b4f5debbed6685761b5951584f6efb0633b" } @@ -60,7 +60,7 @@ func TestManifest(t *testing.T) { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "config": { - "mediaType": "application/vnd.oci.image.serialization.v1+json", + "mediaType": "application/vnd.oci.image.config.v1+json", "size": 1470, "digest": "sha256:c86f7763873b6c0aae22d963bab59b4f5debbed6685761b5951584f6efb0633b" }, @@ -82,7 +82,7 @@ func TestManifest(t *testing.T) { "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "config": { - "mediaType": "application/vnd.oci.image.serialization.v1+json", + "mediaType": "application/vnd.oci.image.config.v1+json", "size": 1470, "digest": "sha256:c86f7763873b6c0aae22d963bab59b4f5debbed6685761b5951584f6efb0633b" }, diff --git a/schema/spec_test.go b/schema/spec_test.go index 4deab176a..1e9da5a49 100644 --- a/schema/spec_test.go +++ b/schema/spec_test.go @@ -41,8 +41,8 @@ func TestValidateManifest(t *testing.T) { validate(t, "../manifest.md") } -func TestValidateSerialization(t *testing.T) { - validate(t, "../serialization.md") +func TestValidateConfig(t *testing.T) { + validate(t, "../config.md") } // TODO(sur): include examples from all specification files