runtime: Clarify UTS and mount cleanup on 'delete'

Now that d43fc42 (config-linux: Lift no-tweaking namespace
restriction, 2017-01-11, opencontainers#649) allows us to get into this sort of
situation.  This sort of ownership may also apply to other resources
(cgroups?), but we can handle them in follow-up commits.

Also drop "Configuration" from the root header.  Everything in that
file is a configuration.

container-namespace3 (instead of container-namespace) supports the
single-page, Pandoc-generated file (see e7be40f, Cleanup the spec a
bit to remove WG/git text that's not really part of the spec,
2016-11-14, opencontainers#626).

Using an informative suggestion was recommended by Dao Quang Minh [1].
I've made the config JSON as small as possible while keeping it valid,
but there's still an unfortunate amount of boilerplate there.  There
is in-flight work to let us at least drop process.args [2].

[1]: opencontainers#651
[2]: opencontainers#620

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

config.md

@@ -20,7 +20,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
     "ociVersion": "0.1.0"
 ```
 
-## Root Configuration
+## Root
 
 **`root`** (object, REQUIRED) configures the container's root filesystem.
 
@@ -41,7 +41,7 @@ For example, if a configuration is compliant with version 1.1 of this specificat
 
 ## Mounts
 
-**`mounts`** (array, OPTIONAL) configures additional mounts (on top of [`root`](#root-configuration)).
+**`mounts`** (array, OPTIONAL) configures additional mounts (on top of [`root`](#root)).
 The runtime MUST mount entries in the listed order.
 The parameters are similar to the ones in [the Linux mount system call](http://man7.org/linux/man-pages/man2/mount.2.html).
 For Solaris, the mounts corresponds to fs resource in zonecfg(8).

runtime.md

@@ -121,11 +121,93 @@ When the process in the container is stopped, irrespective of it being as a resu
 This operation MUST generate an error if it is not provided the container ID.
 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.
-Deleting a container MUST delete the resources that were created during the `create` step.
-Note that resources associated with the container, but not created by this container, MUST NOT be deleted.
 Once a container is deleted its ID MAY be used by a subsequent container.
 
+Deleting a container MUST delete the resources that were created during the `create` step.
+Resources associated with the container, but not created by this container, MUST NOT be altered.
+
+#### Examples of resource ownership
+
+This section contains informative elaborations of the above “resources created by the container” requirements.
+It is not intended to be exhaustive.
+
+##### Joining mount namespaces (Linux)
+
+A container joins an existing [mount namespace](config-linux.md#namespaces) on Linux and pivots [root](config.md#root) into the `rootfs` directory with the following [configuration](config.md):
+
+```json
+{
+    "ociVersion": "1.0.0-rc3",
+    "platform": {
+        "os": "linux",
+        "arch": "amd64"
+    },
+    "process": {
+        "cwd": "/",
+        "args": [
+            "sh"
+        ],
+        "user": {
+            "uid": 1,
+            "gid": 1
+        }
+    },
+    "root": {
+        "path": "rootfs"
+    },
+    "linux": {
+        "namespaces": [
+            {
+                "type": "mount",
+                "path": "/proc/1234/ns/mnt"
+            }
+        ]
+    }
+}
+```
+
+When the example container is deleted, neither removing the preexisting mount namespace nor undoing the pivot into `rootfs` are allowed.
+
+##### Joining UTS namespaces (Linux)
+
+A container joins an existing [UTS namespace](config-linux.md#namespaces) on Linux and changes the [hostname](config.md#hostname) with the following [configuration](config.md):
+
+```json
+{
+    "ociVersion": "1.0.0-rc3",
+    "platform": {
+        "os": "linux",
+        "arch": "amd64"
+    },
+    "process": {
+        "cwd": "/",
+        "args": [
+            "sh"
+        ],
+        "user": {
+            "uid": 1,
+            "gid": 1
+        }
+    },
+    "root": {
+        "path": "rootfs"
+    },
+    "hostname": "alice",
+    "linux": {
+        "namespaces": [
+            {
+                "type": "uts",
+                "path": "/proc/1234/ns/uts"
+            }
+        ]
+    }
+}
+```
+
+When the example container is deleted, neither removing the preexisting UTS namespace nor undoing the hostname change are allowed.
 
 ## Hooks
 Many of the operations specified in this specification have "hooks" that allow for additional actions to be taken before or after each operation.
 See [runtime configuration for hooks](./config.md#hooks) for more information.
+
+[container-namespace3]: glossary.md#container-namespace