Add a "Created" state for new containers that haven't been run yet

Closes #13353

Signed-off-by: Doug Davis <dug@us.ibm.com>
Upstream-commit: dc697b1c9f2bf77b5b78aa871e3f365e333fd253
Component: engine

components/engine/daemon/list.go

@@ -53,7 +53,7 @@ func (daemon *Daemon) Containers(config *ContainersConfig) ([]*types.Container,
 
 	if i, ok := psFilters["status"]; ok {
 		for _, value := range i {
-			if value == "exited" {
+			if value == "exited" || value == "created" {
 				all = true
 			}
 		}

components/engine/daemon/state.go

@@ -52,6 +52,10 @@ func (s *State) String() string {
 		return "Dead"
 	}
 
+	if s.StartedAt.IsZero() {
+		return "Created"
+	}
+
 	if s.FinishedAt.IsZero() {
 		return ""
 	}
@@ -75,6 +79,10 @@ func (s *State) StateString() string {
 		return "dead"
 	}
 
+	if s.StartedAt.IsZero() {
+		return "created"
+	}
+
 	return "exited"
 }
 

components/engine/docs/man/docker-create.1.md

@@ -56,6 +56,16 @@ docker-create - Create a new container
 [**--cgroup-parent**[=*CGROUP-PATH*]]
 IMAGE [COMMAND] [ARG...]
 
+# DESCRIPTION
+
+Creates a writeable container layer over the specified image and prepares it for
+running the specified command. The container ID is then printed to STDOUT. This
+is similar to **docker run -d** except the container is never started. You can 
+then use the **docker start <container_id>** command to start the container at
+any point.
+
+The initial status of the container created with **docker create** is 'created'.
+
 # OPTIONS
 **-a**, **--attach**=[]
    Attach to STDIN, STDOUT or STDERR.

components/engine/docs/man/docker-ps.1.md

@@ -37,7 +37,7 @@ the running containers.
    Provide filter values. Valid filters:
                           exited=<int> - containers with exit code of <int>
                           label=<key> or label=<key>=<value>
-                          status=(restarting|running|paused|exited)
+                          status=(created|restarting|running|paused|exited)
                           name=<string> - container's name
                           id=<ID> - container's ID
 

components/engine/docs/sources/reference/api/docker_remote_api_v1.20.md

@@ -92,7 +92,7 @@ Query Parameters:
         sizes
 -   **filters** - a JSON encoded value of the filters (a `map[string][]string`) to process on the containers list. Available filters:
   -   `exited=<int>`; -- containers with exit code of  `<int>` ;
-  -   `status=`(`restarting`|`running`|`paused`|`exited`)
+  -   `status=`(`created`|`restarting`|`running`|`paused`|`exited`)
   -   `label=key` or `key=value` of a container label
 
 Status Codes:

components/engine/docs/sources/reference/commandline/cli.md

@@ -1033,7 +1033,8 @@ except the container is never started.  You can then use the `docker start
 <container_id>` command to start the container at any point.
 
 This is useful when you want to set up a container configuration ahead of time
-so that it is ready to start when you need it.
+so that it is ready to start when you need it. The initial status of the
+new container is `created`.
 
 Please see the [run command](#run) section and the [Docker run reference](
 /reference/run/) for more details.
@@ -1760,7 +1761,7 @@ The currently supported filters are:
 * label (`label=<key>` or `label=<key>=<value>`)
 * name (container's name)
 * exited (int - the code of exited containers. Only useful with `--all`)
-* status (restarting|running|paused|exited)
+* status (created|restarting|running|paused|exited)
 
 ##### Successfully exited containers
 

components/engine/integration-cli/docker_cli_ps_test.go

@@ -680,3 +680,54 @@ func (s *DockerSuite) TestPsWithSize(c *check.C) {
 		c.Fatalf("docker ps with --size should show virtual size of container")
 	}
 }
+
+func (s *DockerSuite) TestPsListContainersFilterCreated(c *check.C) {
+	// create a container
+	createCmd := exec.Command(dockerBinary, "create", "busybox")
+	out, _, err := runCommandWithOutput(createCmd)
+	if err != nil {
+		c.Fatal(out, err)
+	}
+	cID := strings.TrimSpace(out)
+	shortCID := cID[:12]
+
+	// Make sure it DOESN'T show up w/o a '-a' for normal 'ps'
+	runCmd := exec.Command(dockerBinary, "ps", "-q")
+	if out, _, err = runCommandWithOutput(runCmd); err != nil {
+		c.Fatal(out, err)
+	}
+	if strings.Contains(out, shortCID) {
+		c.Fatalf("Should have not seen '%s' in ps output:\n%s", shortCID, out)
+	}
+
+	// Make sure it DOES show up as 'Created' for 'ps -a'
+	runCmd = exec.Command(dockerBinary, "ps", "-a")
+	if out, _, err = runCommandWithOutput(runCmd); err != nil {
+		c.Fatal(out, err)
+	}
+
+	hits := 0
+	for _, line := range strings.Split(out, "\n") {
+		if !strings.Contains(line, shortCID) {
+			continue
+		}
+		hits++
+		if !strings.Contains(line, "Created") {
+			c.Fatalf("Missing 'Created' on '%s'", line)
+		}
+	}
+
+	if hits != 1 {
+		c.Fatalf("Should have seen '%s' in ps -a output once:%d\n%s", shortCID, hits, out)
+	}
+
+	// filter containers by 'create' - note, no -a needed
+	runCmd = exec.Command(dockerBinary, "ps", "-q", "-f", "status=created")
+	if out, _, err = runCommandWithOutput(runCmd); err != nil {
+		c.Fatal(out, err)
+	}
+	containerOut := strings.TrimSpace(out)
+	if !strings.HasPrefix(cID, containerOut) {
+		c.Fatalf("Expected id %s, got %s for filter, out: %s", cID, containerOut, out)
+	}
+}