Skip to content

Commit 39b2390

Browse files
duglinDoug Davis
duglin
authored and
Doug Davis
committed
Create image.md
Signed-off-by: Doug Davis <dug@us.ibm.com>
1 parent b6d9ebf commit 39b2390

File tree

2 files changed

+137
-0
lines changed

2 files changed

+137
-0
lines changed

‎README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Table of Contents
88
- [Container Principles](principles.md)
99
- [Specification Style](style.md)
1010
- [Filesystem Bundle](bundle.md)
11+
- [Image](image.md)
1112
- Configuration
1213
- [General](config.md)
1314
- [Linux-specific](config-linux.md)

‎image.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# Image
2+
3+
This section defines a format for encoding a container's *filesytem bundle* as a portable *image*.
4+
An image is a set of files organized in a certain way, and containing all of the necessary data and metadata, for any compliant runtime to verify the validity of the image's contents and to construct a filesystem bundle represented by the image.
5+
Images are meant to be portable such that they can be used to reliably move filesystem bundles between instances of OCI compliant implementations.
6+
7+
## Image Contents
8+
9+
A compliant image contains the following pieces of information:
10+
11+
1. An OCI [`config.json`](config.md) file.
12+
This file is REQUIRED to be present in the image, unless this image is a dependent image, in which case it is OPTIONAL.
13+
The `config.json` file contains the host independent configuration information necessary to execute the container.
14+
See [`config.json`](config.md) for more information.
15+
16+
1. The root filesystem of the filesystem bundle.
17+
This directory MUST be present in the image, however it MAY be empty (not contain any files or folders).
18+
As specified in the `config.json` file, this directory contains the files that make up the root filesystem of the container.
19+
This directory MAY contain only a portion of the complete set of files that make up the filesystem bundle, in which case the remaining set of files MUST be found in one of the dependent images.
20+
21+
1. References to dependent images.
22+
If present, this OPTIONAL information MUST be in a file called `required.json`.
23+
This file MUST be a JSON encoded array of references to images as specified in the [Dependent Images](#dependent-images) section.
24+
25+
1. Dependent images.
26+
An image MAY choose to include dependent images as directories within the image.
27+
If present, each dependent image MUST be placed in a directory whose name is the same as its ID.
28+
Within each directory MUST be a complete OCI compliant image definition.
29+
Note that within each dependent image's directory there MAY be a whiteout.json file.
30+
31+
1. Whiteout list.
32+
An image MAY choose to include a list of files that are to be considered to be deleted from the root filesystem even though they are included within the image's root filesystem directory.
33+
It is an implementation detail to decide how this whiteout list is processed but an implementation MUST ensure that any container that is created from this image will behave the same as if those files were not in the root filesystem at all.
34+
The whiteout list MUST be in a file called `whiteout.json`.
35+
See the [Whiteout List](#whiteout-list) section for more details.
36+
37+
1. Extension files.
38+
An image MAY choose to include additional files and directories in the image.
39+
40+
1. The ID of the image.
41+
This REQUIRED information MUST be in a file called `ID`.
42+
See the [Image ID](#image-id) section for more details.
43+
44+
## Serialization of an Image
45+
46+
An image MUST be a `tar` of the pieces of data that make up an image as specified in the [Image Contents](#image-contents) section.
47+
The order in which the data is serialized in the `tar` MUST be the same as the order specified in that section.
48+
The serialization of the "dependent images" MUST be in the same order in which those dependent images are listed in the `requires.json` file.
49+
The serialization of the "extension files" MUST be in case-sensitive alphabetical order.
50+
51+
Each file or directory specified in the [Image Contents](#image-contents) section MUST appear at the root of the `tar` without a leading `/` in their names.
52+
53+
For example, a listing of the `tar` of an image might look like this:
54+
```
55+
config.json
56+
rootfs/
57+
bin/myapp
58+
requires.json
59+
sha512-1d62d181e9c1322d56ccd3a29d05018399147a16188dbd861c0279ad0dd7e14c/
60+
config.json
61+
rootfs/
62+
bin/runit
63+
whiteout.json
64+
ID
65+
sha512-291e2a171ef9bef8a838c59406d9b0aeb6f2f0ebe5173415205733d3d18b8e03/
66+
config.json
67+
rootfs/
68+
bin/monitor
69+
whiteout.json
70+
ID
71+
whiteout.json
72+
ID
73+
```
74+
75+
## Dependent Images
76+
77+
If an image has dependent images then it MUST include a `requires.json` file that references those images.
78+
The `requires.json` file MUST be a JSON encoded array matching this format:
79+
```
80+
{
81+
"requires": [
82+
{
83+
"ID": "..."
84+
},
85+
{
86+
"ID": "..."
87+
}, ...
88+
]
89+
}
90+
```
91+
92+
The order of the images, `ID`s, in the array MUST be in the order in which the images are to be "layed down" into the filesystem bundle that is generated from this image.
93+
In other words, the first image in the array is written to the filesystem first, and subsequent images are overlayed on top - potentially overlaying an ealier image's files.
94+
95+
## Image ID
96+
97+
An image's `ID` MUST be a cryptographic hash of image's contents in the order specified in the [Image Contents](#image-contents) section.
98+
99+
An image's `ID` MUST be a string of the form `<algorithm>-<hash value>`.
100+
The `algorithm` part of the string MUST be in lower-case.
101+
For example, `sha512` not `SHA512`.
102+
103+
It is RECOMMENDED that implementations use the sha512 algorithm.
104+
105+
## Whiteout List
106+
107+
An image's `whiteout.json` file MUST be a JSON encoded file matching this format:
108+
```
109+
{
110+
"files": [
111+
"filename",
112+
...
113+
]
114+
}
115+
```
116+
where each `filename` MUST be the absolute path to the file.
117+
118+
## Expanding an Image to Create a Filesystem Bundle
119+
120+
When an image is expanded to create a filesystem bundle the image's `config.json` file MUST be written to the root of the filesystem bundle's directory.
121+
The expansion process MUST create a directory for the container's root filesystem with a name as specified in the `config.json` file - ie. the `root/path` property.
122+
The contents of this directory MUST appear to be materizlied in such a way as to contain all of the files from the image, without the whiteout (deleted) files, and its dependent images.
123+
The exact mechanism, process and order, by which those files are materialized on disk is an implementation detail, however in the end it MUST appear as though all of the files from the images were written to disk in the order they were specified in the `requires.json` file.
124+
This means that each dependent image's `whiteout.json` file MUST appear to be processed during the materialization of that image so that if a subsequent image creates a file by the same name as one mentioned in the `whiteout.json` file then it will not be deleted.
125+
126+
The `config.json` file of any dependent images, if present, are ignored by the expansion process.
127+
128+
This specification does not mandate any requirements on the processing of the extension files.
129+
In other words, implementations are not required to materialize them on disk in the filesystem bundle.
130+
131+
This specification does not mandate any ordering to when each piece of information from the image is materialized.
132+
133+
## Misc Notes
134+
135+
There is no requirement that importing an image into a compliant OCI implementation and then exporting it will result in the same image since each implementation might choose to create the root filesystem differently.
136+
Thus, exporting that root filesystem might look different from the original image.

0 commit comments

Comments
 (0)