2015-10-02 22:43:16 +08:00
# Filesystem Bundle
2015-09-11 02:36:13 +08:00
## Container Format
2015-06-25 08:15:48 +08:00
2015-10-02 22:43:16 +08:00
This section defines a format for encoding a container as a *filesystem bundle* - a set of files organized in a certain way, and containing all the necessary data and metadata for any compliant runtime to perform all standard operations against it.
2015-09-09 22:17:06 +08:00
See also [OS X application bundles ](http://en.wikipedia.org/wiki/Bundle_%28OS_X%29 ) for a similar use of the term *bundle* .
2015-06-25 08:15:48 +08:00
2015-10-02 22:43:16 +08:00
The definition of a bundle is only concerned with how a container, and its configuration data, are stored on a local file system so that it can be consumed by a compliant runtime.
2015-06-25 08:15:48 +08:00
2015-10-02 22:43:16 +08:00
A Standard Container bundle contains all the information needed to load and run a container.
2016-04-23 02:44:12 +08:00
This MUST include the following artifacts:
2015-06-25 08:15:48 +08:00
config: Single, unified config file
Reverting 7232e4b1 (specs: introduce the concept of a runtime.json,
2015-07-30, #88) after discussion on the mailing list [1]. The main
reason is that it's hard to draw a clear line around "inherently
runtime-specific" or "non-portable", so we shouldn't try to do that in
the spec. Folks who want to flag settings as non-portable for their
own system are welcome to do so (e.g. "we will clobber 'hooks' in
bundles we run") are welcome to do so, but we don't have to have
to split the config into multiple files to do that.
There have been a number of additional changes since #88, so this
isn't a pure Git reversion. Besides copy-pasting and the associated
link-target updates, I've:
* Restored path -> destination, now that the mount type contains both
source and target paths again. I'd prefer 'target' to 'destination'
to match mount(2), but the pre-7232e4b1 phrasing was 'destination'
(possibly due to Windows using 'target' for the source?).
* Restored the Windows mount example to its pre-7232e4b1 content.
* Removed required mounts from the config example (requirements landed
in 3848a238, config-linux: specify the default devices/filesystems
available, 2015-09-09, #164), because specifying those mounts in the
config is now redundant.
* Used headers (vs. bold paragraphs) to set off mount examples so we
get link anchors in the rendered Markdown.
* Replaced references to runtime.json with references to config.json.
[1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY
Subject: Single, unified config file (i.e. rolling back specs#88)
Date: Wed, 4 Nov 2015 09:53:20 -0800
Message-ID: <20151104175320.GC24652@odin.tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
1. `config.json` : contains configuration data.
2016-04-23 02:44:12 +08:00
This REQUIRED file MUST reside in the root of the bundle directory and MUST be named `config.json` .
2015-10-30 22:32:56 +08:00
When the bundle is packaged up for distribution, this file MUST be included.
2015-10-02 22:43:16 +08:00
See [`config.json` ](config.md ) for more details.
2015-06-25 08:15:48 +08:00
config: Single, unified config file
Reverting 7232e4b1 (specs: introduce the concept of a runtime.json,
2015-07-30, #88) after discussion on the mailing list [1]. The main
reason is that it's hard to draw a clear line around "inherently
runtime-specific" or "non-portable", so we shouldn't try to do that in
the spec. Folks who want to flag settings as non-portable for their
own system are welcome to do so (e.g. "we will clobber 'hooks' in
bundles we run") are welcome to do so, but we don't have to have
to split the config into multiple files to do that.
There have been a number of additional changes since #88, so this
isn't a pure Git reversion. Besides copy-pasting and the associated
link-target updates, I've:
* Restored path -> destination, now that the mount type contains both
source and target paths again. I'd prefer 'target' to 'destination'
to match mount(2), but the pre-7232e4b1 phrasing was 'destination'
(possibly due to Windows using 'target' for the source?).
* Restored the Windows mount example to its pre-7232e4b1 content.
* Removed required mounts from the config example (requirements landed
in 3848a238, config-linux: specify the default devices/filesystems
available, 2015-09-09, #164), because specifying those mounts in the
config is now redundant.
* Used headers (vs. bold paragraphs) to set off mount examples so we
get link anchors in the rendered Markdown.
* Replaced references to runtime.json with references to config.json.
[1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY
Subject: Single, unified config file (i.e. rolling back specs#88)
Date: Wed, 4 Nov 2015 09:53:20 -0800
Message-ID: <20151104175320.GC24652@odin.tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
2. A directory representing the root filesystem of the container.
2015-10-02 22:43:16 +08:00
While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs` .
2015-10-30 22:32:56 +08:00
When the bundle is packaged up for distribution, this directory MUST be included.
2015-10-02 22:43:16 +08:00
This directory MUST be referenced from within the `config.json` file.
2015-06-25 08:15:48 +08:00
config: Single, unified config file
Reverting 7232e4b1 (specs: introduce the concept of a runtime.json,
2015-07-30, #88) after discussion on the mailing list [1]. The main
reason is that it's hard to draw a clear line around "inherently
runtime-specific" or "non-portable", so we shouldn't try to do that in
the spec. Folks who want to flag settings as non-portable for their
own system are welcome to do so (e.g. "we will clobber 'hooks' in
bundles we run") are welcome to do so, but we don't have to have
to split the config into multiple files to do that.
There have been a number of additional changes since #88, so this
isn't a pure Git reversion. Besides copy-pasting and the associated
link-target updates, I've:
* Restored path -> destination, now that the mount type contains both
source and target paths again. I'd prefer 'target' to 'destination'
to match mount(2), but the pre-7232e4b1 phrasing was 'destination'
(possibly due to Windows using 'target' for the source?).
* Restored the Windows mount example to its pre-7232e4b1 content.
* Removed required mounts from the config example (requirements landed
in 3848a238, config-linux: specify the default devices/filesystems
available, 2015-09-09, #164), because specifying those mounts in the
config is now redundant.
* Used headers (vs. bold paragraphs) to set off mount examples so we
get link anchors in the rendered Markdown.
* Replaced references to runtime.json with references to config.json.
[1]: https://groups.google.com/a/opencontainers.org/forum/#!topic/dev/0QbyJDM9fWY
Subject: Single, unified config file (i.e. rolling back specs#88)
Date: Wed, 4 Nov 2015 09:53:20 -0800
Message-ID: <20151104175320.GC24652@odin.tremily.us>
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-29 02:06:40 +08:00
While these artifacts MUST all be present in a single directory on the local filesystem, that directory itself is not part of the bundle.
2015-10-02 22:43:16 +08:00
In other words, a tar archive of a *bundle* will have these artifacts at the root of the archive, not nested within a top-level directory.
