diff --git a/.gitignore b/.gitignore index f949ab52a..7d009752f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,2 @@ -code-of-conduct.md /oci-validate-examples output diff --git a/Makefile b/Makefile index 0a5fd7d92..a5502308c 100644 --- a/Makefile +++ b/Makefile @@ -21,9 +21,7 @@ endif # These docs are in an order that determines how they show up in the PDF/HTML docs. DOC_FILES := \ - README.md \ - code-of-conduct.md \ - project.md \ + spec.md \ media-types.md \ descriptor.md \ image-layout.md \ @@ -77,9 +75,6 @@ $(OUTPUT_DIRNAME)/$(DOC_FILENAME).html: $(DOC_FILES) $(FIGURE_FILES) ls -sh $(shell readlink -f $@) endif -code-of-conduct.md: - curl -o $@ https://github.com/raw/opencontainers/tob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md - validate-examples: go test -run TestValidate ./schema diff --git a/README.md b/README.md index f31b72e67..4d1a0caa7 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,15 @@ # Open Container Initiative Image Format Specification 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. -## Table of Contents +The specification can be found [here](spec.md). -- [Introduction](README.md) - - [Code of Conduct](#code-of-conduct) - - [Project Documentation](project.md) - - [Media Types](media-types.md) -- [Content Descriptors](descriptor.md) -- [Image Layout](image-layout.md) -- [Image Manifest](manifest.md) -- [Image Manifest List](manifest-list.md) -- [Filesystem Layers](layer.md) -- [Image Configuration](config.md) -- [Canonicalization](canonicalization.md) +Additional documentation about how this group operates: -## Overview - -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 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). - -The keywords "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. - -![](img/build-diagram.png) - -Once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an [OCI Runtime Bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md). - -![](img/run-diagram.png) - -## Understanding the Specification - -The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification. - -The high-level components of the spec include: - -* An archival format for container images, consisting of an [image manifest](manifest.md), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) -* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) -* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) -* Signatures that are based on signing image content address (optional OCI layer) -* Naming that is federated based on DNS and can be delegated (optional OCI layer) +- [Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md) +- [Roadmap](#roadmap) +- [Releases](RELEASES.md) +- [Project Documentation](project.md) The _optional_ and _base_ layers of all OCI projects are tracked in the [OCI Scope Table](https://www.opencontainers.org/governance/oci-scope-table). @@ -96,10 +61,6 @@ Issues are used for bugs and actionable items and longer discussions can happen The specification and code is licensed under the Apache 2.0 license found in the `LICENSE` file of this repository. -## Code of Conduct - -Participation in the OCI community is governed by the [OCI Code of Conduct](https://github.com/opencontainers/tob/blob/d2f9d68c1332870e40693fe077d311e0742bc73d/code-of-conduct.md). - ## Discuss your design The project welcomes submissions, but please let everyone know what you are working on. @@ -202,6 +163,5 @@ Read more on [How to Write a Git Commit Message](http://chris.beams.io/posts/git 8. When possible, one keyword to scope the change in the subject (i.e. "README: ...", "runtime: ...") -[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18 [UberConference]: https://www.uberconference.com/opencontainers [irc-logs]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/ diff --git a/manifest-list.md b/manifest-list.md index 0e485dcd6..b0c1457ff 100644 --- a/manifest-list.md +++ b/manifest-list.md @@ -41,12 +41,12 @@ This section defines the `application/vnd.oci.image.manifest.list.v1+json` [medi - **`architecture`** *string* This REQUIRED property specified the CPU architecture. - Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform]. + Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.arch`][runtime-platform2]. - **`os`** *string* This REQUIRED property specifies the operating system. - Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform]. + Manifest lists SHOULD use, and implementations SHOULD understand, values [supported by runtime-spec's `platform.os`][runtime-platform2]. - **`os.version`** *string* @@ -118,4 +118,4 @@ Instead they MUST ignore unknown properties. } ``` -[runtime-platform]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform +[runtime-platform2]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#platform diff --git a/spec.md b/spec.md new file mode 100644 index 000000000..19143133d --- /dev/null +++ b/spec.md @@ -0,0 +1,52 @@ +# Open Container Initiative Image Format Specification + +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). + +The goal of this specification is to enable the creation of interoperable tools for building, transporting, and preparing a container image to run. + +## Table of Contents + +- [Introduction](spec.md) +- [Notational Conventions](#notational-conventions) +- [Overview](#overview) + - [Understanding the Specification](#understanding-the-specification) + - [Media Types](media-types.md) +- [Content Descriptors](descriptor.md) +- [Image Layout](image-layout.md) +- [Image Manifest](manifest.md) +- [Image Manifest List](manifest-list.md) +- [Filesystem Layers](layer.md) +- [Image Configuration](config.md) +- [Canonicalization](canonicalization.md) + +# Notational Conventions + +The key words "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). + +The key words "unspecified", "undefined", and "implementation-defined" are to be interpreted as described in the [rationale for the C99 standard][c99-unspecified]. + +# Overview + +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 layers is called the "OCI Image". + +![](img/build-diagram.png) + +Once built the OCI Image can then be discovered by name, downloaded, verified by hash, trusted through a signature, and unpacked into an [OCI Runtime Bundle](https://github.com/opencontainers/runtime-spec/blob/master/bundle.md). + +![](img/run-diagram.png) + +## Understanding the Specification + +The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification. + +The high-level components of the spec include: + +* An archival format for container images, consisting of an [image manifest](manifest.md), an [image layout](image-layout.md), a set of [filesystem layers](layer.md), and [image configuration](config.md) (base OCI layer) +* A [process of referencing container images by a cryptographic hash of their content](descriptor.md) (base OCI layer) +* A format for [storing CAS blobs and references to them](image-layout.md) (optional OCI layer) +* Signatures that are based on signing image content address (optional OCI layer) +* Naming that is federated based on DNS and can be delegated (optional OCI layer) + +[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18