Anyone setting 'rootfs.path' should be aware of this advice,
regardless of whether they're the ones composing the bundle or not.
Use the RFC 2119 "SHOULD" (vs. the old lowercase "should") for this
recommendation. The SHOULD semantics make sense and using SHOULD
avoids confusing readers ("did they mean to SHOULD this?").
Also drop the "While the name of this directory may be arbitrary"
caveat, because SHOULD already implies "but you can pick another
directory name if you want".
Note that the "MUST be present in a single directory" line which is
still in bundle.md forbids you from picking "foo/bar", "../foo", or
other paths that do not point at a direct child of the bundle
directory. I don't like that direct-child restriction [1], but I'm
not touching it in this commit.
[1]: https://github.com/opencontainers/runtime-spec/pull/469
Signed-off-by: W. Trevor King <wking@tremily.us>
This should have happened in 4b49c64a (config: Shift oomScoreAdj from
linux.resources to process, 2017-05-09, #789) as part of moving the
property from a Linux-specific type to a cross-platform type.
Signed-off-by: W. Trevor King <wking@tremily.us>
replace `filesystemtype` with `type of filesystem`
`list of strings` should be replaced by `array of strings`
Signed-off-by: Ma Shimiao <mashimiao.fnst@cn.fujitsu.com>
We have an explicit policy for example header levels in style.md, so
follow that in config-linux.md. Also adjust the non-example headers
to be one level deeper than their parent.
Signed-off-by: W. Trevor King <wking@tremily.us>
It's optional since c41ea83d (config: Make process optional,
2017-02-27, #701) which landed yesterday.
Mrunal wanted to continue testing a config which has enough for a
'start' invocation [1], so I've kept the old JSON as
minimal-for-start.json (washing it through 'make -C schema fmt' to
adjust the args indenting).
[1]: https://github.com/opencontainers/runtime-spec/pull/805#issuecomment-300811461
Signed-off-by: W. Trevor King <wking@tremily.us>
Catch the Markdown spec up with the JSON Schema change in 09274372
(schema: Drop pointers and nulls, 2017-01-18, #662). The Markdown is
canonical, so we could restore the explicit-null handling to the JSON
Schema instead, but the maintainers feel (and I agree) that there's no
point in explicitly allowing a null value when callers can simply
leave the property unset [1].
[1]: https://github.com/opencontainers/runtime-spec/pull/555#issuecomment-272020515
Signed-off-by: W. Trevor King <wking@tremily.us>
The only .PHONY entry we *need* is for schema/validate, since that's a
real file but we haven't told Make about its real dependencies (which
involve complicated Go lookups). I'm personally in favor of using
.PHONY for all targets that aren't on-disk files, because it hints to
readers that the rule is not generating a file at the target. But
there has been resistance to adding .PHONY entries to all such cases
(e.g. [1,2]), so this commit brings us around to a
internally-consistent "only use .PHONY when you always need it"
position.
That means that, for example, users who create files named 'clean'
will turn 'clean' the target into a no-op, but runtime-spec
maintainers are ok with that.
[1]: https://github.com/opencontainers/runtime-spec/pull/791#issuecomment-300369882
[2]: https://github.com/opencontainers/runtime-spec/pull/791#issuecomment-300612827
Signed-off-by: W. Trevor King <wking@tremily.us>
Step 3 of the lifecycle from before this commit had two sentences
which both landed in be594153 (Split create and start, 2016-04-01,
#384). I pushed back a bit on the entry then [1,2], but we seem to be
pretty comfortable with the current "keep all lifecyle entries in a
one-layer enumerated list" approach, so I'm leaving that alone in this
commit. Step 3 isn't really a lifecycle step though, it's more about
clarifying that you can jump around in the lifecycle instead of
hitting all the steps in consecutive order. I'd floated a new
paragraph addressing that jumping, but was unable to form a consensus
around wording, and the jumping is already somewhat covered by the
current list entries (e.g. "The container process exits."). This
commit just drops the old step 3, and Michael will follow up with
wording about jumping [3].
The other sentence from the old step 3 doesn't need replacing, because
the limits are already covered in more detail in the operation
sections themselves. For example, the 'delete' operation has:
Attempting to delete a container that does not exist MUST generate
an error. Attempting to delete a container whose process is still
running MUST generate an error.
I don't see the need to call generic attention to that idea, and
especially do not think that an entry in the lifecycle list is the
right place for such a generic call-out.
[1]: https://github.com/opencontainers/runtime-spec/pull/384#r60939710
[2]: https://github.com/opencontainers/runtime-spec/pull/384#issuecomment-214418730
[3]: http://ircbot.wl.linuxfoundation.org/meetings/opencontainers/2017/opencontainers.2017-05-10-21.03.log.html#l-79
Signed-off-by: W. Trevor King <wking@tremily.us>
Based on IRC discussion today (times in PST) [1]:
11:36 < crosbymichael> just take a step back and think about it.
you have a process object in the spec. its a single object
defining what to run. How do you run a process? you exec its
args. From the spec pov its an atomic operation. in between
create and start its not running the users code and is left up to
the runtime. you either have a process defined by the spec and
its created as an operation in the container on start or your
dont.
With the previous wording, it was unclear how large a hole we were
poking with "the user-specified program MUST NOT be run at this time".
This commit removes that ambiguous wording and replaces it with an
explicit reference to 'process.args'. It makes it clear that
everything outside of 'process' MUST happen at create-time. And it
leaves all of 'process' except for 'process.args' up to the
implementation.
This means that the caller has no reliable way to set the
user/cwd/capabilities/… of the runtime's container process between
'create' and 'start'. You could avoid that limitation by requiring
all process properties *except* process.args be applied at
create-time, but my attempt to make process.args optional (which would
have allowed that interpretation without burdening callers who never
intended to call 'start') was rejected in favor of this all-or-nothing
approach to 'process' handling [2].
[1]: http://ircbot.wl.linuxfoundation.org/eavesdrop/%23opencontainers/%23opencontainers.2017-02-27.log.html#t2017-02-27T19:35:35
[2]: https://github.com/opencontainers/runtime-spec/pull/620#issuecomment-282820279
Signed-off-by: W. Trevor King <wking@tremily.us>
Daniel, Dao Quang Minh