Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

spec: Standardize language for actions ((un)packing, etc.) #554

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ END FOR

With this approach, the link map and links names of a directory could be compared against that of another directory to derive additions and changes to hardlinks.

## Creating
## Packing

### Initial Root Filesystem

Expand Down Expand Up @@ -211,17 +211,17 @@ The resulting tar archive for `rootfs-c9d-v1.s1` has the following entries:

To signify that the resource `./etc/my-app-config` MUST be removed when the changeset is applied, the basename of the entry is prefixed with `.wh.`.

## Applying Changesets
## Unpacking

Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _applied_, rather than simply extracted as tar archives.
Layer Changesets of [media type](media-types.md) `application/vnd.oci.image.layer.v1.tar` are _unpacked_, rather than simply extracted as tar archives.

Applying a layer changeset requires special consideration for the [whiteout](#whiteouts) files.
Unpacking a layer changeset requires special consideration for the [whiteout](#whiteouts) files.

In the absence of any [whiteout](#whiteouts) files in a layer changeset, the archive is extracted like a regular tar archive.

### Changeset over existing files

This section specifies applying an entry from a layer changeset if the target path already exists.
This section specifies unpacking an entry from a layer changeset if the target path already exists.

If the entry and the existing path are both directories, then the existing path's attributes MUST be replaced by those of the entry in the changeset.
In all other cases, the implementation MUST do the semantic equivalent of the following:
Expand Down
62 changes: 48 additions & 14 deletions spec.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,11 @@ The goal of this specification is to enable the creation of interoperable tools
- [Introduction](spec.md)
- [Notational Conventions](#notational-conventions)
- [Overview](#overview)
- [Understanding the Specification](#understanding-the-specification)
- [Media Types](media-types.md)
- [Components](#componets)
- [Actions](#actions)
- [Packing Images](#packing-images)
- [Unpacking Images](#unpacking-images)
- [Media Types](#media-types.md)
- [Content Descriptors](descriptor.md)
- [Image Layout](image-layout.md)
- [Image Manifest](manifest.md)
Expand All @@ -33,18 +36,7 @@ An implementation is compliant if it satisfies all the MUST, REQUIRED, and SHALL

# 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 manifest list is a higher-level manifest which points to one or more manifests.
Typically, these manifests may provide different implementations of the image, possibly varying by platform or other attributes.

![](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
## Components

The [OCI Image Media Types](media-types.md) document is a starting point to understanding the overall structure of the specification.

Expand All @@ -56,4 +48,46 @@ The high-level components of the spec include:
* 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)

## Actions

The specified [components](#components) MAY be manipulated with actions.

* **pack**: Create a blob from the local filesystem (or other storage).
* **unpack**: Update the local filesystem (or other storage) based on data found in a blob.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a blob -> series of tar-based blobs ?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a blob -> series of tar-based blobs ?

I'm using "(un)packing" more generically than that. In the examples below, I also talk about (un)packing manifest(-list)s, and in that context it is "(de)serializing into JSON, potentially just in memory".

* **validate**: Verify that blobs [comply](#notational-conventions) with the specification for their [media type](media-types.md).
Blobs can be validated on their own (**intra-blob validation**) or recursively including [referenced](descriptor.md) ancestors (**recursive validation**).
* **translate**: Convert a blob between similar formats.
Translation may be **lossy** or **lossless** depending on how well the formats align.
* **put**: Add a blob to content-addressable storage like [image layout's `blobs`](image-layout.md#blobs) or a reference to location-addressable storage like [image layout's `refs`](image-layout.md#refs).
* **get**: Retrieve a blob from content-addressable storage like [image layout's `blobs`](image-layout.md#blobs) or a reference from location-addressable storage like [image layout's `refs`](image-layout.md#refs).
* **delete**: Remove a blob from content-addressable storage like [image layout's `blobs`](image-layout.md#blobs) or a reference from location-addressable storage like [image layout's `refs`](image-layout.md#refs).

## Packing Images

In packing a new image, an example workflow is:

* The [bundle][]'s [root filesystem][runtime-spec-root] is packed into a [layer](layer.md) (or layers) which are put into content-addressable storage.
* The [bundle's `config.json`][bundle] is translated into an [image configuration](config.md) which is put into content-addressable storage.
* The image configuration and layer(s) are packed into a [manifest](manifest.md) which is put into content-addressable storage.
* That manifest (and potentially other manifests) are packed into a [manifest-list](manifest-list.md) (optional) which is put into content-addressable storage.
* A reference to the manifest-list (and/or manifest) is put into location-addressable storage.

![](img/build-diagram.png)

## Unpacking Images

In unpacking an existing image, an example workflow is:

* Get an image reference from location-addressable storage like [image layout's `refs`](image-layout.md#refs) or an index based on the [associated annotations](descriptor.md#properties).
* Get the referenced [manifest-list](manifest-list.md) (optional) from content-addressable storage, validate it, and unpack it to find the appropriate [manifest](manifest.md) for the target platform.
* Get the referenced [manifest](manifest.md) from content-addressable storage, validate it, and unpack it to find the [image configuration](config.md) and [layer(s)](layer.md).
* Get the referenced [layer(s)](layer.md) from content-addressable storage, validate it, and unpack it into the [bundle][]'s [root filesystem][runtime-spec-root].
* Get the referenced [image configuration](config.md) from content-addressable storage, validate it, and translate it to a [runtime configuration][runtime-spec-config].
Write the translated configuration to the [bundle's `config.json`][bundle].

![](img/run-diagram.png)

[c99-unspecified]: http://www.open-std.org/jtc1/sc22/wg14/www/C99RationaleV5.10.pdf#page=18
[bundle]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/bundle.md
[runtime-spec-root]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md#root-configuration
[runtime-spec-config]: https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md