Update docs for new api endpoints
Signed-off-by: Michael Crosby <crosbymichael@gmail.com>
This commit is contained in:
Michael Crosby
parent
72ee22ad60
commit
8af8c56510
4 changed files with 175 additions and 48 deletions
210
README.md
210
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}'
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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,
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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{
|
||||
|
|
|
|||
|
|
@ -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 {
|
||||
|
|
|
|||
Loading…
Reference in a new issue