Add runtime state configuration and structs

crosbymichael · crosbymichael · commit a79d5650596e · 2015-08-28T14:06:20.000-07:00
This adds runtime state information for oci container's so that it can
be persisted and used by external tools.

Signed-off-by: Michael Crosby &lt;crosbymichael@gmail.com&gt;
diff --git a/config.go b/config.go
@@ -56,3 +56,15 @@ 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"`
+	// Root is the path to the container's bundle directory.
+	Root string `json:"root"`
+}
diff --git a/runtime.md b/runtime.md
@@ -1,5 +1,47 @@
 # Runtime and Lifecycle
 
+## State
+
+The runtime state for a container is persisted on disk so that external tools can consume and act on this information.
+The runtime state is stored in a JSON encoded file.
+It is recommended that this file is stored in a temporary filesystem so that it can be removed on a system reboot.
+On Linux based systems the state information should be stored in `/run/oci/containers`.
+The directory structure for a container is `/run/oci/containers/<containerID>/state.json`.
+By providing a default location that container state is stored external applications can find all containers running on a system.
+
+* **version** (string) Version of the OCI specification used when creating the container.
+* **id** (string) ID is the container's ID.
+* **pid** (int) Pid is the ID of the main process within the container.
+* **root** (string) Root is the path to the container's bundle directory.
+
+The ID is provided in the state because hooks will be executed with the state as the payload.
+This allows the hook to perform clean and teardown logic after the runtime destroys its own state.
+The root directory to the bundle is provided in the state so that consumers can find the container's configuration and rootfs.
+
+*Example*
+
+```json
+{
+    "id": "oci-container",
+    "pid": 4422,
+    "root": "/containers/redis"
+}
+```
+
+Linux systems add some platform specific information to the state.
+
+* **externalFds** Paths to the container's open file descriptors.
+
+*Example Linux*
+
+```json
+{
+    "externalFds": [
+        "/proc/33/fd/1"
+    ]
+}
+```
+
 ## Lifecycle
 
 ### Create
diff --git a/runtime_config_linux.go b/runtime_config_linux.go
@@ -2,6 +2,9 @@ package specs
 
 import "os"
 
+// LinuxStateDirectory holds the container's state information
+const LinuxStateDirectory = "/run/oci/containers"
+
 // LinuxSpec is the full specification for linux containers.
 type LinuxRuntimeSpec struct {
 	RuntimeSpec
@@ -195,3 +198,12 @@ type Syscall struct {
 	Action Action `json:"action"`
 	Args   []*Arg `json:"args"`
 }
+
+type LinuxState struct {
+	State
+	// Linux holds platform specific state information for linux.
+	Linux struct {
+		// ExternalFds holds paths to the container's open file descriptors.
+		ExternalFds []string `json:"externalFds,omitempty"`
+	} `json:"linux,omitempty"`
+}
