The kernel ABI to these values is a string, which accepts the value `-1`
to mean "unlimited" or an integer up to 2^63 for an amount of memory in
bytes.
While the internal representation in the kernel is unsigned, this is not
exposed in any ABI directly. Because of the user-kernel memory split, values
over 2^63 are not really useful; indeed that much memory is not supported,
as physical memory is limited to 52 bits in the forthcoming switch to five
level page tables. So it is much more natural to support the value `-1` for
unlimited, especially as the actual number needed to represent the maximum
has varied in different kernel versions, and across 32 and 64 bit architectures,
so determining the value to use is not possible, so it is necessary to write
the string `-1` to the cgroup files.
See also discussion in
- https://github.com/opencontainers/runc/pull/1494
- https://github.com/opencontainers/runc/pull/1492
- https://github.com/opencontainers/runc/pull/1375
- https://github.com/opencontainers/runc/issues/1421
Signed-off-by: Justin Cormack <justin.cormack@docker.com>
Instead of repeating the config.md conditions, just make the linkage
more clear. Now the chain is:
1. Bundles REQUIRE a config.json which is a bundle artifact.
2. If that config.json has a root.path entry (as specified in
config.md), then add the referenced directory to the set of bundle
artifacts. The config.md requirements include "If defined, a
directory MUST exist at the path declared by the field".
3. Apply the "MUST all be present in a single directory" condition to
all bundle artifacts. I don't like that direct-child restriction
[1], but I'm not touching it in this commit.
So these are the same requirements as before this commit, but with
less redundancy and fewer words.
[1]: https://github.com/opencontainers/runtime-spec/pull/469
Signed-off-by: W. Trevor King <wking@tremily.us>
The old language is from a502caf6 (config: Add consoleSize to process,
2016-09-14, #563), where nobody commented on the "if attached" wording
[1]. But reading the old line now, it's not clear to me what
consoleSize means when terminal is not true.
This commit explicitly declares consoleSize ignored in that condition.
I'd rather have made it unspecified, so runtimes are free to do what
they want short of erroring out, but Michael wanted the more specific
"ignored" [2]. I considered making the property undefined or
requiring it to be unset, but those seemed too strict given our
permissive "MUST ignore unknown properties" extensibility requirement.
[1]: https://github.com/opencontainers/runtime-spec/pull/563
[2]: https://github.com/opencontainers/runtime-spec/pull/863#discussion_r119682760
Signed-off-by: W. Trevor King <wking@tremily.us>
Namespaces are not all hierarchical and processes aren't always in
leaves. Also punt to config-linux.md for details about namespace
creation, although currently that section doesn't talk much about how
the runtime namespaces relate to new container namespaces [1].
Also mention resource access, because runtime namespaces play a role
even if no new container namespaces are created. I've used resources
that currently explicitly mention runtime namespaces as examples,
although I think more resources (e.g. root.path and mounts[].source
[2,3]) deserve wording about that as well and would be better examples
if they'd already landed such wording.
Examples of resources retrieved from this namespace include
linux.namespaces[].path and the resctrl psuedo-filesystem used for
`linux.intelRdt`, but Mrunal and Michael didn't want me to include the
examples in the glossary entry (probably because they could go stale).
[1]: https://github.com/opencontainers/runtime-spec/pull/795#issuecomment-303768518
[2]: https://github.com/opencontainers/runtime-spec/pull/735#issuecomment-301198710
[3]: https://github.com/opencontainers/runtime-spec/commit/604205e5e1b58854c43e07901d3ec241df31df4e#diff-c9c91c29b41257aea3a3403cc606ad99R65
Signed-off-by: W. Trevor King <wking@tremily.us>
This line landed in 718f9f3 (origin/pr/673) minor narrative cleanup
regarding config compatibility, 2017-01-30, #673), but I'm not clear
on the motivation. The wording reads to me like "you don't have to
support valid values for platform-specific fields if you don't want
to", but we already cover unsupported value handling with the "MUST
generate an error when invalid or unsupported values are encountered"
language separated out in c763e641 (config: Move valid-value rules to
their own section, 2017-02-07, #681). This commit removes the
ambiguous line.
Signed-off-by: W. Trevor King <wking@tremily.us>
This condition landed in 27a05de3 (Add text about extensions,
2016-06-26, #510) with subsequent wording tweaks in 3f0440b4
(config.md: add empty limit for key of annotations, Dec 28 10:35:19
2016, #645) and 2c8feeb3 (config: Bring "unique... within this map"
back together, 2017-01-12, #654). However, since eeaccfab (glossary:
Make objects explicitly unordered and forbid duplicate names,
2016-09-27, #584) we forbid duplicate keys on *all* objects (not just
annotations), so this PR removes the redundant annotation-specific
condition.
Signed-off-by: W. Trevor King <wking@tremily.us>
These are long enough without the prefix, and
linux.resources.blockIO.blkioWeight, etc. are just as specific as
linux.resources.blockIO.weight.
Generated with:
$ sed -i s/blkioWeight/weight/g $(git grep -l blkioWeight)
$ sed -i s/blkioLeaf/leaf/g $(git grep -l blkioLeaf)
$ sed -i s/blkioThrottle/throttle/g $(git grep -l blkioThrottle)
Signed-off-by: W. Trevor King <wking@tremily.us>
SHOULD means that [1]:
... there may exist valid reasons in particular circumstances to
ignore a particular item, but the full implications must be
understood and carefully weighed before choosing a different course.
So consideration is already baked into the definition, and we can just
say "SHOULD be" and warn folks whenever they use a value other than
'rootfs'.
Also move this under the non-Windows conditions, because the advice
they doesn't apply to Windows where the value MUST be a volume GUID
path (since 2283e63, Windows: Remove Sandbox, additional tweaks,
2017-05-23, #849).
[1]: https://tools.ietf.org/html/rfc2119#section-3
Signed-off-by: W. Trevor King <wking@tremily.us>
Borrowing language from root.path for absolute/relative.
I think we also need to talk about 'mounts' being in the container
mount namespace (after creating it with the runtime mount namespace as
a seed) and before the pivot into root.path. But Michael and/or
Mrunal are going to file follow-up work to address that.
Signed-off-by: W. Trevor King <wking@tremily.us>
Clarifying the language from 28e8f68 (Hooks to linux,solaris and doc
clarification, 2017-05-24, #855), which did not say which platforms
support hooks and which don't. Without something like this commit,
there's no clear way for config authors to know if their runtime will
support hooks or not, and there was previous agreement that that sort
of ambiguity was not helpful [1]. This also gives normative Markdown
grounding for the Go platform tag added in 28e8f68.
[1]: https://github.com/opencontainers/runtime-spec/pull/472#r78088802
Signed-off-by: W. Trevor King <wking@tremily.us>
Not all hooks are run after creation. In fact, there are currently no
postcreate hooks (prestart hooks are called "after the start operation
is called but before the user-specified program command is executed".
Fixing 28e8f68 (Hooks to linux,solaris and doc clarification,
2017-05-24, #855), which pulled the broken line in from a Go comment
[1].
[1]: https://github.com/opencontainers/runtime-spec/pull/855#discussion_r118341546
Signed-off-by: W. Trevor King <wking@tremily.us>
Tianon Gravi