bundle: Add platform-matching config directories

To allow a single bundle to be cross-platform.  I've tried to add
enough context to motivate the additional complexity without adding so
much that the context distracts from the spec changes.

The tie-breaking version ranking (step (2) for picking the best config
file) also make it possible to write backwards-compatible bundles that
still take advantage of new features when possible.  For example,
placing v1.0, v1.6, and v2.0 configs in the same directory would let
you run the same container on all v1.* and v2.* runtimes while still
letting you take advantage of v1.6 and v2.0 features for compatible
runtimes.  After explaining the multi-platform advantages, the
multi-version example seemed obvious enough to not be worth cluttering
the bundle.md description, but commit-message space is cheap so I'm
talking about it explicitly here ;).

There was discussion about schemes for sharing content between config
files (JSON Schema's $ref [1] and explicit child declarations [2]).
However, neither approach makes it convenient to both make mass tweaks
across a family of related configs and make targetted tweaks to a
single leaf [3], so for now we'll follow the Dockerfile example and
have simple, stand-alone configs [4].  Folks who find this tedious or
redundant are free to automate it with external tooling, and if a
given external tool gains enough mass we can roll it into the spec
later.

[1]: #73 (comment)
[2]: #74
[3]: #73 (comment)
[4]: #74 (comment)

Author: wking

bundle.md

@@ -12,19 +12,72 @@ A standard container bundle is made of the following 3 parts:
 
 # Directory layout
 
-A Standard Container bundle is a directory containing all the content needed to load and run a container. This includes its configuration file (`config.json`) and content directories. The main property of this directory layout is that it can be moved as a unit to another machine and run the same container.
+A Standard Container bundle is a directory containing all the content needed to load and run a container. This includes its configuration file(s) and content directories. The main property of this directory layout is that it can be moved as a unit to another machine and run the same container.
 
-The syntax and semantics for `config.json` are described in [this specification](config.md).
+*Example*
 
-One or more *content directories* may be adjacent to the configuration file. This must include at least the root filesystem (referenced in the configuration file by the *root* field) and may include other related content (signatures, other configs, etc.). The interpretation of these resources is specified in the configuration. The names of the directories may be arbitrary, but users should consider using conventional names as in the example below.
+```
+/
+|-- config.json
+`-- rootfs
+```
+
+## Configuration
+
+The config file's syntax and semantics are described in [this specification](config.md).  By default, containers will use `config.json` in the bundle root:
+
+```
+/
+|-- config.json
+`-- rootfs
+```
+
+However, sometimes you need a more flexible configuration than you can get from a single static file.  Runtime's should use the following logic to select which config file to use:
+
+1. If a `config.json` file exists (or you were passed a file path), use that.
+2. If a `config` directory exists (or you were passed a directory path), walk it looking for the best platform match and use that.
+
+### Alternative configurations
+
+Runtimes like [runC][] allow you to specify a different config file explicitly, so you may find it convenient to place additional config files somewhere in your bundle.  For example, with a bundle like:
 
 ```
 /
-!
--- config.json
-!
---- rootfs
-!
---- signatures
+|-- config.json
+|-- config-shell.json
+`-- rootfs
+```
+
+Then you could use `runc` to launch your application, and `runc config-shell.json` to launch a shell in a similar container environment for poking around.
+
+### Multiple platforms
+
+In some situations, it's convenient to have a single bundle for multiple platforms.  For example, a Python bundle template could be written with the Python interpreter in `rootfs` with `process` configs designed to launch a `app/main.py`.  This template could be shared by many developers, who create bundles by dropping their application into the `app` directory without having to worry about platform idiosyncrasies.
+
 ```
+.
+|-- config
+|   |-- linux.json
+|   `-- windows.json
+|-- rootfs
+|   |-- linux
+|   `-- windows
+`-- app
+```
+
+When the runtime loads a config from a directory, it walks the directory recursively to find all `*.json` files, and checks those files for compatible [`version`s][version].  Of the compatible files, it chooses the config with:
+
+1. The best [`platform`][platform] match for the runtime system, breaking ties with
+2. The newest [`version`][version].
+
+Each config file in the directory should stand alone, so there may be some information that is duplicated among several config files.  Bundle authors who want a [DRYer][DRY] system are free to use an independent tool to generate the config files.
+
+## Content
+
+One or more *content directories* and *auxiliary files* may be adjacent to the configuration file or configuration directory. This must include at least the root filesystem (referenced in the configuration file by the [`root` field][root]) and may include other related content (signatures, other configs, etc.). The interpretation of these resources may be specified in the configuration (e.g. the [`root` field][root]) or they may be runtime extensions. The names of the non-config directories are arbitrary, but users should consider using conventional names.
 
+[runC]: https://github.com/opencontainers/runc
+[version]: ./config.md#manifest-version
+[platform]: ./config.md#platform-specific-configuration
+[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
+[root]: ./config.md#root-configuration