1## OCI Image Layout Specification 2 3* The OCI Image Layout is directory structure for OCI content-addressable blobs and [location-addressable](https://en.wikipedia.org/wiki/Content-addressable_storage#Content-addressed_vs._location-addressed) references (refs). 4* This layout MAY be used in a variety of different transport mechanisms: archive formats (e.g. tar, zip), shared filesystem environments (e.g. nfs), or networked file fetching (e.g. http, ftp, rsync). 5 6Given an image layout and a ref, a tool can create an [OCI Runtime Specification bundle](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/bundle.md) by: 7 8* Following the ref to find a [manifest](manifest.md#image-manifest), possibly via an [image index](image-index.md) 9* [Applying the filesystem layers](layer.md#applying) in the specified order 10* Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0/config.md) 11 12# Content 13 14The image layout is as follows: 15 16- `blobs` directory 17 - Contains content-addressable blobs 18 - A blob has no schema and SHOULD be considered opaque 19 - Directory MUST exist and MAY be empty 20 - See [blobs](#blobs) section 21- `oci-layout` file 22 - It MUST exist 23 - It MUST be a JSON object 24 - It MUST contain an `imageLayoutVersion` field 25 - See [oci-layout file](#oci-layout-file) section 26 - It MAY include additional fields 27- `index.json` file 28 - It MUST exist 29 - It MUST be an [image index](image-index.md) JSON object. 30 - See [index.json](#indexjson-file) section 31 32## Example Layout 33 34This is an example image layout: 35 36``` 37$ cd example.com/app/ 38$ find . -type f 39./index.json 40./oci-layout 41./blobs/sha256/3588d02542238316759cbf24502f4344ffcc8a60c803870022f335d1390c13b4 42./blobs/sha256/4b0bc1c4050b03c95ef2a8e36e25feac42fd31283e8c30b3ee5df6b043155d3c 43./blobs/sha256/7968321274dc6b6171697c33df7815310468e694ac5be0ec03ff053bb135e768 44``` 45 46Blobs are named by their contents: 47 48``` 49$ shasum -a 256 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 50afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 51``` 52 53## Blobs 54 55* Object names in the `blobs` subdirectories are composed of a directory for each hash algorithm, the children of which will contain the actual content. 56* The content of `blobs/<alg>/<encoded>` MUST match the digest `<alg>:<encoded>` (referenced per [descriptor](descriptor.md#digests)). For example, the content of `blobs/sha256/da39a3ee5e6b4b0d3255bfef95601890afd80709` MUST match the digest `sha256:da39a3ee5e6b4b0d3255bfef95601890afd80709`. 57* The character set of the entry name for `<alg>` and `<encoded>` MUST match the respective grammar elements described in [descriptor](descriptor.md#digests). 58* The blobs directory MAY contain blobs which are not referenced by any of the [refs](#indexjson-file). 59* The blobs directory MAY be missing referenced blobs, in which case the missing blobs SHOULD be fulfilled by an external blob store. 60 61### Example Blobs 62 63``` 64$ cat ./blobs/sha256/9b97579de92b1c195b85bb42a11011378ee549b02d7fe9c17bf2a6b35d5cb079 | jq 65{ 66 "schemaVersion": 2, 67 "manifests": [ 68 { 69 "mediaType": "application/vnd.oci.image.manifest.v1+json", 70 "size": 7143, 71 "digest": "sha256:afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51", 72 "platform": { 73 "architecture": "ppc64le", 74 "os": "linux" 75 } 76 }, 77... 78``` 79 80``` 81$ cat ./blobs/sha256/afff3924849e458c5ef237db5f89539274d5e609db5db935ed3959c90f1f2d51 | jq 82{ 83 "schemaVersion": 2, 84 "config": { 85 "mediaType": "application/vnd.oci.image.config.v1+json", 86 "size": 7023, 87 "digest": "sha256:5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270" 88 }, 89 "layers": [ 90 { 91 "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip", 92 "size": 32654, 93 "digest": "sha256:9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0" 94 }, 95... 96``` 97 98``` 99$ cat ./blobs/sha256/5b0bcabd1ed22e9fb1310cf6c2dec7cdef19f0ad69efa1f392e94a4333501270 | jq 100{ 101 "architecture": "amd64", 102 "author": "Alyssa P. Hacker <alyspdev@example.com>", 103 "config": { 104 "Hostname": "8dfe43d80430", 105 "Domainname": "", 106 "User": "", 107 "AttachStdin": false, 108 "AttachStdout": false, 109 "AttachStderr": false, 110 "Tty": false, 111 "OpenStdin": false, 112 "StdinOnce": false, 113 "Env": [ 114 "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" 115 ], 116 "Cmd": null, 117 "Image": "sha256:6986ae504bbf843512d680cc959484452034965db15f75ee8bdd1b107f61500b", 118... 119``` 120 121``` 122$ cat ./blobs/sha256/9834876dcfb05cb167a5c24953eba58c4ac89b1adf57f28f2f9d09af107ee8f0 123[gzipped tar stream] 124``` 125 126## oci-layout file 127 128This JSON object serves as a marker for the base of an Open Container Image Layout and to provide the version of the image-layout in use. 129The `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 image layout are required. 130This section defines the `application/vnd.oci.layout.header.v1+json` [media type](media-types.md). 131 132### oci-layout Example 133 134```json,title=OCI%20Layout&mediatype=application/vnd.oci.layout.header.v1%2Bjson 135{ 136 "imageLayoutVersion": "1.0.0" 137} 138``` 139 140## index.json file 141 142This REQUIRED file is the entry point for references and descriptors of the image-layout. 143The [image index](image-index.md) is a multi-descriptor entry point. 144 145This index provides an established path (`/index.json`) to have an entry point for an image-layout and to discover auxiliary descriptors. 146 147* No semantic restriction is given for the "org.opencontainers.image.ref.name" annotation of descriptors. 148* In general the `mediaType` of each [descriptor][descriptors] object in the `manifests` field will be either `application/vnd.oci.image.index.v1+json` or `application/vnd.oci.image.manifest.v1+json`. 149* Future versions of the spec MAY use a different mediatype (i.e. a new versioned format). 150* An encountered `mediaType` that is unknown SHOULD be safely ignored. 151 152 153**Implementor's Note:** 154A common use case of descriptors with a "org.opencontainers.image.ref.name" annotation is representing a "tag" for a container image. 155For example, an image may have a tag for different versions or builds of the software. 156In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc. 157Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc. 158 159 160### Index Example 161 162```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson 163{ 164 "schemaVersion": 2, 165 "manifests": [ 166 { 167 "mediaType": "application/vnd.oci.image.index.v1+json", 168 "size": 7143, 169 "digest": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd", 170 "annotations": { 171 "org.opencontainers.image.ref.name": "stable-release" 172 } 173 }, 174 { 175 "mediaType": "application/vnd.oci.image.manifest.v1+json", 176 "size": 7143, 177 "digest": "sha256:e692418e4cbaf90ca69d05a66403747baa33ee08806650b51fab815ad7fc331f", 178 "platform": { 179 "architecture": "ppc64le", 180 "os": "linux" 181 }, 182 "annotations": { 183 "org.opencontainers.image.ref.name": "v1.0" 184 } 185 }, 186 { 187 "mediaType": "application/xml", 188 "size": 7143, 189 "digest": "sha256:b3d63d132d21c3ff4c35a061adf23cf43da8ae054247e32faa95494d904a007e", 190 "annotations": { 191 "org.freedesktop.specifications.metainfo.version": "1.0", 192 "org.freedesktop.specifications.metainfo.type": "AppStream" 193 } 194 } 195 ], 196 "annotations": { 197 "com.example.index.revision": "r124356" 198 } 199} 200``` 201 202This illustrates an index that provides two named manifest references and an auxiliary mediatype for this image layout. 203 204 205[descriptors]: ./descriptor.md 206