glossary: Provide a quick overview of important terms

[wking]

And link them to the more detailed specification.

This borrows from appc, which calls the launched process tree "the
app". I don't see a point to abbreviating it, so I've gone with
"application".

Subsection titles for the entries will be obnoxiously spacious, but
the other alternatives seem worse:

• An HTML definition list (<dl>) would have nice default styling, but
  it's annoying to write raw HTML. And we would have needed
  something like:

    <dt name="bundle">Bundle</dt>
    <dd>
  
    A [directory structure](bundle.md) that is...
  
    </dd>
  

  to get Markdown-style links in the defintion itself.

• A Markdown list (* …) would have reasonable default styling, but
  there's no Markdown syntax for adding anchors to the entries. And a
  glossary is much less useful if you can't link to a specific entry.

Spun off from #88.

[philips]

launching an application? A bundle only specifies launches a single application process.

[wking]

On Tue, Aug 11, 2015 at 09:26:58PM -0700, Brandon Philips wrote:

+## Bundle
+
+A directory structure that is written ahead of time, distributed, and used to seed the runtime for creating containers and launching applications.

launching an application? A bundle only specifies launches a single
application process.

One application (which can result in a multi-process tree) per runtime
invocation yes. But you can use the same bundle to launch several
copies of the application.

And you can also have several config choices in a single bundle. My
proposed docs for this are in this subsection 1 of #76. That PR was
rejected for other reasons, but that particular subsection still
applies to the current spec and at least the runC implementation.

[philips]

The intention is that a single bundle launches a single application. The bundle defines a single identity (bundle directory, cgroup hierarchy, etc) and a single lifecycle (hooks, etc).

[wking]

On Wed, Aug 12, 2015 at 09:42:27AM -0700, Brandon Philips wrote:

+## Bundle
+
+A directory structure that is written ahead of time, distributed, and used to seed the runtime for creating containers and launching applications.

The intention is that a single bundle launches a single
application. The bundle defines a single identity (bundle directory,
cgroup hierarchy, etc) and a single lifecycle (hooks, etc).

Do we explicitly set that “single application” limit somewhere? I
understand we have a default config location (config.json) for the
bundle 1, but I don't see why you couldn't store additional config
files in the bundle, and have optional runtime support for launching
from one of those additional configs 2. Allowing the default config
filename to be overridden at runtime seems both useful and easy to
implement, so I don't see an upside to requiring a
single-application-per-bundle limit.

[wking]

On Wed, Aug 12, 2015 at 02:37:00PM -0700, W. Trevor King wrote:

Allowing the default config filename to be overridden at runtime
seems both useful and easy to implement…

For a concrete example, see 1, which supports both the IPFS gateway:

runc

and a shell for poking around:

runc config-sh.json

[wking]

On Sat, Aug 29, 2015 at 01:40:07AM -0700, Lai Jiangshan wrote:

When the namespaces have been created, it implies that at least one
process has been started. (it is the runc init process for the
runc implementation for example)

RunC currently conflates the container creation and application
execution, but that's not required. For example, bocker:

1. creates a network namespace, cgroups, and networking here 1,
2. enters that container and executes the application 2, and
3. deletes the container [3,4]

It doesn't split those into separate commands (since it's based on the
Docker UI), but you could certainly split them into separate
commands, and that seems like the most sane approach to me.

[laijs]

Thanks for pointing out.
But how to create other namespaces without starting any additional process?
Must be there some ways like network, but I can't find out any grace way currently.

---

I found a bad way (untested)

the creating process()
  unshare()
  mount --bind to save the namespace on some where.
  setns() back or exit.

the starting init process()
  setns() to the saved namespace.

---

So I think it is better to create namespaces when starting the container.

[wking]

On Sat, Aug 29, 2015 at 02:26:41AM -0700, Lai Jiangshan wrote:

But how to create other namespaces without starting any additional
process? Must be there some ways like network, but I can't find out
any grace way currently.

They may not all have a way ;). Any namespaces that turn out to
require a PID may require the runtime to store create-time
information, check that store when launching a new application, and
create any missing namespaces when launching that application. That
gives us consistent client semantics (e.g. you can still join an
existing user namespace by listing it's path in application.json 1).
And if/when the kernel gains the ability to create/destroy those
namespaces independently we can drop the associated runtime storage.

[laijs]

so

Create

Creates the container: file system, namespaces, cgroups, capabilities.

is some kinds of misleading. Only the network namespace can be created
graciously before starting.

[wking]

On Sat, Aug 29, 2015 at 10:25:27AM -0700, Lai Jiangshan wrote:

Create

Creates the container: file system, namespaces, cgroups, capabilities.

is some kinds of misleading. Only the network namespace can be
created graciously before starting.

That may be. But I think this is getting too far afield for this PR
(maybe shift it to 1?). I was only quoting that existing spec
(not suggesting we add that wording in this PR) to show that the
current spec seems to lean both ways (depending on which section
you're reading) about whether or not there will be multiple
applications in one container 2. And if we accept that the
singular/plural application question is currently up in the air, the
‘applications’ plural suggested by this PR isn't a major concession.

But that cuts both ways, so I guess I'll just change to singular here
and isolate the singular/plural lifecycle discussion in 1. Done in
the just pushed 5fc03cf→9db5fbe, which also rebases onto the current
master (not that there were any conflicts, but having a shorter
fork/merge delay makes for an easier-to-read history graph ;).

[wking]

While commenting on #87, I realized that I don't understand what happens when a non-PID-namespaced process forks/execs a child that escapes its process tree. Is it still part of the “application” (I'm not sure)? Is that process something that gets terminated when we stop a container (I'm not sure, but this should probably be the same answer as for “application”)? Is it checkpointed/restored when we move a container (you could tie checkpointing into just the freezer cgroup)?

[wking]

Rebased onto the current master to get #88 and reference both config.json and runtime.json. I also added a few links out to relevant sections of the spec.

In today's meeting, @vbatts was saying some of the wording here needed review, but after reading it over again I'm not sure what needs to change. I'm happy to make any changes required to get this landed.

[wking]

I added a new commit with the UTF-8 JSON requirement (since that was the maintainer-recommended approach in #146.

[crosbymichael]

I'm -1 on making this change now. This is adding new terms that don't exist, not being a glossary for existing things. There is no "Application". There are only containers and processes. Also the glossary has a little container/application infinite loop going on which is not helpful.

[wking]

On Mon, Oct 05, 2015 at 11:01:47AM -0700, Michael Crosby wrote:

There is no "Application".

Dropped with b795e6f → a57ba05, which also breaks the container ↔
application loop. Anything else that I need to change to get this
landed?

[wking]

On Mon, Oct 05, 2015 at 11:09:12AM -0700, W. Trevor King wrote:

Mon, Oct 05, 2015 at 11:01:47AM -0700, Michael Crosby:

There is no "Application".

Dropped with b795e6f → a57ba05…

I missed a few with that update. Dropped the rest with a57ba05 →
6bddc28.

[philips]

just say "for example" instead of the parenthetical and ellipses?

[wking]

On Tue, Dec 22, 2015 at 10:28:22PM -0800, Brandon Philips wrote:

+An environment for executing processes with configurable isolation and resource limitations (namespaces, resource limits, mounts, …).

just say "for example" instead of the parenthetical and ellipses?

In 6bddc28 → 0f9ec22 I've spun the parenthetical out into a new
sentence:

For example, namespaces, resource limits, and mounts are all part of
the container environment.

Does that address your concerns?

[philips]

lgtm

[hqhq]

LGTM. Seems all terms are existed in specs, and I think it's good enough for now, merging, thanks.