Skip to content

image-layout: organize for anchors #423

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.

Sign up for GitHub

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

Merged
stevvooe merged 1 commit into from
Dec 20, 2016
Merged

image-layout: organize for anchors #423

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
32 changes: 22 additions & 10 deletions image-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Given an image layout and a ref, a tool can create an [OCI Runtime Specification
* [Applying the filesystem layers](layer.md#applying) in the specified order
* Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md)

# Content

The image layout MUST contain two top level directories:

- `blobs` contains content-addressable blobs.
Expand All @@ -25,6 +27,8 @@ The image layout MUST also contain an `oci-layout` file:
- The `imageLayoutVersion` value will align with the OCI Image Specification version at the time changes to the layout are made, and will pin a given version until changes to the layout are required
- It MAY include additional fields

## Example Layout

This is an example image layout:

```
Expand All @@ -49,16 +53,9 @@ $ shasum -a 256 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935e
afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51
```

Object names in the `refs` subdirectories MUST NOT include characters outside of the set of "A" to "Z", "a" to "z", "0" to "9", the hyphen `-`, the dot `.`, and the underscore `_`.
## Refs

Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
A blob, referenced with digest `<alg>:<hex>` (per [descriptor](descriptor.md#digests-and-verification)), MUST have its content stored in a file under `blobs/<alg>/<hex>`.
The character set of the entry name for `<hex>` and `<alg>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests-and-verification).
For example `sha256:5b` will map to the layout `blobs/sha256/5b`.

The blobs directory MAY contain blobs which are not referenced by any of the refs.

The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.
Object names in the `refs` subdirectories MUST NOT include characters outside of the set of "A" to "Z", "a" to "z", "0" to "9", the hyphen `-`, the dot `.`, and the underscore `_`.

No semantic restriction is given for object names in the `refs` subdirectory.
Each object in the `refs` subdirectory MUST be of type `application/vnd.oci.descriptor.v1+json`.
Expand All @@ -70,7 +67,7 @@ For example, an image may have a tag for different versions or builds of the sof
In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc.
Those tags will often be represented in an image-layout repository with matching refs names like "v1.0.0-vendor.0", "2.0.0-debug", etc.

This illustrates the expected contents of a given ref, the manifest list it points to and the blobs the manifest references.
### Example Ref

```
$ cat ./refs/v1.0 | jq
Expand All @@ -81,6 +78,21 @@ $ cat ./refs/v1.0 | jq
}
```

This illustrates the expected contents of a given ref, the manifest list it points to and the blobs the manifest references.
Copy link
Contributor

@wking wking Oct 28, 2016

Choose a reason for hiding this comment

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

Looking at this line more closely after it was shifted, what is it actually saying? “contents of a given ref” sounds like “a descriptor”, so ok. “the manifest list it points to” might be the descriptor again. But how is this illustrating “thte blobs the manifest references”? Maybe we should drop this line entirely.

Copy link
Contributor

@wking wking Oct 28, 2016

Choose a reason for hiding this comment

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

Looks like the “blobs the manifest references” wording came in with 2f24791, #136. I think we either want to revert the changes 2f24791 made to this line or drop the line. CC @runcom.

Copy link
Member Author

@vbatts vbatts Oct 31, 2016

Choose a reason for hiding this comment

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

Separate concern from this PR

Copy link
Contributor

@wking wking Oct 31, 2016

Choose a reason for hiding this comment

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

Spun off into #427.


## Blobs

Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content.
A blob, referenced with digest `<alg>:<hex>` (per [descriptor](descriptor.md#digests-and-verification)), MUST have its content stored in a file under `blobs/<alg>/<hex>`.
The character set of the entry name for `<hex>` and `<alg>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests-and-verification).
For example `sha256:5b` will map to the layout `blobs/sha256/5b`.

The blobs directory MAY contain blobs which are not referenced by any of the refs.

The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store.

### Example Blobs

```
$ cat ./blobs/sha256/e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f | jq
{
Expand Down