Talk about host specific/independent instead of mutability

Cover my action item from this week's OCI call.

Also moved State json out of config.go since its not really part of
the config.json file/config.

Signed-off-by: Doug Davis <[email protected]>

bundle.md

@@ -10,17 +10,20 @@ The definition of a bundle is only concerned with how a container, and its confi
 A Standard Container bundle contains all the information needed to load and run a container.
 This includes the following three artifacts which MUST all reside in the same directory on the local filesystem:
 
-1. `config.json` : immutable, host independent configuration.
+1. `config.json` : contains host independent configuration data.
 This REQUIRED file, which MUST be named `config.json`, contains settings that are host independent and application specific such as security permissions, environment variables and arguments.
+When the bundle is packaged up for distribution, this file MUST be included.
 See [`config.json`](config.md) for more details.
 
-2. `runtime.json` : mutable, host dependent configuration.
-This REQUIRED file, which MUST be named `runtime.json`, contains settings that are host specific such as memory limits, local device access and mount sources.
-The goal is that the bundle can be moved as a unit to another runtime and run the same application if `runtime.json` is reconfigured.
+2. `runtime.json` : contains host-specific configuration data.
+This REQUIRED file, which MUST be named `runtime.json`, contains settings that are host specific such as mount sources and hooks.
+The goal is that the bundle can be moved as a unit to another runtime and run the same application once a host-specific `runtime.json` is defined.
+When the bundle is packaged up for distribution, this file MUST NOT be included.
 See [`runtime.json`](runtime-config.md) for more details.
 
 3. A directory representing the root filesystem of the container.
 While the name of this REQUIRED directory may be arbitrary, users should consider using a conventional name, such as `rootfs`.
+When the bundle is packaged up for distribution, this directory MUST be included.
 This directory MUST be referenced from within the `config.json` file.
 
 While these three artifacts MUST all be present in a single directory on the local filesytem, that directory itself is not part of the bundle.

config.go

@@ -1,7 +1,8 @@
 package specs
 
 // Spec is the base configuration for the container. It specifies platform
-// independent configuration.
+// independent configuration. This information must be included when the
+// bundle is packaged for distribution.
 type Spec struct {
  // Version is the version of the specification that is supported.
  Version string `json:"version"`
@@ -56,15 +57,3 @@ type MountPoint struct {
  // Path specifies the path of the mount. The path and child directories MUST exist, a runtime MUST NOT create directories automatically to a mount point.
  Path string `json:"path"`
 }
-
-// State holds information about the runtime state of the container.
-type State struct {
- // Version is the version of the specification that is supported.
- Version string `json:"version"`
- // ID is the container ID
- ID string `json:"id"`
- // Pid is the process id for the container's main process.
- Pid int `json:"pid"`
- // BundlePath is the path to the container's bundle directory.
- BundlePath string `json:"bundlePath"`
-}

runtime_config.go

@@ -1,6 +1,8 @@
 package specs
 
-// RuntimeSpec is the generic runtime state information on a running container
+// RuntimeSpec contains host-specific configuration information for
+// a container. This information must not be included when the bundle
+// is packaged for distribution.
 type RuntimeSpec struct {
  // Mounts is a mapping of names to mount configurations.
  // Which mounts will be mounted and where should be chosen with MountPoints

state.go

@@ -0,0 +1,16 @@
+package specs
+
+// State holds information about the runtime state of the container.
+// This information will be stored in a file called `state.json`.
+// The location of this file will be operating system specific. On Linux
+// it will be in `/run/opencontainers/runc/<containerID>/state.json`
+type State struct {
+ // Version is the version of the specification that is supported.
+ Version string `json:"version"`
+ // ID is the container ID
+ ID string `json:"id"`
+ // Pid is the process id for the container's main process.
+ Pid int `json:"pid"`
+ // BundlePath is the path to the container's bundle directory.
+ BundlePath string `json:"bundlePath"`
+}