2016-11-30 16:33:27 -08:00
# <a name="glossary" />Glossary
2015-08-11 10:15:20 -07:00
2016-11-30 16:33:27 -08:00
## <a name="glossaryBundle" />Bundle
2015-08-11 10:15:20 -07:00
A [directory structure ](bundle.md ) that is written ahead of time, distributed, and used to seed the runtime for creating a [container ](#container ) and launching a process within it.
2016-11-30 16:33:27 -08:00
## <a name="glossaryConfiguration" />Configuration
2015-08-11 10:15:20 -07: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-28 10:06:40 -08:00
The [`config.json` ](config.md ) file in a [bundle ](#bundle ) which defines the intended [container ](#container ) and container process.
2015-08-11 10:15:20 -07:00
2016-11-30 16:33:27 -08:00
## <a name="glossaryContainer" />Container
2015-08-11 10:15:20 -07:00
An environment for executing processes with configurable isolation and resource limitations.
For example, namespaces, resource limits, and mounts are all part of the container environment.
2016-11-30 16:33:27 -08:00
## <a name="glossaryContainerNamespace" />Container namespace
config-linux: Specify host mount namespace for namespace paths
Avoid trouble with situations like:
# mount --bind /mnt/test /mnt/test
# mount --make-rprivate /mnt/test
# touch /mnt/test/mnt /mnt/test/user
# mount --bind /proc/123/ns/mnt /mnt/test/mnt
# mount --bind /proc/123/ns/user /mnt/test/user
# nsenter --mount=/proc/123/ns/mnt --user /proc/123/ns/user sh
which uses the required private mount for binding mount namespace
references [1,2,3]. We want to avoid:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime joins the mount namespace referenced by fd 3.
3. Runtime fails to open /mnt/test/user, because /mnt/test is not
visible in the current mount namespace.
and instead get runtime authors to setup flows like:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime opens /mnt/test/user as fd 4.
3. Runtime joins the mount namespace referenced by fd 3.
4. Runtime joins the user namespace referenced by fd 4.
This also applies to new namespace creation. We want to avoid:
1. Runtime clones a container process with a new mount namespace.
2c. Container process fails to open /mnt/test/user, because /mnt/test
is not visible in the current mount namespace.
in favor of something like:
1. Runtime opens /mnt/test/user as fd 3.
2. Runtime clones a container process with a new mount namespace.
3h. Host process closes unneeded fd 3.
3c. Container process joins the user namespace referenced by fd 3.
I also define runtime and container namespaces, so we have consistent
terminology. I prefer:
* host namespace: a namespace you are in when you invoke the runtime
* host process: the runtime process invoked by the user
* container process: the process created by a clone call in the host
process which will eventually execute the user-configured process.
Both the host and container processes are running runtime code
(although the container process eventually transitions to
user-configured code), so I find "runtime process", "runtime
namespace", etc. to be imprecise. However, the maintainer consensus
is for "runtime namespace" [4,5], so that's what we're going with
here.
[1]: http://karelzak.blogspot.com/2015/04/persistent-namespaces.html
[2]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=4ce5d2b1a8fde84c0eebe70652cf28b9beda6b4e
[3]: http://mid.gmane.org/87haeahkzc.fsf@xmission.com
[4]: https://github.com/opencontainers/specs/pull/275#discussion_r48057211
[5]: https://github.com/opencontainers/specs/pull/275#discussion_r48324264
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-18 10:42:33 -08:00
2017-05-24 09:30:01 -07:00
On Linux,the [namespaces][namespaces.7] in which the [configured process ](config.md#process ) executes.
config-linux: Specify host mount namespace for namespace paths
Avoid trouble with situations like:
# mount --bind /mnt/test /mnt/test
# mount --make-rprivate /mnt/test
# touch /mnt/test/mnt /mnt/test/user
# mount --bind /proc/123/ns/mnt /mnt/test/mnt
# mount --bind /proc/123/ns/user /mnt/test/user
# nsenter --mount=/proc/123/ns/mnt --user /proc/123/ns/user sh
which uses the required private mount for binding mount namespace
references [1,2,3]. We want to avoid:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime joins the mount namespace referenced by fd 3.
3. Runtime fails to open /mnt/test/user, because /mnt/test is not
visible in the current mount namespace.
and instead get runtime authors to setup flows like:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime opens /mnt/test/user as fd 4.
3. Runtime joins the mount namespace referenced by fd 3.
4. Runtime joins the user namespace referenced by fd 4.
This also applies to new namespace creation. We want to avoid:
1. Runtime clones a container process with a new mount namespace.
2c. Container process fails to open /mnt/test/user, because /mnt/test
is not visible in the current mount namespace.
in favor of something like:
1. Runtime opens /mnt/test/user as fd 3.
2. Runtime clones a container process with a new mount namespace.
3h. Host process closes unneeded fd 3.
3c. Container process joins the user namespace referenced by fd 3.
I also define runtime and container namespaces, so we have consistent
terminology. I prefer:
* host namespace: a namespace you are in when you invoke the runtime
* host process: the runtime process invoked by the user
* container process: the process created by a clone call in the host
process which will eventually execute the user-configured process.
Both the host and container processes are running runtime code
(although the container process eventually transitions to
user-configured code), so I find "runtime process", "runtime
namespace", etc. to be imprecise. However, the maintainer consensus
is for "runtime namespace" [4,5], so that's what we're going with
here.
[1]: http://karelzak.blogspot.com/2015/04/persistent-namespaces.html
[2]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=4ce5d2b1a8fde84c0eebe70652cf28b9beda6b4e
[3]: http://mid.gmane.org/87haeahkzc.fsf@xmission.com
[4]: https://github.com/opencontainers/specs/pull/275#discussion_r48057211
[5]: https://github.com/opencontainers/specs/pull/275#discussion_r48324264
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-18 10:42:33 -08:00
2023-05-16 19:48:03 +09:00
## <a name="glossaryFeaturesDocument" />Features Structure
2021-12-09 16:45:04 +09:00
2023-05-16 19:48:03 +09:00
A [JSON][] structure that represents [the implemented features ](#features.md ) of the [runtime ](#runtime ).
2021-12-09 16:45:04 +09:00
Irrelevant to the actual availability of the features in the host operating system.
2016-11-30 16:33:27 -08:00
## <a name="glossaryJson" />JSON
2015-09-25 15:09:03 -07:00
All configuration [JSON][] MUST be encoded in [UTF-8][].
2016-09-27 09:18:55 -07:00
JSON objects MUST NOT include duplicate names.
The order of entries in JSON objects is not significant.
2015-09-25 15:09:03 -07:00
2016-11-30 16:33:27 -08:00
## <a name="glossaryRuntime" />Runtime
2015-08-11 10:15:20 -07:00
An implementation of this specification.
It reads the [configuration files ](#configuration ) from a [bundle ](#bundle ), uses that information to create a [container ](#container ), launches a process inside the container, and performs other [lifecycle actions ](runtime.md ).
2015-09-25 15:09:03 -07:00
2021-12-09 16:45:04 +09:00
## <a name="glossaryRuntimeCaller" />Runtime caller
An external program to execute a [runtime ](#runtime ), directly or indirectly.
Examples of direct callers include containerd, CRI-O, and Podman.
Examples of indirect callers include Docker/Moby and Kubernetes.
Runtime callers often execute a runtime via [runc][]-compatible command line interface, however, its interaction interface is currently out of the scope of the Open Container Initiative Runtime Specification.
2016-11-30 16:33:27 -08:00
## <a name="glossaryRuntimeNamespace" />Runtime namespace
config-linux: Specify host mount namespace for namespace paths
Avoid trouble with situations like:
# mount --bind /mnt/test /mnt/test
# mount --make-rprivate /mnt/test
# touch /mnt/test/mnt /mnt/test/user
# mount --bind /proc/123/ns/mnt /mnt/test/mnt
# mount --bind /proc/123/ns/user /mnt/test/user
# nsenter --mount=/proc/123/ns/mnt --user /proc/123/ns/user sh
which uses the required private mount for binding mount namespace
references [1,2,3]. We want to avoid:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime joins the mount namespace referenced by fd 3.
3. Runtime fails to open /mnt/test/user, because /mnt/test is not
visible in the current mount namespace.
and instead get runtime authors to setup flows like:
1. Runtime opens /mnt/test/mnt as fd 3.
2. Runtime opens /mnt/test/user as fd 4.
3. Runtime joins the mount namespace referenced by fd 3.
4. Runtime joins the user namespace referenced by fd 4.
This also applies to new namespace creation. We want to avoid:
1. Runtime clones a container process with a new mount namespace.
2c. Container process fails to open /mnt/test/user, because /mnt/test
is not visible in the current mount namespace.
in favor of something like:
1. Runtime opens /mnt/test/user as fd 3.
2. Runtime clones a container process with a new mount namespace.
3h. Host process closes unneeded fd 3.
3c. Container process joins the user namespace referenced by fd 3.
I also define runtime and container namespaces, so we have consistent
terminology. I prefer:
* host namespace: a namespace you are in when you invoke the runtime
* host process: the runtime process invoked by the user
* container process: the process created by a clone call in the host
process which will eventually execute the user-configured process.
Both the host and container processes are running runtime code
(although the container process eventually transitions to
user-configured code), so I find "runtime process", "runtime
namespace", etc. to be imprecise. However, the maintainer consensus
is for "runtime namespace" [4,5], so that's what we're going with
here.
[1]: http://karelzak.blogspot.com/2015/04/persistent-namespaces.html
[2]: https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/commit/?id=4ce5d2b1a8fde84c0eebe70652cf28b9beda6b4e
[3]: http://mid.gmane.org/87haeahkzc.fsf@xmission.com
[4]: https://github.com/opencontainers/specs/pull/275#discussion_r48057211
[5]: https://github.com/opencontainers/specs/pull/275#discussion_r48324264
Signed-off-by: W. Trevor King <wking@tremily.us>
2015-12-18 10:42:33 -08:00
2017-05-24 09:38:11 -07:00
On Linux, the namespaces from which new [container namespaces ](#container-namespace ) are [created ](config-linux.md#namespaces ) and from which some configured resources are accessed.
2017-02-09 15:32:39 -05:00
2018-02-20 10:35:21 -08:00
[JSON]: https://tools.ietf.org/html/rfc8259
2024-11-04 12:25:33 +01:00
[UTF-8]: https://www.unicode.org/versions/Unicode8.0.0/ch03.pdf
2021-12-09 16:45:04 +09:00
[runc]: https://github.com/opencontainers/runc
2017-02-09 15:32:39 -05:00
2024-11-04 12:25:33 +01:00
[namespaces.7]: https://man7.org/linux/man-pages/man7/namespaces.7.html
