Update docs for new api endpoints

Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
2015-12-04 14:44:08 -08:00 · 2015-12-04 14:44:08 -08:00 · 8af8c56510
parent 72ee22ad60
commit 8af8c56510
4 changed files with 175 additions and 48 deletions
--- a/README.md
+++ b/README.md
@ -2,77 +2,203 @@

 another container runtime

-Start a container:
+#### Status 

+*alpha*
+
+What does alpha, beta, etc mean?
+* alpha - not feature complete
+* beta - feature complete but needs testing
+* prod ready - read for production
+
+
+# REST API v1
+
+## Starting a container
+
+To start a container hit the `/containers/{name}` endpoint with a `POST` request.
+The checkpoint field is option but allows you to start the container with the specified
+checkpoint name instead of a new instance of the container.
+
+Example:
 ```bash
-curl -XPOST localhost:8888/containers/redis -d '{"bundlePath": "/containers/redis"}' 
+curl -XPOST localhost:8888/containers/redis -d '{
+    "bundlePath": "/containers/redis",
+    "checkpoint: "checkpoint-name"
+    }' 
 ```

-Add a process:
+## Add a process to an existing container

+To add an additional process to a running container send a `PUT` request to the
+`/containers/{name}/processes` endpoint.
+
+Example:
 ```bash
-curl -s -XPUT localhost:8888/containers/redis/process -d@process.json | json_pp                   
-{
-   "user" : {
-      "gid" : 0,
-      "uid" : 0
-   },
-   "args" : [
-      "sh",
-      "-c",
-      "sleep 10"
-   ],
-   "env" : [
-      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
-      "TERM=xterm"
-   ]
-}
+curl -s -XPUT localhost:8888/containers/redis/process -d '{
+       "user" : {
+          "gid" : 0,
+          "uid" : 0
+       },
+       "args" : [
+          "sh",
+          "-c",
+          "sleep 10"
+       ],
+       "env" : [
+          "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+          "TERM=xterm"
+       ]
+    }'
 ```


-Get containers and state: 
+## Signal a specific process in a container
+
+To send a signal to any of the containers processes send a  `POST` request to
+the `/containers/{name}/process/{pid}` endpoint.
+
+Example

 ```bash
-curl -s localhost:8888/state | json_pp
+curl -s -XPOST  localhost:8888/containers/redis/process/1234 -d '{"signal": 15}'
+```
+
+## Get the state of containerd and all of its containers
+
+To the the entire state of the containerd instance send a `GET` request
+to the `/state` endpoint.
+
+Example:
+```bash
+curl -s localhost:8888/state
+```
+
+Response:
+```json
 {
   "containers" : [
      {
+         "state" : {
+            "status" : "running"
+         },
+         "bundlePath" : "/containers/redis",
+         "id" : "redis",
         "processes" : [
            {
               "args" : [
-                  "sh",
-                  "-c",
-                  "sleep 60"
+                  "redis-server",
+                  "--bind",
+                  "0.0.0.0"
               ],
               "user" : {
-                  "gid" : 0,
-                  "uid" : 0
+                  "gid" : 1000,
+                  "uid" : 1000
               },
-               "pid" : 25743,
+               "terminal" : false,
+               "pid" : 11497,
               "env" : [
                  "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
                  "TERM=xterm"
               ]
            }
-         ],
-         "id" : "redis",
-         "state" : {
-            "status" : "running"
-         },
-         "bundlePath" : "/containers/redis"
+         ]
      }
-   ]
+   ],
+   "machine" : {
+      "cpus" : 4,
+      "memory" : 7872909312
+   }
 }
-
 ```

-Other stuff:
+## Create a checkpoint for a container
+
+To create a checkpoint for a container send a `POST` request to the 
+`/containers/{name}/checkpoint/{checkpointname}` endpoint.  All of the options
+to this endpoint are optional.
+
+If you send `"exit": true` the container will be stopped after the checkpoint is complete,
+the default is to keep the container running.
+
+Example:

 ```bash
-# pause and resume a container
-curl -XPATCH localhost:8888/containers/redis -d '{"status": "paused"}'
-curl -XPATCH localhost:8888/containers/redis -d '{"status": "running"}'
-
-# send signal to a container's specific process
-curl -XPOST localhost:8888/containers/redis/process/18306 -d '{"signal": 9}'
+curl -s -XPOST localhost:8888/containers/redis/checkpoint/test1 -d '{
+        "exit": false,
+        "tcp": false,
+        "unixSockets": false,
+        "shell": false
+    }'
+```
+
+## List all checkpoints for a container
+
+To list all checkpoints for a container send a `GET` request to the 
+`/containers/{name}/checkpoint` endpoint.
+
+Example:
+
+```bash
+curl -s localhost:8888/containers/redis/checkpoint
+```
+
+Response:
+
+```json
+[
+   {
+      "name" : "test1",
+      "unixSockets" : false,
+      "tcp" : false,
+      "shell" : false
+   },
+   {
+      "name" : "test2",
+      "tcp" : false,
+      "unixSockets" : false,
+      "shell" : false
+   }
+]
+```
+
+## Delete a container's checkpoint
+
+To delete a container's checkpoint send a `DELETE` request to the 
+`/containers/redis/checkpoint/{checkpointname}` endpoint.
+
+Example:
+
+```bash
+curl -XDELETE -s localhost:8888/containers/redis/checkpoint/test1
+```
+
+## Update a container
+
+The update endpoint for a container accepts a JSON object with various fields 
+for the actions you with to perform.  To update a container send a `PATCH` request
+to the `/containers/{name}` endpoint.
+
+### Pause and resume a container
+
+To pause or resume a continer you want to send a `PATCH` request updating the container's state.
+
+Example:
+
+```bash
+# pause a container
+curl -XPATCH localhost:8888/containers/redis -d '{"status": "paused"}'
+
+# resume the container
+curl -XPATCH localhost:8888/containers/redis -d '{"status": "running"}'
+```
+
+### Signal the main process of a container
+
+To signal the main process of the container hit the same update endpoint with a different state.
+
+Example:
+
+```bash
+curl -s -XPATCH localhost:8888/containers/redis -d '{"signal": 9}'
 ```
--- a/api/v1/client.go
+++ b/api/v1/client.go
@ -20,9 +20,10 @@ type Client struct {

 // Start starts a container with the specified id and path to the container's
 // bundle on the system.
-func (c *Client) Start(id, path string) error {
+func (c *Client) Start(id, path, checkpoint string) error {
 	container := Container{
 		BundlePath: path,
+		Checkpoint: checkpoint,
 	}
 	buf := bytes.NewBuffer(nil)
 	if err := json.NewEncoder(buf).Encode(container); err != nil {
@ -53,7 +54,7 @@ func (c *Client) Containers() ([]Container, error) {
 	return s.Containers, nil
 }

-func (c *Client) Signal(id string, pid, signal int) error {
+func (c *Client) SignalProcess(id string, pid, signal int) error {
 	sig := Signal{
 		Signal: signal,
 	}
--- a/api/v1/server.go
+++ b/api/v1/server.go
@ -34,7 +34,7 @@ func NewServer(supervisor *containerd.Supervisor) http.Handler {
 	r.HandleFunc("/containers/{id:.*}", s.updateContainer).Methods("PATCH")

 	// internal method for replaying the journal
-	r.HandleFunc("/event", s.event).Methods("POST")
+	// r.HandleFunc("/event", s.event).Methods("POST")
 	r.HandleFunc("/events", s.events).Methods("GET")

 	// containerd handlers
@ -263,9 +263,9 @@ func (s *server) createContainer(w http.ResponseWriter, r *http.Request) {
 	e := containerd.NewEvent(containerd.StartContainerEventType)
 	e.ID = id
 	e.BundlePath = c.BundlePath
-	if c.Checkpoint != nil {
+	if c.Checkpoint != "" {
 		e.Checkpoint = &runtime.Checkpoint{
-			Name: c.Checkpoint.Name,
+			Name: c.Checkpoint,
 		}
 	}
 	e.Stdio = &runtime.Stdio{
--- a/api/v1/types.go
+++ b/api/v1/types.go
@ -29,7 +29,7 @@ type Container struct {
 	Stdout     string          `json:"stdout,omitempty"`
 	Stderr     string          `json:"stderr,omitempty"`
 	State      *ContainerState `json:"state,omitempty"`
-	Checkpoint *Checkpoint     `json:"checkpoint,omitempty"`
+	Checkpoint string          `json:"checkpoint,omitempty"`
 }

 type User struct {