narrative cleanup in support of Base Config Compatibility #303 #673

jlbutler · 2017-01-30T21:42:30Z

Some minor narrative nits cleaned up in support of resolving issue #303. Most changes attempt to make it clear that multiple platforms are supported but keep the Linux examples and references in place. In the Process section, Linux-only options were left under the original header, anything which is supported by at least one other platform was pulled out.

jlbutler · 2017-01-30T22:10:07Z

@RobDolinMS please review in the context of #303. It seems a lot of other changes have come in to establish config compatibility, this just cleans up a few nits.

wking · 2017-01-30T22:02:08Z

config.md

@@ -1,7 +1,7 @@
 # Container Configuration file

 The container's top-level directory MUST contain a configuration file called `config.json`.
-The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go).
+The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go). [**`Platform-specific`**](#platform) configuration schema are defined in platform-specific documents.


There is already some documentation for this idea here. If you think it needs a mention in the top of this file, I'd consider just adding a link to the local #platform-specific-configuration (which actually links to the platform-specific documentation).

That's what I intended to do, typo. Will fix, thanks.

I also broke the 'one sentence per line' rule here, will fix.

wking · 2017-01-30T22:04:52Z

config.md

@@ -119,7 +118,6 @@ See links for details about [mountvol](http://ss64.com/nt/mountvol.html) and [Se
 **`process`** (object, REQUIRED) configures the container process.

 * **`terminal`** (bool, OPTIONAL) specifies whether a terminal is attached to that process, defaults to false.
-  On Linux, a pseudoterminal pair is allocated for the container process and the pseudoterminal slave is duplicated on the container process's [standard streams][stdin.3].


This language is new in #518; we probably don't want to remove it in this PR without addressing why directly. There's also the recent #663 which might end up removing process.terminal completely.

Ok thanks for pointing that out. It seemed like an implementation note more than anything, so I just dropped it. I'll put it back for now; I'm aware of #663.

wking · 2017-01-30T22:05:57Z

config.md

@@ -52,7 +51,7 @@ For Solaris, the mounts corresponds to fs resource in zonecfg(8).
  For the Solaris operating system, this corresponds to "dir" of the fs resource in zonecfg(8).
 * **`type`** (string, REQUIRED) The filesystem type of the filesystem to be mounted.
  Linux: *filesystemtype* argument supported by the kernel are listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
-  Windows: ntfs.
+  Windows: corresponds to the type of file system on the volume, e.g. 'ntfs'.


I would be much happier if we could link to some Windows docs listing allowed types here. “e.g. ntfs” doesn't help with compliance testing (which types should get checked before a runtime is deemed compliant?).

I thought using an example rather than implying only 'ntfs' would be better. I pinged irc for supported file systems but no reply yet. It's possible that only 'ntfs' is supported, but I thought we might see 'refs' eventually.

@RobDolinMS could you advise what should go here?

wking · 2017-01-30T22:06:49Z

config.md

@@ -25,8 +25,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
 **`root`** (object, REQUIRED) configures the container's root filesystem.

 * **`path`** (string, REQUIRED) Specifies the path to the root filesystem for the container.
-  The path can be an absolute path (starting with /) or a relative path (not starting with /), which is relative to the bundle.
-  For example (Linux), with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`.
+  The path can is either an absolute path or a relative path to the bundle. On Linux for example, with a bundle at `/to/bundle` and a root filesystem at `/to/bundle/rootfs`, the `path` value can be either `/to/bundle/rootfs` or `rootfs`.


You're dropping the one sentence per line.

Will fix, thanks.

wking · 2017-01-30T22:08:36Z

config.md

-
-* **`capabilities`** (array of strings, OPTIONAL) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
-  Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html).
+* **`capabilities`** (array of strings, OPTIONAL) is an array that specifies the set of capabilities of the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html).


I think you need to say something like “OPTIONAL on Linux and Solaris, undefined on Windows” or something to get that idea across. Also, if other platforms besides Linux support process.capabilities we need to link to their documentation for allowed values, otherwise compliance testing is difficult.

On the wording, is there a reason to label this as explicitly undefined? If it's OPTIONAL, implementations may leave it out of their scope.

As far as documentation, on reading this spec I really take the man page references to be just example references for clarity. We have various places where documentation is not explicitly referred to. If that should be part of this (or another PR), I think it would extend to more than this field. Thoughts?

If it's OPTIONAL, implementations may leave it out of their scope.

Right, but when a Linux config sets capabilities, the runtime has to apply them in a particular way. And when a Windows config sets capabilities, the runtime doesn't have to do anything.

As far as documentation, on reading this spec I really take the man page references to be just example references for clarity. We have various places where documentation is not explicitly referred to. If that should be part of this (or another PR), I think it would extend to more than this field.

I agree that this is a bigger issue than we want to handle in this PR. I just think we need to have clearly-specified values (otherwise how do the compliance tests or folks writing a config know what values their generic OCI-compliant runtime must support?). And while I don't think we need to strengthen all of that in this PR, I'd rather not weaken anything here ;).

For this PR, how would you feel about a generic "valid values for other platforms are as documented for that specific platform" or similar type of statement? Without some abstraction, we should probably refer to specific documentation for all platforms.

The abstraction proofs the spec against platform-specific documentation changes (content or location), which seems like an additional benefit.

wking · 2017-01-30T22:09:41Z

config.md

-    * **`soft`** (uint64, REQUIRED) - the value that the kernel enforces for the corresponding resource.
-    * **`hard`** (uint64, REQUIRED) - the ceiling for the soft limit that could be set by an unprivileged process.
-      Only privileged process (under Linux: one with the CAP_SYS_RESOURCE capability) can raise a hard limit.
+    * **`type`** (string, REQUIRED) - the platform resource being limited, for example as defined in [the man page](http://man7.org/linux/man-pages/man2/setrlimit.2.html).


This is not “for example” on Linux. The values defined in setrlimit(2) MUST be supported by compliant runtimes. For other platforms, we need new links to their supported values, not a weakening of the Linux values.

Again, I took this to be an example. I don't see how this infers that the field is not required nor how it weakens the spec. It's just that the specific man page reference is specific only to Linux, it serves as an example as to what can be valid for a particular platform.

This loops back to previous comment, if this spec should have references to all documentation for all configuration options on all supported platforms, it seems more work than these specific fields.

jlbutler · 2017-02-03T14:04:50Z

@opencontainers/runtime-spec-maintainers @RobDolinMS @jhowardmsft PTAL, thank you.

Based on this week's discussion on the call and in IRC, I've made changes to clarify what constitutes a valid value for a platform-specific property. Note the reference at the top of the file to the platform-specific scope below. I am hoping that this abstraction is enough to allow for implementors to feel free to support a platform as they see fit, while maintaining the spec's strength.

There are various nits which improve consistency and readability, I'm hoping it's simpler to review taken as a whole, rather than breaking out nits into separate PRs.

wking · 2017-02-03T15:03:05Z

config.md

-
-* **`capabilities`** (array of strings, OPTIONAL) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
-  Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html).
+* **`capabilities`** (array of strings, OPTIONAL) is an array that specifies the set of capabilities of the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [CAPABILITIES(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) man page.


I think this is still too wishy. MUST runtimes support all those valid values? E.g. is a runtime that errors on CAP_AUDIT_READ still compliant?. What are valid values on Solaris? On Windows (now that you've removed the earlier "For Linux-based systems the process structure supports the following process specific fields:" guard)?

I don't see that it's any different from before, only that Linux isn't the only thing referenced, and the man page isn't an implied extension of the spec. I have attempted to clarify with statements in the 'Platform-specific configuration' section. Applying those rules for all fields, not just 'capabilities', the answers to your questions are yes, valid values for Solaris are documented with the Solaris doc set, same for Windows. A runtime may support any combination of valid values for that platform, and there are rules for what it must do if it chooses to not do so.

A runtime may support any combination of valid values for that platform, and there are rules for what it must do if it chooses to not do so.

But then you could have a “compliant” no-op runtime, which always errors out with “sorry, I don't support that”. I think it makes sense to set a minimum bar for what you have to implement before you are compliant (e.g. “Linux runtimes MUST implement at least these capabilities: …”. I'm ok with that minimum bar being bounded by the local platform (e.g. a compliant runtime can error on CAP_X if and only if the kernel doesn't support CAP_X), but I don't have a good way to word that requirement generically.

I think we might be getting a bit contrived with a runtime that implements nothing... for example, no file system types for mounts are supported by choice. That said, this isn't meant to be a design document. I would say that as long as a clear error message is returned for any valid value for a field, yes it's spec-compliant.

I would say that as long as a clear error message is returned for any valid value for a field, yes it's spec-compliant.

That's an internally consistent approach, although it makes “OCI runtime-spec compliant” a pretty cheap badge, and means the only way to know that a runtime will be able to handle a given config will be “try to use the runtime to launch that config”. If the maintainers want to go in this direction, they may want to re-evaluate the effort currently being put into runtime-tools' compliance testing.

I think this is fine. Again, if further linting is required by an application to ensure a host has the expected capabilities, that is not going to be defined here.

What @vbatts said. You cannot base compliance on system values @wking and you cannot just make up some minimum. It can support as many values as the underlying host supports for fields like this. Just because you use a runtime on an older kernel that doesn't have a CAP does not mean its no longer a compliant runtime.

LGTM @jlbutler

Just because you use a runtime on an older kernel that doesn't have a CAP does not mean its no longer a compliant runtime.

That's not the situation I'm concerned about. I'm concerned about the situation where the host does support a particular CAP_* (or whatever) but the runtime does not. Instead of “it can support…”, I'd rather have “it MUST support values from {some values} for values supported by the host platform”. That bases compliance on system values (which you don't like), but means that you can actually test runtimes for meaningful compliance (e.g. the no-op runtime would be non-compliant).

@wking then the runtime errors out. end-users investigate. complain to the runtime developers or write a fix. That kind-of linting and validation needs to be secondary to this spec.

then the runtime errors out. end-users investigate. complain to the runtime developers or write a fix. That kind-of linting and validation needs to be secondary to this spec.

So what kind of CAP_* values should runtime compliance testing use? Currently it sets these, and fails runtimes which die in create (currently start, because runtime-tools hasn't been ported around #384, opencontainers/runtime-tools#285) or run without a matching set. Will we update that to say that any runtime is compliant as long as it:

Dies in create or

Succeeds in create and has a container environment matching the configuration

And then test all combinations (or some sampling) of CAP_* values regardless of platform support?

vbatts · 2017-02-06T21:01:53Z

Good stuff, so far. I'm still reviewing it tho.

wking · 2017-02-06T21:04:24Z

config.md

@@ -2,11 +2,15 @@

 The container's top-level directory MUST contain a configuration file called `config.json`.
 The canonical schema is defined in this document, but there is a JSON Schema in [`schema/config-schema.json`](schema/config-schema.json) and Go bindings in [`specs-go/config.go`](specs-go/config.go).
+Platform-specific configuration schema are defined in [**`platform-specific documents`**](#platform-specific-configuration) linked below.


We probably don't need backticks or bold around “platform-specific documents”. The usual link styling makes the link-ness obvious enough.

vbatts · 2017-02-06T21:04:16Z

config.md

-  Windows: ntfs.
-  Solaris: corresponds to "type" of the fs resource in zonecfg(8).
+  * Linux: valid *filesystemtype* supported by the kernel as listed in */proc/filesystems* (e.g., "minix", "ext2", "ext3", "jfs", "xfs", "reiserfs", "msdos", "proc", "nfs", "iso9660").
+  * Windows: the type of file system on the volume, e.g. "ntfs".


yea. This allows for better future-proofing.

vbatts · 2017-02-06T21:07:57Z

config.md

-
-* **`capabilities`** (array of strings, OPTIONAL) capabilities is an array that specifies Linux capabilities that can be provided to the process inside the container.
-  Valid values are the strings for capabilities defined in [the man page](http://man7.org/linux/man-pages/man7/capabilities.7.html).
+* **`capabilities`** (array of strings, OPTIONAL) is an array that specifies the set of capabilities of the process(es) inside the container. Valid values are platform-specific. For example, valid values for Linux are defined in the [CAPABILITIES(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) man page.


I think this is fine. Again, if further linting is required by an application to ensure a host has the expected capabilities, that is not going to be defined here.

vbatts · 2017-02-06T21:09:44Z

config.md

-[**`platform.os`**](#platform) is used to lookup further platform-specific configuration.
+[**`platform.os`**](#platform) is used to specify platform-specific configuration.
+Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration.
+Implementations MUST generate a clear error message for valid values it chooses to not support and MUST generate an error when invalid values are encountered.


does "a clear error message" mean that the implementation would not continue running and would exit non-zero? Just curious.

does "a clear error message" mean that the implementation would not continue running and would exit non-zero?

Exiting non-zero on create errors is covered by the in-flight #513. The currently landed error language has “as if the operation were never attempted” wording and “MUST generate an error and a new container MUST NOT be created” wording, which seems to cover everything but the exit-code (which only makes sense in the context of the #513 API).

jlbutler · 2017-02-06T21:52:53Z

Rebased, fixed up link nits and clarified the error and exit requirements in the platform-specific scope. Thanks @wking and @vbatts .

wking · 2017-02-06T22:07:22Z

config.md

-[**`platform.os`**](#platform) is used to lookup further platform-specific configuration.
+[**`platform.os`**](#platform) is used to specify platform-specific configuration.
+Runtime implementations MAY support any valid values for platform-specific fields as part of this configuration.
+Implementations MUST error out when invalid values are encountered and MUST generate a clear error message and exit non-zero when encountering valid values it chooses to not support.


I think we want to drop “exit non-zero”, because config.md should be independent of the API used to invoke the runtime. “generate a clear error message” is generic, and the relationship between error generation and exit-code should be setup in the API docs for APIs which use exit-codes.

And “clear” is hard to test. Maybe make it “MUST generate an error”? Then we'd trust on runtime authors to make it clear. If we don't trust runtime authors, we should say something enforceable, but that's hard to do when we don't even require the runtime to expose error to the user.

I believe I've covered these concerns in the latest commit. Thanks!

Signed-off-by: Jesse Butler <jesse.butler@oracle.com>

vbatts · 2017-02-07T22:10:06Z

LGTM

crosbymichael · 2017-02-07T22:19:16Z

LGTM

This wording just landed via 718f9f3 (origin/pr/673) minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673), but the rule is generic and not unique to platform-specific properties. Also adjust the wording somewhat to match the more established wording from the "Extensibility" section. Signed-off-by: W. Trevor King <wking@tremily.us>

With the "valid values it chooses to not support" language from 718f9f3 (origin/pr/673) minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673), the runtime is clearly free to support a subset of the platform's capabilities. But the runtime should not be free to change the semantics of valid values (e.g. CAP_CHOWN should always mean the same thing on Linux, regardless of which runtime you use). Signed-off-by: W. Trevor King <wking@tremily.us>

This wording just landed via 718f9f3 (origin/pr/673) minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673), but the rule is generic and not unique to platform-specific properties. Also adjust the wording somewhat to match the more established wording from the "Extensibility" section. Signed-off-by: W. Trevor King <wking@tremily.us>

And add platform annotations. By formally defining our syntax, we do a better job of making that syntax enforcable. We can also make platform-scoping very obvious, and no longer need to rely on "For Linux-based systems the process supports..." guards. The only intentional semantic change is that we now allow, platform-named properties that don't match platform.os. For example: { "platform": { "os": "linux", ... }, "windows": { ... } } and even: { "platform": { "os": "linux", ... }, "windows": "foo", } are both legal now. This rolls back the "MUST NOT be set otherwise" requirement which had landed in 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) to make those properties consistent with our general: Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property. and: The state MAY include additional properties. extensibility policies. The alternative would be cross-platform specification of those properties which then forbid the properties on non-matching platforms, but then the cross-platform definition would not match the platform-specific Go type. For example: Linux *Linux `json:"linux,omitempty" platform:"linux"` Blocking the non-matching-platform properties didn't seem to be worth the potential confusion of the Go platform tag not matching the Markdown platforms tag. Signed-off-by: W. Trevor King <wking@tremily.us>

And add platform annotations. By formally defining our syntax, we do a better job of making that syntax enforcable. We can also make platform-scoping very obvious, and no longer need to rely on "For Linux-based systems the process supports..." guards. The only intentional semantic change is that we now allow, platform-named properties that don't match platform.os. For example: { "platform": { "os": "linux", ... }, "windows": { ... } } and even: { "platform": { "os": "linux", ... }, "windows": "foo", } are both legal now. This rolls back the "MUST NOT be set otherwise" requirement which had landed in 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) to make those properties consistent with our general: Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property. and: The state MAY include additional properties. extensibility policies. The alternative would be cross-platform specification of those properties which then forbid the properties on non-matching platforms, but then the cross-platform definition would not match the platform-specific Go type. For example: Linux *Linux `json:"linux,omitempty" platform:"linux"` Blocking the non-matching-platform properties didn't seem to be worth the potential confusion of the Go platform tag not matching the Markdown platforms tag. The ABNF highlighting comes from [1,2]. [1]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting [2]: https://github.com/github/linguist/blob/v5.0.8/lib/linguist/languages.yml#L50-L56 Signed-off-by: W. Trevor King <wking@tremily.us>

The current "For example, valid values for Linux..." wording in config.md does not seem strong enough to support this condition, especially since the spec makes no claims about what valid capabilities are for non-Linux OSes. And process.capabilities has been nominally legal for non-Linux OSes since 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Signed-off-by: W. Trevor King <wking@tremily.us>

And add platform annotations. By formally defining our syntax, we do a better job of making that syntax enforcable. We can also make platform-scoping very obvious, and no longer need to rely on "For Linux-based systems the process supports..." guards. The only intentional semantic change is that we now allow, platform-named properties that don't match platform.os. For example: { "platform": { "os": "linux", ... }, "windows": { ... } } and even: { "platform": { "os": "linux", ... }, "windows": "foo", } are both legal now. This rolls back the "MUST NOT be set otherwise" requirement which had landed in 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) to make those properties consistent with our general: Implementations that are reading/processing this configuration file MUST NOT generate an error if they encounter an unknown property. and: The state MAY include additional properties. extensibility policies. The alternative would be cross-platform specification of those properties which then forbid the properties on non-matching platforms, but then the cross-platform definition would not match the platform-specific Go type. For example: Linux *Linux `json:"linux,omitempty" platform:"linux"` Blocking the non-matching-platform properties didn't seem to be worth the potential confusion of the Go platform tag not matching the Markdown platforms tag. The ABNF highlighting comes from [1,2]. [1]: https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting [2]: https://github.com/github/linguist/blob/v5.0.8/lib/linguist/languages.yml#L50-L56 Signed-off-by: W. Trevor King <wking@tremily.us>

…gain) Roll back the genericization from 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Lifting the restriction there seems to have been motivated by "Solaris supports capabilities", but that was before the split into a capabilities object which happened in eb114f0 (Add ambient and bounding capability support, 2017-02-02, opencontainers#675). It's not clear if Solaris supports ambient caps, or what Solaris API rlimits or noNewPrivileges were punting to [1]. And John Howard has recently confirmed that Windows does not support capabilities and is unlikely to do so in the future [2]. John's statement didn't directly address rlimits or noNewPrivileges, but we can always restore any of these properties to the Solaris/Windows platforms if/when we get docs about which API we're punting to on those platforms. Also add some backticks, remove the hyphens in "OPTIONAL) - the", standardize lines I touch to use "the process" [3], and use four-space indents here to keep Pandoc happy (see 7795661 (runtime.md: Fix sub-bullet indentation, 2016-06-08, opencontainers#495). [1]: opencontainers#673 (comment) [2]: opencontainers#810 (comment) [3]: opencontainers#809 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

Roll back the genericization from 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Lifting the restriction there seems to have been motivated by "Solaris supports capabilities", but that was before the split into a capabilities object which happened in eb114f0 (Add ambient and bounding capability support, 2017-02-02, opencontainers#675). It's not clear if Solaris supports ambient caps, or what Solaris API noNewPrivileges were punting to [1]. And John Howard has recently confirmed that Windows does not support capabilities and is unlikely to do so in the future [2]. He also confirmed that Windows does not support rlimits [3]. John's statement didn't directly address noNewPrivileges, but we can always restore any of these properties to the Solaris/Windows platforms if/when we get docs about which API we're punting to on those platforms. Also add some backticks, remove the hyphens in "OPTIONAL) - the", standardize lines I touch to use "the process" [4], and use four-space indents here to keep Pandoc happy (see 7795661 (runtime.md: Fix sub-bullet indentation, 2016-06-08, opencontainers#495). [1]: opencontainers#673 (comment) [2]: opencontainers#810 (comment) [3]: opencontainers#835 (comment) [4]: opencontainers#809 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

This property was initially Linux-specific. 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) removed the Linux restriction, but the rlimit concept is from POSIX and Windows doesn't support it [1]. This commit adds new subsections for the POSIX-specific and Linux-specific process entries (to match the approach we currently use for process.user), and punts to POSIX for the Solaris values and compliance testing approach. If/when we get a Solaris-specific doc for valid values, we can replace the POSIX punt there, but we probably want to continue punting to POSIX for getrlimit(3)-based compliance testing. [1]: opencontainers#835 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

This property was initially Linux-specific. 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) removed the Linux restriction, but the rlimit concept is from POSIX and Windows doesn't support it [1]. This commit adds new subsections for the POSIX-specific and Linux-specific process entries (to match the approach we currently use for process.user), and punts to POSIX for the Solaris values and compliance testing approach. If/when we get a Solaris-specific doc for valid values, we can replace the POSIX punt there, but we probably want to continue punting to POSIX for getrlimit(3)-based compliance testing. I've renamed the overly-specific LinuxRlimit to POSIXRlimit. We could use the generic Rlimit, but then we'd be stuck if/when Windows adds support for some rlimit-like thing that doesn't match up cleanly enough for us to use the POSIX structure. [1]: opencontainers#835 (comment) 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, opencontainers#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 c763e64 (config: Move valid-value rules to their own section, 2017-02-07, opencontainers#681). This commit removes the ambiguous line. Signed-off-by: W. Trevor King <wking@tremily.us>

Roll back the genericization from 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Lifting the restriction there seems to have been motivated by "Solaris supports capabilities", but that was before the split into a capabilities object which happened in eb114f0 (Add ambient and bounding capability support, 2017-02-02, opencontainers#675). It's not clear if Solaris supports ambient caps, or what Solaris API noNewPrivileges were punting to [1]. And John Howard has recently confirmed that Windows does not support capabilities and is unlikely to do so in the future [2]. He also confirmed that Windows does not support rlimits [3]. John's statement didn't directly address noNewPrivileges, but we can always restore any of these properties to the Solaris/Windows platforms if/when we get docs about which API we're punting to on those platforms. Also add some backticks, remove the hyphens in "OPTIONAL) - the", standardize lines I touch to use "the process" [4], and use four-space indents here to keep Pandoc happy (see 7795661 (runtime.md: Fix sub-bullet indentation, 2016-06-08, opencontainers#495). [1]: opencontainers#673 (comment) [2]: opencontainers#810 (comment) [3]: opencontainers#835 (comment) [4]: opencontainers#809 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

This property was initially Linux-specific. 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) removed the Linux restriction, but the rlimit concept is from POSIX and Windows doesn't support it [1]. This commit adds new subsections for the POSIX-specific and Linux-specific process entries (to match the approach we currently use for process.user), and punts to POSIX for the Solaris values and compliance testing approach. If/when we get a Solaris-specific doc for valid values, we can replace the POSIX punt there, but we probably want to continue punting to POSIX for getrlimit(3)-based compliance testing. I've renamed the overly-specific LinuxRlimit to POSIXRlimit. We could use the generic Rlimit, but then we'd be stuck if/when Windows adds support for some rlimit-like thing that doesn't match up cleanly enough for us to use the POSIX structure. [1]: opencontainers#835 (comment) 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, opencontainers#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 c763e64 (config: Move valid-value rules to their own section, 2017-02-07, opencontainers#681). This commit removes the ambiguous line. Signed-off-by: W. Trevor King <wking@tremily.us>

The filesystem at root.path is not the bundle; the bundle contains both root.path and the config.json as siblings (according to bundle.md). Remove the possibly confusing use of "bundle" for something else, rolling back part of 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Signed-off-by: W. Trevor King <wking@tremily.us>

Roll back the genericization from 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673). Lifting the restriction there seems to have been motivated by "Solaris supports capabilities", but that was before the split into a capabilities object which happened in eb114f0 (Add ambient and bounding capability support, 2017-02-02, opencontainers#675). It's not clear if Solaris supports ambient caps, or what Solaris API noNewPrivileges were punting to [1]. And John Howard has recently confirmed that Windows does not support capabilities and is unlikely to do so in the future [2]. He also confirmed that Windows does not support rlimits [3]. John's statement didn't directly address noNewPrivileges, but we can always restore any of these properties to the Solaris/Windows platforms if/when we get docs about which API we're punting to on those platforms. Also add some backticks, remove the hyphens in "OPTIONAL) - the", standardize lines I touch to use "the process" [4], and use four-space indents here to keep Pandoc happy (see 7795661 (runtime.md: Fix sub-bullet indentation, 2016-06-08, opencontainers#495). [1]: opencontainers#673 (comment) [2]: opencontainers#810 (comment) [3]: opencontainers#835 (comment) [4]: opencontainers#809 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

This property was initially Linux-specific. 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) removed the Linux restriction, but the rlimit concept is from POSIX and Windows doesn't support it [1]. This commit adds new subsections for the POSIX-specific and Linux-specific process entries (to match the approach we currently use for process.user), and punts to POSIX for the Solaris values and compliance testing approach. If/when we get a Solaris-specific doc for valid values, we can replace the POSIX punt there, but we probably want to continue punting to POSIX for getrlimit(3)-based compliance testing. I've renamed the overly-specific LinuxRlimit to POSIXRlimit. We could use the generic Rlimit, but then we'd be stuck if/when Windows adds support for some rlimit-like thing that doesn't match up cleanly enough for us to use the POSIX structure. [1]: opencontainers#835 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

In 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) we got: Implementations MUST error out when invalid values are encountered and MUST generate an error message and error out when encountering valid values it chooses to not support In c763e64 (config: Move valid-value rules to their own section, 2017-02-07, opencontainers#681), I'd moved that out into the current "Valid values" section with the line I'm removing in this commit. However, giving runtimes a blanket clause to ignore valid values makes it harder to use runtimes, because you can't be sure an OCI-compliant runtime supports the spec-defined value you need [1]. There have been concerns about requiring runtimes to support values which are not supported by the host system [2]. But since 766abd6 (runtime.md: Require 'create' to fail if config.json asks for the impossible, 2016-09-08, opencontainers#559) we've had runtime.md wording that gives the runtime the ability to compliantly die in those cases. That text had a wording tweak in 72e8062 (runtime: Explicitly make process.* timing implementation-defined, 2017-02-27, opencontainers#700), and is now: If the runtime cannot apply a property as specified in the configuration, it MUST generate an error and a new container MUST NOT be created. With this line removed, consumers will be able to rely on valid-value support in compliant runtimes, although many properties could use clearer runtimes-MUST-support wording for those values. However, we can sort those out on a per-property basis. And runtimes are still allowed to support extention values not defined in the spec (e.g. new capability types, or mount options, or whatever). Like all extentions, it is up to the runtime and runtime-caller to negotiate support in those cases. [1]: opencontainers#813 (comment) [2]: opencontainers#673 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

In 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) we got: Implementations MUST error out when invalid values are encountered and MUST generate an error message and error out when encountering valid values it chooses to not support In c763e64 (config: Move valid-value rules to their own section, 2017-02-07, opencontainers#681), I'd moved that out into the current "Valid values" section with the line I'm removing in this commit. However, giving runtimes a blanket clause to ignore valid values makes it harder to use runtimes, because you can't be sure an OCI-compliant runtime supports the spec-defined value you need [1]. There have been concerns about requiring runtimes to support values which are not supported by the host system [2]. But since 766abd6 (runtime.md: Require 'create' to fail if config.json asks for the impossible, 2016-09-08, opencontainers#559) we've had runtime.md wording that gives the runtime the ability to compliantly die in those cases. That text had a wording tweak in 72e8062 (runtime: Explicitly make process.* timing implementation-defined, 2017-02-27, opencontainers#700), and is now: If the runtime cannot apply a property as specified in the configuration, it MUST generate an error and a new container MUST NOT be created. With this commit, consumers will be able to rely on valid-value support in compliant runtimes. Many properties could use clearer runtimes-MUST-support wording for those values, but we can sort those out on a per-property basis in follow-up work. And runtimes are still allowed to support extention values not defined in the spec (e.g. new capability types, or mount options, or whatever). Like all extentions, it is up to the runtime and runtime-caller to negotiate support in those cases. [1]: opencontainers#813 (comment) [2]: opencontainers#673 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

In 718f9f3 (minor narrative cleanup regarding config compatibility, 2017-01-30, opencontainers#673) we got: Implementations MUST error out when invalid values are encountered and MUST generate an error message and error out when encountering valid values it chooses to not support In c763e64 (config: Move valid-value rules to their own section, 2017-02-07, opencontainers#681), I'd moved that out into the current "Valid values" section with the line I'm removing in this commit. However, giving runtimes a blanket clause to ignore valid values makes it harder to use runtimes, because you can't be sure an OCI-compliant runtime supports the spec-defined value you need [1]. There have been concerns about requiring runtimes to support values which are not supported by the host system [2]. But since 766abd6 (runtime.md: Require 'create' to fail if config.json asks for the impossible, 2016-09-08, opencontainers#559) we've had runtime.md wording that gives the runtime the ability to compliantly die in those cases. That text had a wording tweak in 72e8062 (runtime: Explicitly make process.* timing implementation-defined, 2017-02-27, opencontainers#700), and is now: If the runtime cannot apply a property as specified in the configuration, it MUST generate an error and a new container MUST NOT be created. As it stands both before and after this commit, a runtime can *still* die in 'create' because it cannot apply values supported by the host. This commit is just a step towards requiring runtimes to support as many values as the host supports; it doesn't get us all the way there. Many properties could use clearer runtimes-MUST-support wording for those values, but we can sort those out on a per-property basis in follow-up work. And runtimes are still allowed to support extention values not defined in the spec (e.g. new capability types, or mount options, or whatever). Like all extentions, it is up to the runtime and runtime-caller to negotiate support in those cases. [1]: opencontainers#813 (comment) [2]: opencontainers#673 (comment) Signed-off-by: W. Trevor King <wking@tremily.us>

wking reviewed Jan 30, 2017

View reviewed changes

wking mentioned this pull request Feb 2, 2017

schema/config-linux: add min/max limit for resource memory and cpu #533

Closed

wking reviewed Feb 3, 2017

View reviewed changes

wking reviewed Feb 6, 2017

View reviewed changes

vbatts reviewed Feb 6, 2017

View reviewed changes

wking reviewed Feb 6, 2017

View reviewed changes

minor narrative cleanup regarding config compatibility

718f9f3

Signed-off-by: Jesse Butler <jesse.butler@oracle.com>

crosbymichael merged commit 2e2d568 into opencontainers:master Feb 7, 2017

jlbutler deleted the config-compat-303 branch February 7, 2017 22:20

wking mentioned this pull request Feb 7, 2017

config: Move valid-value rules to their own section #681

Merged

wking mentioned this pull request Feb 7, 2017

config: Clarify capabilities(7) as the canonical source of Linux caps #682

Closed

jlbutler mentioned this pull request Feb 9, 2017

[Tracker] Base Config Compatibility #303

Closed

wking mentioned this pull request Feb 17, 2017

Add ambient and bounding capability support #675

Merged

zhouhao3 mentioned this pull request Mar 6, 2017

validate.go add checkos opencontainers/runtime-tools#332

Merged

vbatts mentioned this pull request Mar 6, 2017

Bump version #710

Merged

wking mentioned this pull request Mar 21, 2017

validate: increase OS validation for special cases opencontainers/runtime-tools#350

Merged

wking mentioned this pull request Mar 29, 2017

spec: Define the property-specification syntax #747

Closed

wking mentioned this pull request Apr 5, 2017

Linux capabilities not listed #755

Closed

wking mentioned this pull request Apr 11, 2017

schema/defs-linux: Drop 'Capability' type #766

Merged

wking mentioned this pull request May 18, 2017

config: Make capabilities, noNewPrivileges, and rlimits Linux-only (again) #835

Closed

wking mentioned this pull request May 24, 2017

config: Remove "MAY support any valid values" sentence #851

Merged

wking mentioned this pull request Oct 3, 2017

question about valid values runtime choose to support #813

Open

wking mentioned this pull request Oct 4, 2017

config: Drop "subset of the valid values" line #927

Closed

wking mentioned this pull request Jun 2, 2018

seccomp: specify what must happen if a syscall can't be resolved #972

Open

narrative cleanup in support of Base Config Compatibility #303 #673

narrative cleanup in support of Base Config Compatibility #303 #673

Conversation

jlbutler commented Jan 30, 2017

jlbutler commented Jan 30, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlbutler commented Feb 3, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlbutler Feb 3, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wking Feb 7, 2017 • edited Loading

Choose a reason for hiding this comment

vbatts commented Feb 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jlbutler commented Feb 6, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vbatts commented Feb 7, 2017 • edited by caniszczyk Loading

crosbymichael commented Feb 7, 2017 • edited by caniszczyk Loading

jlbutler Feb 3, 2017 •

edited

Loading

wking Feb 7, 2017 •

edited

Loading

vbatts commented Feb 7, 2017 •

edited by caniszczyk

Loading

crosbymichael commented Feb 7, 2017 •

edited by caniszczyk

Loading