From 8af8c5651092133ecbfc294223e2a2a64537387a Mon Sep 17 00:00:00 2001 From: Michael Crosby Date: Fri, 4 Dec 2015 14:44:08 -0800 Subject: [PATCH] Update docs for new api endpoints Signed-off-by: Michael Crosby --- README.md | 210 +++++++++++++++++++++++++++++++++++++---------- api/v1/client.go | 5 +- api/v1/server.go | 6 +- api/v1/types.go | 2 +- 4 files changed, 175 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index d2ece74..5b7787d 100644 --- 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}' ``` diff --git a/api/v1/client.go b/api/v1/client.go index 876793c..e7b72f7 100644 --- 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, } diff --git a/api/v1/server.go b/api/v1/server.go index 2e83595..12864d0 100644 --- 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{ diff --git a/api/v1/types.go b/api/v1/types.go index 0c7acb2..cb5e361 100644 --- 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 {