From 4dc6f6d0b5933747e428685e9c927b6ea81c7a99 Mon Sep 17 00:00:00 2001
From: Lantao Liu <lantaol@google.com>
Date: Tue, 5 Feb 2019 00:15:54 -0800
Subject: [PATCH] Add state machine for sandbox and container

Signed-off-by: Lantao Liu <lantaol@google.com>
---
 pkg/store/container/status.go | 32 +++++++++++++++++++++++++++
 pkg/store/sandbox/status.go   | 41 ++++++++++++++++++++++++++++++++++-
 2 files changed, 72 insertions(+), 1 deletion(-)

diff --git a/pkg/store/container/status.go b/pkg/store/container/status.go
index 7dfe1cdb0..b73a2ef66 100644
--- a/pkg/store/container/status.go
+++ b/pkg/store/container/status.go
@@ -28,6 +28,38 @@ import (
 	runtime "k8s.io/kubernetes/pkg/kubelet/apis/cri/runtime/v1alpha2"
 )
 
+// The container state machine in the CRI plugin:
+//
+//                         +              +
+//                         |              |
+//                         | Create       | Load
+//                         |              |
+//                    +----v----+         |
+//                    |         |         |
+//                    | CREATED <---------+-----------+
+//                    |         |         |           |
+//                    +----+-----         |           |
+//                         |              |           |
+//                         | Start        |           |
+//                         |              |           |
+//                    +----v----+         |           |
+//   Exec    +--------+         |         |           |
+//  Attach   |        | RUNNING <---------+           |
+// LogReopen +-------->         |         |           |
+//                    +----+----+         |           |
+//                         |              |           |
+//                         | Stop/Exit    |           |
+//                         |              |           |
+//                    +----v----+         |           |
+//                    |         <---------+      +----v----+
+//                    |  EXITED |                |         |
+//                    |         <----------------+ UNKNOWN |
+//                    +----+----+       Stop     |         |
+//                         |                     +---------+
+//                         | Remove
+//                         v
+//                      DELETED
+
 // statusVersion is current version of container status.
 const statusVersion = "v1" // nolint
 
diff --git a/pkg/store/sandbox/status.go b/pkg/store/sandbox/status.go
index 4bd6745f9..201b19ba4 100644
--- a/pkg/store/sandbox/status.go
+++ b/pkg/store/sandbox/status.go
@@ -21,8 +21,44 @@ import (
 	"time"
 )
 
+// The sandbox state machine in the CRI plugin:
+//                    +              +
+//                    |              |
+//                    | Create(Run)  | Load
+//                    |              |
+//      Start    +----v----+         |
+//     (failed)  |         |         |
+// +-------------+  INIT   |         +-----------+
+// |             |         |         |           |
+// |             +----+----+         |           |
+// |                  |              |           |
+// |                  | Start(Run)   |           |
+// |                  |              |           |
+// | PortForward +----v----+         |           |
+// |      +------+         |         |           |
+// |      |      |  READY  <---------+           |
+// |      +------>         |         |           |
+// |             +----+----+         |           |
+// |                  |              |           |
+// |                  | Stop/Exit    |           |
+// |                  |              |           |
+// |             +----v----+         |           |
+// |             |         <---------+      +----v----+
+// |             | NOTREADY|                |         |
+// |             |         <----------------+ UNKNOWN |
+// |             +----+----+       Stop     |         |
+// |                  |                     +---------+
+// |                  | Remove
+// |                  v
+// +-------------> DELETED
+
 // State is the sandbox state we use in containerd/cri.
-// It has init state defined.
+// It includes init and unknown, which are internal states not defined in CRI.
+// The state mapping from internal states to CRI states:
+// * ready -> ready
+// * not ready -> not ready
+// * init -> not exist
+// * unknown -> not ready
 type State uint32
 
 const (
@@ -40,6 +76,9 @@ const (
 	// cleanup resources other than sandbox container, e.g. network namespace.
 	// This is an assumption made in CRI.
 	StateNotReady
+	// StateUnknown is unknown state. Sandbox only goes
+	// into unknown state when its status fails to be loaded.
+	StateUnknown
 )
 
 // Status is the status of a sandbox.