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>
Any runtime which violated that constraint would necessarily violate
some more specific constraint on a 'resources' setting.
This also removes a non-spec-requirement "required" to avoid any
confusion with the spec-requirement REQUIRED [1].
[1]: https://github.com/opencontainers/runtime-spec/pull/729#issue-214550260
Signed-off-by: W. Trevor King <wking@tremily.us>
Since f9dc90b0 (make link usage consistent across the specification,
2017-02-09, #687), the official style is to only use reference-style
links for external links. I expect the remaining three entries just
slipped through. This commit adjusts everything found with:
$ git grep ']: [a-z]' | grep -v http
It also fixes the underscore -> hyphen in the
glossary.md#container-namespace target and updates the capabilities
location to catch up with 5a8a779f (Move process specific settings to
process, 2016-03-02, #329).
Signed-off-by: W. Trevor King <wking@tremily.us>
The only discussion related to this is in [1,2], where the
relationship between oomScoreAdj and disableOOMKiller is raised. But
since 429f936 (Adding cgroups path to the Spec, 2015-09-02, #137)
resources has been tied to cgroups, and oomScoreAdj is not about
cgroups. For example, we currently have (in config-linux.md):
You can configure a container's cgroups via the resources field of
the Linux configuration.
I suggested we move the property from linux.resources.oomScoreAdj to
linux.oomScoreAdj so config authors and runtimes don't have to worry
about what cgroupsPath means if the only entry in resources is
oomScoreAdj. Michael responded with [4]:
If anything it should probably go on the process
So that's what this commit does.
I've gone with the four-space indents here to keep Pandoc happy (see
7795661 (runtime.md: Fix sub-bullet indentation, 2016-06-08, #495),
but have left the existing entries in this list unchanged to reduce
churn.
[1]: https://github.com/opencontainers/runtime-spec/pull/236
[2]: https://github.com/opencontainers/runtime-spec/pull/292
[3]: https://github.com/opencontainers/runtime-spec/pull/137
[4]: https://github.com/opencontainers/runtime-spec/issues/782#issuecomment-299990075
Signed-off-by: W. Trevor King <wking@tremily.us>
These states are already defined in the "State" section. There's no
need to redefine them in the operation sections.
Operation-level redefinitions are dicy anyway, because they imply
something testable about the immediately-after-this-operation time,
and it's not possible to run race-free tests of that time (e.g. the
process could die for other reasons between the successful 'create'
call and the 'state' call you made to look for a 'created' status).
Signed-off-by: W. Trevor King <wking@tremily.us>
With the same link update that config-solaris.md got in ea65eb3d
(config-solaris.md: fix info, 2017-04-28, #786), since the old link
404s.
Signed-off-by: W. Trevor King <wking@tremily.us>
These were added in f9dc90b0 (make link usage consistent across the
specification, 2017-08-09, #687) to follow the new _N name-dedup
policy discussed in style.md. They were removed in ea65eb3d
(config-solaris.md: fix info, 2017-04-28, #786), overlooking that
policy. This commit brings them back.
Signed-off-by: W. Trevor King <wking@tremily.us>
Instead of leading off with links to a bunch of other places, notes on
the Go tags, etc., make things more inviting by leading off with a
big-picture summary of what the configuration is about.
Signed-off-by: W. Trevor King <wking@tremily.us>
Avoid injecting:
"consoleSize":{"height":0,"width":0}
when serializing with Go's stock JSON serializer. Using a pointer for
this optional struct property works around [1].
[1]: https://github.com/golang/go/issues/11939
Signed-off-by: W. Trevor King <wking@tremily.us>
And fill in some known-good and known-bad examples. We can make this
as detailed as we want, but this commit just adds enough to know that:
* The full-file spec examples are valid.
* The JSON Schema can distinguish valid examples from invalid JSON.
This will help catch JSON Schema typos like those being addressed by
[1].
[1]: https://github.com/opencontainers/runtime-spec/pull/784
Signed-off-by: W. Trevor King <wking@tremily.us>
So we can compliance-test runtimes for these settings.
Also remove the tutorial, since the kernel docs should provide
sufficient documentation on that front. The kernel can be patched if
they do not, and we do not include tutorials for other config-linux
settings in this spec.
The updated example was recommended by Xiaochen to compensate for the
removed inline tutorial [1].
[1]: https://github.com/opencontainers/runtime-spec/pull/787#discussion_r114254422
Signed-off-by: W. Trevor King <wking@tremily.us>
The previous wording hinted at, but did not require, this setting to
be implemented via oom_score_adj. With the new wording, when proc is
mounted at /proc, the container process can check this value by
looking at /proc/self/oom_score_adj.
Signed-off-by: W. Trevor King <wking@tremily.us>
Daniel, Dao Quang Minh
W. Trevor King
Tianon Gravi
Ma Shimiao
Michael Crosby
Mrunal Patel
Qiang Huang