README: add some user stories #280

philips · 2015-12-23T06:10:46Z

I am trying to document who might want to read this spec. I constantly get asked who should be looking at OCI and why. Lets see how successful I am.

wking · 2015-12-23T16:44:14Z

README.md

@@ -22,9 +22,17 @@ In the specifications in the above table of contents, the keywords "MUST", "MUST

 To provide context for users the following section gives example use cases for each part of the spec.

-## Filesystem Bundle & Configuration
+**Container Configuration**


I'd rather stick to headers (they go all the way down to h6 ;), so we get link anchors.

wking · 2015-12-23T17:23:47Z

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

I am trying to document who might want to read this spec.

+1 to this :). The content sections look like they're currently
focusing on details about in the spec, and not on the relationships
between user-types that the spec enables. How about something like:

User stories

Bundle author

Bundle authors can write and publish bundles to
distribute software along with any required libraries or auxiliary
tools. They can provide OCI configuration
files in the bundle to configure default
resources limits so runtime callers have reasonable defaults
(although runtime callers are free to adjust these limits).

Runtime author

Runtime authors can write runtime implementations to allow
OCI-compliant bundles to run on a particular platform (or with a
particular containerization-technology).

Hook author

Hook authors can write commands to handle
functionality that is outside the scope of basic container
technology (for example, sophisticated network configuration).

Runtime callers

Runtime callers can use a consistent runtime
API to launch
containers from bundles provided by bundle authors. They can also
adjust the bundle author's provided OCI config to tailor the
container to their environment (for example, by injecting hooks or
adjusting resource limits).

Although until the command-line API lands somewhere more official, we
should probably leave the runtime-callers section out.

philips · 2015-12-23T19:04:23Z

@wking I like your approach by user better, I will fix if up.

mrunalp · 2015-12-23T20:02:48Z

+1 to user approach

I am going to add some additional use cases so lets move to h4 instead of an h2. Signed-off-by: Brandon Philips <brandon.philips@coreos.com>

philips · 2015-12-24T01:08:14Z

PTAL @wking @mrunalp

jonboulle · 2015-12-24T14:23:18Z

README.md


- A user can create a root filesystem and configuration, with low-level OS and host specific details, and launch it as a container under an Open Container runtime.
+Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files and some low-level details for launching an application as a container.
+The application can in-turn rely on certain OS configuration being available when it is launched inside of a container by a runtime.


in-turn -> in turn

It's pretty unclear what low level configuration the user (builder) must specify and what will be provided by something else (presumably the runtime). Maybe this is just conflating the two "users"? (builder and application).

On Thu, Dec 24, 2015 at 06:24:56AM -0800, Jonathan Boulle wrote:

-- A user can create a root filesystem and configuration, with low-level OS and host specific details, and launch it as a container under an Open Container runtime.
+Application bundle builders can create a bundle directory that includes all of the files and some low-level details for launching an application as a container.
+The application can in-turn rely on certain OS configuration being available when it is launched inside of a container by a runtime.

It's pretty unclear what low level configuration the user (builder)
must specify and what will be provided by something else (presumably
the runtime).

I'm pretty sure this is calling attention to the requirements added in
in #164. And again, I don't think we need to get down to this level
of detail here. Folks are packaging some software in a container
because they want it to be easy to run in a reliable, safe manner.
They pick the OCI format because it's a popular (hopefully ;) standard
with broad (hopefully ;) support. Making a low-level sales pitch for
the OCI format (vs. other formats?) seems to be off-target for a
doc-section where we're trying to paint pictures of who these
spec-user classes are.

OCI is low-level. It points and and in many cases requires things like cgroups paths. I think someone familiar with docker image format or appc would be surprised by these requirements.

On Fri, Dec 25, 2015 at 07:46:34AM -0800, Brandon Philips wrote:

+Application bundle builders can create a bundle
directory that includes all of the files and some low-level
details for launching an application as a container.
+The application can in-turn rely on certain OS configuration
being available when it is launched inside of a container by a
runtime.

OCI is low-level. It points and and in many cases requires things
like cgroups paths. I think someone familiar with docker image
format or appc would be surprised by these requirements.

Clearing up that surprise makes more sense to me than the “can in-turn
rely on” phrasing (which doesn't link to docs about what OS
configuration it's referring to). How about:

Application bundle builders can create a bundle
directory that includes all of the files required for launching an
application as a container. The bundle also contains OCI
configuration files where you can
declare both high-level settings (which executable to
launch) and low-level settings
(which namespaces and
cgroups to join).

Although I still prefer my initial focus on resource limits 1, as it
avoids mentioning the Linux-specific cgroups/namespaces.

I think we need to stop trying to try and be OS agnostic until we get details on a second target. We are just inventing language without a target abstraction.

vishh · 2015-12-28T20:16:03Z

README.md

+[Hook](runtime-config.md#hooks) authors can extend the functionality of an OCI-compliant runtime by hooking into a container's lifecycle with an external application.
+Example use cases include sophisticated network configuration, volume garbage collection, etc.
+
+#### Runtime Writer


nit: s/Writer/Developer

philips · 2016-01-06T10:13:14Z

Please take a look at this latest attempt.

wking · 2016-01-06T15:34:38Z

README.md

- A user can create a root filesystem and configuration, with low-level OS and host specific details, and launch it as a container under an Open Container runtime.
+Application bundle builders can create a [bundle](bundle.md) directory that includes all of the files required for launching an application as a container.
+The bundle contains OCI [configuration files](config.md) where the builder can specify host-independent details such as [which executable to launch](config.md#process-configuration) and host-specific settings such as [mount](runtime-config.md#mount-configuration) locations, [hook](runtime-config.md#hooks) paths, Linux [namespaces](runtime-config-linux.md#namespaces) and [cgroups](runtime-config-linux.md#control-groups).
+Because the configuration includes host-specific settings application bundle directories copied between two hosts may not work and will require configuration adjustments.


“settings application” → “settings, application”. And I'd replace “may not work and will require configuration adjustments” with “may require configuration adjustments” (to soften the “will”), because there's a chance that it does work as copied.

I will change it to may but in almost every non-trivial example it will require changes.

wking · 2016-01-06T15:41:02Z

On Wed, Jan 06, 2016 at 02:13:16AM -0800, Brandon Philips wrote:

Please take a look at this latest attempt.

Left some trivial copy-edit suggestions 1, but 1ca1981 → b5b252d
looks good to me.

Lets call out some users directly and give them titles. Then define what they is trying to do. Signed-off-by: Brandon Philips <brandon.philips@coreos.com>

philips · 2016-01-19T20:24:02Z

Can I get an lgtm and merge?

mrunalp · 2016-01-19T20:29:28Z

LGTM

vishh · 2016-01-19T20:56:55Z

LGTM

README: add some user stories

wking reviewed Dec 23, 2015
View reviewed changes

philips force-pushed the try-and-add-some-use-cases branch from 90f4d36 to acb2dd0 Compare December 24, 2015 01:04

README: make use cases less loud

bcb459c

I am going to add some additional use cases so lets move to h4 instead of an h2. Signed-off-by: Brandon Philips <brandon.philips@coreos.com>

philips force-pushed the try-and-add-some-use-cases branch 3 times, most recently from ad4a7e9 to 229d601 Compare December 24, 2015 01:08

jonboulle reviewed Dec 24, 2015
View reviewed changes

philips force-pushed the try-and-add-some-use-cases branch from 229d601 to 1ca1981 Compare December 25, 2015 15:50

vishh reviewed Dec 28, 2015
View reviewed changes

philips force-pushed the try-and-add-some-use-cases branch 2 times, most recently from 577cf5f to b5b252d Compare January 6, 2016 10:12

wking reviewed Jan 6, 2016
View reviewed changes

mrunalp added this to the v0.3.0 milestone Jan 13, 2016

README: add runtime, bundle, and hook author user

9289afe

Lets call out some users directly and give them titles. Then define what they is trying to do. Signed-off-by: Brandon Philips <brandon.philips@coreos.com>

philips force-pushed the try-and-add-some-use-cases branch from b5b252d to 9289afe Compare January 19, 2016 20:23

vishh added a commit that referenced this pull request Jan 19, 2016

Merge pull request #280 from philips/try-and-add-some-use-cases

72e7cf9

README: add some user stories

vishh merged commit 72e7cf9 into opencontainers:master Jan 19, 2016

wking mentioned this pull request Jan 20, 2016

config: Single, unified config file #284

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README: add some user stories #280

README: add some user stories #280

philips commented Dec 23, 2015

wking Dec 23, 2015

wking commented Dec 23, 2015

philips commented Dec 23, 2015

mrunalp commented Dec 23, 2015

philips commented Dec 24, 2015

jonboulle Dec 24, 2015

jonboulle Dec 24, 2015

wking Dec 24, 2015

philips Dec 25, 2015

wking Dec 28, 2015

philips Jan 6, 2016

vishh Dec 28, 2015

vbatts Jan 4, 2016

philips commented Jan 6, 2016

wking Jan 6, 2016

philips Jan 19, 2016

wking commented Jan 6, 2016

philips commented Jan 19, 2016

mrunalp commented Jan 19, 2016

vishh commented Jan 19, 2016

README: add some user stories #280

README: add some user stories #280

Conversation

philips commented Dec 23, 2015

Choose a reason for hiding this comment

wking commented Dec 23, 2015

User stories

Bundle author

Runtime author

Hook author

Runtime callers

philips commented Dec 23, 2015

mrunalp commented Dec 23, 2015

philips commented Dec 24, 2015

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

philips commented Jan 6, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wking commented Jan 6, 2016

philips commented Jan 19, 2016

mrunalp commented Jan 19, 2016

vishh commented Jan 19, 2016