1# OCI Image Configuration
2
3An OCI _Image_ is an ordered collection of root filesystem changes and the corresponding execution parameters for use within a container runtime.
4This specification outlines the JSON format describing images for use with a container runtime and execution tool and its relationship to filesystem changesets, described in [Layers](layer.md).
5
6This section defines the `application/vnd.oci.image.config.v1+json` [media type](media-types.md).
7
8## Terminology
9
10This specification uses the following terms:
11
12### [Layer](layer.md)
13
14- Image filesystems are composed of _layers_.
15- Each layer represents a set of filesystem changes in a tar-based [layer format](layer.md), recording files to be added, changed, or deleted relative to its parent layer.
16- Layers do not have configuration metadata such as environment variables or default arguments - these are properties of the image as a whole rather than any particular layer.
17- Using a layer-based or union filesystem such as AUFS, or by computing the diff from filesystem snapshots, the filesystem changeset can be used to present a series of image layers as if they were one cohesive filesystem.
18
19### Image JSON
20
21- Each image has an associated JSON structure which describes some basic information about the image such as date created, author, as well as execution/runtime configuration like its entrypoint, default arguments, networking, and volumes.
22- The JSON structure also references a cryptographic hash of each layer used by the image, and provides history information for those layers.
23- This JSON is considered to be immutable, because changing it would change the computed [ImageID](#imageid).
24- Changing it means creating a new derived image, instead of changing the existing image.
25
26### Layer DiffID
27
28A layer DiffID is the digest over the layer's uncompressed tar archive and serialized in the descriptor digest format, e.g., `sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
29Layers SHOULD be packed and unpacked reproducibly to avoid changing the layer DiffID, for example by using [tar-split][] to save the tar headers.
30
31NOTE: Do not confuse DiffIDs with [layer digests](manifest.md#image-manifest-property-descriptions), often referenced in the manifest, which are digests over compressed or uncompressed content.
32
33### Layer ChainID
34
35For convenience, it is sometimes useful to refer to a stack of layers with a single identifier.
36While a layer's `DiffID` identifies a single changeset, the `ChainID` identifies the subsequent application of those changesets.
37This ensures that we have handles referring to both the layer itself, as well as the result of the application of a series of changesets.
38Use in combination with `rootfs.diff_ids` while applying layers to a root filesystem to uniquely and safely identify the result.
39
40#### Definition
41
42The `ChainID` of an applied set of layers is defined with the following recursion:
43
44```text
45ChainID(L₀) = DiffID(L₀)
46ChainID(L₀|...|Lₙ₋₁|Lₙ) = Digest(ChainID(L₀|...|Lₙ₋₁) + " " + DiffID(Lₙ))
47```
48
49For this, we define the binary `|` operation to be the result of applying the right operand to the left operand.
50For example, given base layer `A` and a changeset `B`, we refer to the result of applying `B` to `A` as `A|B`.
51
52Above, we define the `ChainID` for a single layer (`L₀`) as equivalent to the `DiffID` for that layer.
53Otherwise, the `ChainID` for a set of applied layers (`L₀|...|Lₙ₋₁|Lₙ`) is defined as the recursion `Digest(ChainID(L₀|...|Lₙ₋₁) + " " + DiffID(Lₙ))`.
54
55#### Explanation
56
57Let's say we have layers A, B, C, ordered from bottom to top, where A is the base and C is the top.
58Defining `|` as a binary application operator, the root filesystem may be `A|B|C`.
59While it is implied that `C` is only useful when applied to `A|B`, the identifier `C` is insufficient to identify this result, as we'd have the equality `C = A|B|C`, which isn't true.
60
61The main issue is when we have two definitions of `C`, `C = C` and `C = A|B|C`.
62If this is true (with some handwaving), `C = x|C` where `x = any application`.
63This means that if an attacker can define `x`, relying on `C` provides no guarantee that the layers were applied in any order.
64
65The `ChainID` addresses this problem by being defined as a compound hash.
66**We differentiate the changeset `C`, from the order-dependent application `A|B|C` by saying that the resulting rootfs is identified by ChainID(A|B|C), which can be calculated by `ImageConfig.rootfs`.**
67
68Let's expand the definition of `ChainID(A|B|C)` to explore its internal structure:
69
70```text
71ChainID(A) = DiffID(A)
72ChainID(A|B) = Digest(ChainID(A) + " " + DiffID(B))
73ChainID(A|B|C) = Digest(ChainID(A|B) + " " + DiffID(C))
74```
75
76We can replace each definition and reduce to a single equality:
77
78```text
79ChainID(A|B|C) = Digest(Digest(DiffID(A) + " " + DiffID(B)) + " " + DiffID(C))
80```
81
82Hopefully, the above is illustrative of the _actual_ contents of the `ChainID`.
83Most importantly, we can easily see that `ChainID(C) != ChainID(A|B|C)`, otherwise, `ChainID(C) = DiffID(C)`, which is the base case, could not be true.
84
85### ImageID
86
87Each image's ID is given by the SHA256 hash of its [configuration JSON](#image-json).
88It is represented as a hexadecimal encoding of 256 bits, e.g., `sha256:a9561eb1b190625c9adb5a9513e72c4dedafc1cb2d4c5236c9a6957ec7dfd5a9`.
89Since the [configuration JSON](#image-json) that gets hashed references hashes of each layer in the image, this formulation of the ImageID makes images content-addressable.
90
91## Properties
92
93Note: Any OPTIONAL field MAY also be set to null, which is equivalent to being absent.
94
95- **created** _string_, OPTIONAL
96
97 An combined date and time at which the image was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6].
98
99- **author** _string_, OPTIONAL
100
101 Gives the name and/or email address of the person or entity which created and is responsible for maintaining the image.
102
103- **architecture** _string_, REQUIRED
104
105 The CPU architecture which the binaries in this image are built to run on.
106 Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOARCH`][go-environment].
107
108- **os** _string_, REQUIRED
109
110 The name of the operating system which the image is built to run on.
111 Configurations SHOULD use, and implementations SHOULD understand, values listed in the Go Language document for [`GOOS`][go-environment].
112
113- **os.version** _string_, OPTIONAL
114
115 This OPTIONAL property specifies the version of the operating system targeted by the referenced blob.
116 Implementations MAY refuse to use manifests where `os.version` is not known to work with the host OS version.
117 Valid values are implementation-defined. e.g. `10.0.14393.1066` on `windows`.
118
119- **os.features** _array of strings_, OPTIONAL
120
121 This OPTIONAL property specifies an array of strings, each specifying a mandatory OS feature.
122 When `os` is `windows`, image indexes SHOULD use, and implementations SHOULD understand the following values:
123
124 - `win32k`: image requires `win32k.sys` on the host (Note: `win32k.sys` is missing on Nano Server)
125
126- **variant** _string_, OPTIONAL
127
128 The variant of the specified CPU architecture.
129 Configurations SHOULD use, and implementations SHOULD understand, `variant` values listed in the [Platform Variants](image-index.md#platform-variants) table.
130
131- **config** _object_, OPTIONAL
132
133 The execution parameters which SHOULD be used as a base when running a container using the image.
134 This field can be `null`, in which case any execution parameters should be specified at creation of the container.
135
136 - **User** _string_, OPTIONAL
137
138 The username or UID which is a platform-specific structure that allows specific control over which user the process run as.
139 This acts as a default value to use when the value is not specified when creating a container.
140 For Linux based systems, all of the following are valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`.
141 If `group`/`gid` is not specified, the default group and supplementary groups of the given `user`/`uid` in `/etc/passwd` and `/etc/group` from the container are applied.
142 If `group`/`gid` is specified, supplementary groups from the container are ignored.
143
144 - **ExposedPorts** _object_, OPTIONAL
145
146 A set of ports to expose from a container running this image.
147 Its keys can be in the format of:
148`port/tcp`, `port/udp`, `port` with the default protocol being `tcp` if not specified.
149 These values act as defaults and are merged with any specified when creating a container.
150 **NOTE:** This JSON structure value is unusual because it is a direct JSON serialization of the Go type `map[string]struct{}` and is represented in JSON as an object mapping its keys to an empty object.
151
152 - **Env** _array of strings_, OPTIONAL
153
154 Entries are in the format of `VARNAME=VARVALUE`.
155 These values act as defaults and are merged with any specified when creating a container.
156
157 - **Entrypoint** _array of strings_, OPTIONAL
158
159 A list of arguments to use as the command to execute when the container starts.
160 These values act as defaults and may be replaced by an entrypoint specified when creating a container.
161
162 - **Cmd** _array of strings_, OPTIONAL
163
164 Default arguments to the entrypoint of the container.
165 These values act as defaults and may be replaced by any specified when creating a container.
166 If an `Entrypoint` value is not specified, then the first entry of the `Cmd` array SHOULD be interpreted as the executable to run.
167
168 - **Volumes** _object_, OPTIONAL
169
170 A set of directories describing where the process is likely to write data specific to a container instance.
171 **NOTE:** This JSON structure value is unusual because it is a direct JSON serialization of the Go type `map[string]struct{}` and is represented in JSON as an object mapping its keys to an empty object.
172
173 - **WorkingDir** _string_, OPTIONAL
174
175 Sets the current working directory of the entrypoint process in the container.
176 This value acts as a default and may be replaced by a working directory specified when creating a container.
177
178 - **Labels** _object_, OPTIONAL
179
180 The field contains arbitrary metadata for the container.
181 This property MUST use the [annotation rules](annotations.md#rules).
182
183 - **StopSignal** _string_, OPTIONAL
184
185 The field contains the system call signal that will be sent to the container to exit. The signal can be a signal name in the format `SIGNAME`, for instance `SIGKILL` or `SIGRTMIN+3`.
186
187 - **ArgsEscaped** _boolean_, OPTIONAL
188
189 `[Deprecated]` - This field is present only for legacy compatibility with Docker and should not be used by new image builders.
190 It is used by Docker for Windows images to indicate that the `Entrypoint` or `Cmd` or both, contains only a single element array, that is a pre-escaped, and combined into a single string `CommandLine`.
191 If `true` the value in `Entrypoint` or `Cmd` should be used as-is to avoid double escaping.
192 Note, the exact behavior of `ArgsEscaped` is complex and subject to implementation details in Moby project.
193
194 - **Memory** _integer_, OPTIONAL
195
196 This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
197
198 - **MemorySwap** _integer_, OPTIONAL
199
200 This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
201
202 - **CpuShares** _integer_, OPTIONAL
203
204 This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
205
206 - **Healthcheck** _object_, OPTIONAL
207
208 This property is _reserved_ for use, to [maintain compatibility](media-types.md#compatibility-matrix).
209
210- **rootfs** _object_, REQUIRED
211
212 The rootfs key references the layer content addresses used by the image.
213 This makes the image config hash depend on the filesystem hash.
214
215 - **type** _string_, REQUIRED
216
217 MUST be set to `layers`.
218 Implementations MUST generate an error if they encounter a unknown value while verifying or unpacking an image.
219
220 - **diff_ids** _array of strings_, REQUIRED
221
222 An array of layer content hashes (`DiffIDs`), in order from first to last.
223
224- **history** _array of objects_, OPTIONAL
225
226 Describes the history of each layer.
227 The array is ordered from first to last.
228 The object has the following fields:
229
230 - **created** _string_, OPTIONAL
231
232 A combined date and time at which the layer was created, formatted as defined by [RFC 3339, section 5.6][rfc3339-s5.6].
233
234 - **author** _string_, OPTIONAL
235
236 The author of the build point.
237
238 - **created_by** _string_, OPTIONAL
239
240 The command which created the layer.
241
242 - **comment** _string_, OPTIONAL
243
244 A custom message set when creating the layer.
245
246 - **empty_layer** _boolean_, OPTIONAL
247
248 This field is used to mark if the history item created a filesystem diff.
249 It is set to true if this history item doesn't correspond to an actual layer in the rootfs section (for example, Dockerfile's [ENV](https://docs.docker.com/engine/reference/builder/#/env) command results in no change to the filesystem).
250
251Any extra fields in the Image JSON struct are considered implementation specific and MUST NOT generate an error by any implementations which are unable to interpret them.
252
253Whitespace is OPTIONAL and implementations MAY have compact JSON with no whitespace.
254
255## Example
256
257Here is an example image configuration JSON document:
258
259```json,title=Image%20JSON&mediatype=application/vnd.oci.image.config.v1%2Bjson
260{
261 "created": "2015-10-31T22:22:56.015925234Z",
262 "author": "Alyssa P. Hacker <alyspdev@example.com>",
263 "architecture": "amd64",
264 "os": "linux",
265 "config": {
266 "User": "alice",
267 "ExposedPorts": {
268 "8080/tcp": {}
269 },
270 "Env": [
271 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
272 "FOO=oci_is_a",
273 "BAR=well_written_spec"
274 ],
275 "Entrypoint": [
276 "/bin/my-app-binary"
277 ],
278 "Cmd": [
279 "--foreground",
280 "--config",
281 "/etc/my-app.d/default.cfg"
282 ],
283 "Volumes": {
284 "/var/job-result-data": {},
285 "/var/log/my-app-logs": {}
286 },
287 "WorkingDir": "/home/alice",
288 "Labels": {
289 "com.example.project.git.url": "https://example.com/project.git",
290 "com.example.project.git.commit": "45a939b2999782a3f005621a8d0f29aa387e1d6b"
291 }
292 },
293 "rootfs": {
294 "diff_ids": [
295 "sha256:c6f988f4874bb0add23a778f753c65efe992244e148a1d2ec2a8b664fb66bbd1",
296 "sha256:5f70bf18a086007016e948b04aed3b82103a36bea41755b6cddfaf10ace3c6ef"
297 ],
298 "type": "layers"
299 },
300 "history": [
301 {
302 "created": "2015-10-31T22:22:54.690851953Z",
303 "created_by": "/bin/sh -c #(nop) ADD file:a3bc1e842b69636f9df5256c49c5374fb4eef1e281fe3f282c65fb853ee171c5 in /"
304 },
305 {
306 "created": "2015-10-31T22:22:55.613815829Z",
307 "created_by": "/bin/sh -c #(nop) CMD [\"sh\"]",
308 "empty_layer": true
309 },
310 {
311 "created": "2015-10-31T22:22:56.329850019Z",
312 "created_by": "/bin/sh -c apk add curl"
313 }
314 ]
315}
316```
317
318[rfc3339-s5.6]: https://tools.ietf.org/html/rfc3339#section-5.6
319[go-environment]: https://golang.org/doc/install/source#environment
320[tar-split]: https://github.com/vbatts/tar-split
View as plain text