---
swagger: "2.0"
schemes:
- "http"
- "https"
produces:
- "application/json"
- "text/plain"
consumes:
- "application/json"
- "text/plain"
basePath: "/v1.24"
info:
title: "Pouch Engine API"
version: "1.24"
description: |
API is an HTTP API served by Pouch Engine.
produces:
- "application/json"
paths:
/_ping:
get:
summary: ""
description: ""
responses:
200:
description: "no error"
schema:
type: "string"
example: "OK"
500:
$ref: "#/responses/500ErrorResponse"
/version:
get:
summary: "Get Pouchd version"
description: ""
responses:
200:
schema:
$ref: '#/definitions/SystemVersion'
description: "no error"
500:
$ref: "#/responses/500ErrorResponse"
/info:
get:
summary: "Get System information"
description: ""
responses:
200:
schema:
$ref: '#/definitions/SystemInfo'
description: "no error"
500:
$ref: "#/responses/500ErrorResponse"
/auth:
post:
summary: "Check auth configuration"
description: "Validate credentials for a registry and, if available, get an identity token for accessing the registry without password."
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "An identity token was generated successfully."
schema:
$ref: "#/definitions/AuthResponse"
401:
description: "Login unauthorized"
schema:
$ref: "#/responses/401ErrorResponse"
500:
description: "Server error"
schema:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "authConfig"
in: "body"
description: "Authentication to check"
schema:
$ref: "#/definitions/AuthConfig"
/daemon/update:
post:
summary: "Update daemon's labels and image proxy"
consumes:
- "application/json"
produces:
- "application/json"
responses:
200:
description: "no error"
400:
description: "bad parameter"
schema:
$ref: '#/definitions/Error'
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "DaemonUpdateConfig"
in: body
description: "Config used to update daemon, only labels and image proxy are allowed."
schema:
$ref: "#/definitions/DaemonUpdateConfig"
/images/create:
post:
summary: "Create an image by pulling from a registry or importing from an existing source file"
consumes:
- "text/plain"
- "application/octet-stream"
produces:
- "application/json"
responses:
200:
description: "no error"
404:
schema:
$ref: '#/definitions/Error'
description: "image not found"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "fromImage"
in: "query"
description: "Name of the image to pull. The name may include a tag or digest. This parameter may only be used when pulling an image. The pull is cancelled if the HTTP connection is closed."
type: "string"
- name: "fromSrc"
in: "query"
description: "Source to import. The value may be a URL from which the image can be retrieved or `-` to read the image from the request body. This parameter may only be used when importing an image."
type: "string"
- name: "repo"
in: "query"
description: "Repository name given to an image when it is imported. The repo may include a tag. This parameter may only be used when importing an image."
type: "string"
- name: "tag"
in: "query"
description: "Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled."
type: "string"
- name: "inputImage"
in: "body"
description: "Image content if the value `-` has been specified in fromSrc query parameter"
schema:
type: "string"
required: false
- name: "X-Registry-Auth"
in: "header"
description: "A base64-encoded auth configuration. [See the authentication section for details.](#section/Authentication)"
type: "string"
/images/load:
post:
summary: "Import images"
description: |
Load a set of images by oci.v1 format tar stream
consumes:
- application/x-tar
responses:
200:
description: "no error"
500:
description: "server error"
schema:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "imageTarStream"
in: "body"
description: "tar stream containing images"
schema:
type: "string"
format: "binary"
- name: "name"
in: "query"
description: "set the image name for the tar stream, default unknown/unknown"
type: "string"
/images/{imageid}/json:
get:
summary: "Inspect a image"
description: "Return the information about image"
operationId: "ImageInspect"
produces:
- "application/json"
responses:
200:
description: "no error"
schema:
$ref: "#/definitions/ImageInfo"
examples:
application/json:
CreatedAt: "2017-12-19 15:32:09"
Digest: "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
ID: "e216a057b1cb"
Name: "ubuntu:12.04"
Size: 103579269
Tag: "12.04"
404:
description: "no such image"
schema:
$ref: "#/definitions/Error"
examples:
application/json:
message: "No such image: e216a057b1cb"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/imageid"
/images/json:
get:
summary: "List Images"
description: "Return a list of stored images."
operationId: "ImageList"
produces:
- "application/json"
responses:
200:
description: "Summary image data for the images matching the query"
schema:
type: "array"
items:
$ref: "#/definitions/ImageInfo"
examples:
application/json:
- Id: "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8"
ParentId: ""
RepoTags:
- "ubuntu:12.04"
- "ubuntu:precise"
RepoDigests:
- "ubuntu@sha256:992069aee4016783df6345315302fa59681aae51a8eeb2f889dea59290f21787"
Created: 1474925151
Size: 103579269
VirtualSize: 103579269
SharedSize: 0
Labels: {}
Containers: 2
- Id: "sha256:3e314f95dcace0f5e4fd37b10862fe8398e3c60ed36600bc0ca5fda78b087175"
ParentId: ""
RepoTags:
- "ubuntu:12.10"
- "ubuntu:quantal"
RepoDigests:
- "ubuntu@sha256:002fba3e3255af10be97ea26e476692a7ebed0bb074a9ab960b2e7a1526b15d7"
- "ubuntu@sha256:68ea0200f0b90df725d99d823905b04cf844f6039ef60c60bf3e019915017bd3"
Created: 1403128455
Size: 172064416
VirtualSize: 172064416
SharedSize: 0
Labels: {}
Containers: 5
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "all"
in: "query"
description: "Show all images. Only images from a final layer (no children) are shown by default."
type: "boolean"
- name: "filters"
in: "query"
description: |
A JSON encoded value of the filters (a `map[string][]string`) to process on the images list. Available filters:
- `before`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
- `dangling=true`
- `label=key` or `label="key=value"` of an image label
- `reference`=(`<image-name>[:<tag>]`)
- `since`=(`<image-name>[:<tag>]`, `<image id>` or `<image@digest>`)
type: "string"
- name: "digests"
in: "query"
description: "Show digest information as a `RepoDigests` field on each image."
type: "boolean"
/images/search:
get:
summary: "Search images"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
type: "array"
items:
$ref: "#/definitions/SearchResultItem"
500:
$ref: "#/responses/500ErrorResponse"
/images/{imageid}/tag:
post:
summary: "Tag an image"
description: "Add tag reference to the existing image"
parameters:
- $ref: "#/parameters/imageid"
- name: "repo"
in: "query"
description: "The repository to tag in. For example, `someuser/someimage`."
type: "string"
- name: "tag"
in: "query"
description: "The name of the new tag."
type: "string"
responses:
201:
description: "No error"
400:
description: "Bad parameter"
schema:
$ref: "#/definitions/Error"
404:
description: "no such image"
schema:
$ref: "#/definitions/Error"
500:
$ref: "#/responses/500ErrorResponse"
/images/{imageid}:
delete:
summary: "Remove an image"
description: "Remove an image by reference."
parameters:
- $ref: "#/parameters/imageid"
- name: "force"
in: "query"
description: "Remove the image even if it is being used"
type: "boolean"
default: false
responses:
204:
description: "No error"
404:
description: "no such image"
schema:
$ref: "#/definitions/Error"
examples:
application/json:
message: "No such image: c2ada9df5af8"
500:
$ref: "#/responses/500ErrorResponse"
/containers/create:
post:
summary: "Create a container"
consumes:
- "application/json"
produces:
- "application/json"
parameters:
- name: "name"
in: "query"
description: "Assign the specified name to the container. Must match `/?[a-zA-Z0-9_-]+`."
type: "string"
pattern: "/?[a-zA-Z0-9_-]+"
- name: "body"
in: "body"
description: "Container to create"
schema:
$ref: "#/definitions/ContainerCreateConfig"
required: true
responses:
201:
description: "Container created successfully"
schema:
$ref: "#/definitions/ContainerCreateResp"
examples:
application/json:
Id: "e90e34656806"
Warnings: []
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
description: "no such image"
schema:
$ref: "#/definitions/Error"
examples:
application/json:
message: "image: xxx:latest: not found"
409:
description: "conflict"
schema:
$ref: "#/definitions/Error"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/json:
get:
summary: "Inspect a container"
description: "Return low-level information about a container."
operationId: "ContainerInspect"
produces:
- "application/json"
responses:
200:
description: "no error"
schema:
$ref: "#/definitions/ContainerJSON"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
- name: "size"
in: "query"
type: "boolean"
description: "Return the size of container as fields `SizeRw` and `SizeRootFs`"
tags: ["Container"]
/containers/json:
get:
summary: "List containers"
operationId: "ContainerList"
produces: ["application/json"]
responses:
200:
description: "Summary containers that matches the query"
schema:
type: "array"
items:
$ref: "#/definitions/Container"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "all"
in: "query"
description: "Return all containers. By default, only running containers are shown"
type: "boolean"
default: false
/containers/{id}/rename:
post:
summary: "Rename a container"
operationId: "ContainerRename"
parameters:
- $ref: "#/parameters/id"
- name: "name"
in: "query"
required: true
description: "New name for the container"
type: "string"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
409:
description: "name already in use"
schema:
$ref: "#/definitions/Error"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/restart:
post:
summary: "Restart a container"
operationId: "ContainerRestart"
parameters:
- $ref: "#/parameters/id"
- name: "name"
in: "query"
required: true
description: "New name for the container"
type: "string"
- name: "t"
in: "query"
description: "Number of seconds to wait before killing the container"
type: "integer"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/start:
post:
summary: "Start a container"
operationId: "ContainerStart"
parameters:
- $ref: "#/parameters/id"
- name: "detachKeys"
in: "query"
description: "Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`."
type: "string"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/stop:
post:
summary: "Stop a container"
operationId: "ContainerStop"
parameters:
- $ref: "#/parameters/id"
- name: "t"
in: "query"
description: "Number of seconds to wait before killing the container"
type: "integer"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/pause:
post:
summary: "Pause a container"
operationId: "ContainerPause"
parameters:
- $ref: "#/parameters/id"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/unpause:
post:
summary: "Unpause a container"
operationId: "ContainerUnpause"
parameters:
- $ref: "#/parameters/id"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/top:
post:
summary: "Display the running processes of a container"
operationId: "ContainerTop"
parameters:
- $ref: "#/parameters/id"
- name: "ps_args"
in: "query"
description: "top arguments"
type: "string"
responses:
200:
description: "no error"
schema:
$ref: "#/definitions/ContainerProcessList"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/wait:
post:
summary: "Block until a container stops, then returns the exit code."
operationId: "ContainerWait"
parameters:
- $ref: "#/parameters/id"
responses:
200:
description: "The container has exited."
schema:
type: "object"
required: [StatusCode]
properties:
StatusCode:
description: "Exit code of the container"
type: "integer"
x-nullable: false
Error:
description: "The error message of waiting container"
type: "string"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}:
delete:
summary: "Remove one container"
operationId: "ContainerRemove"
parameters:
- $ref: "#/parameters/id"
- name: "force"
in: "query"
description: "If the container is running, force query is used to kill it and remove it forcefully."
type: "boolean"
responses:
204:
description: "no error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/exec:
post:
summary: "Create an exec instance"
description: "Run a command inside a running container."
operationId: "ContainerExec"
consumes:
- "application/json"
produces:
- "application/json"
responses:
201:
description: "no error"
schema:
$ref: "#/definitions/ExecCreateResp"
404:
$ref: "#/responses/404ErrorResponse"
409:
description: "container is paused"
schema:
$ref: "#/definitions/Error"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
- name: "body"
in: "body"
schema:
$ref: "#/definitions/ExecCreateConfig"
required: true
tags: ["Exec"]
/containers/{id}/logs:
get:
summary: "Get container logs"
description: |
Get `stdout` and `stderr` logs from a container.
Note: This endpoint works only for containers with the `json-file` or `journald` logging driver.
operationId: "ContainerLogs"
responses:
101:
description: "logs returned as a stream"
schema:
type: "string"
format: "binary"
200:
description: "logs returned as a string in response body"
schema:
type: "string"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "follow"
in: "query"
description: |
Return the logs as a stream.
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Return logs from `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Return logs from `stderr`"
type: "boolean"
default: false
- name: "since"
in: "query"
description: "Only return logs since this time, as a UNIX timestamp"
type: "integer"
default: 0
- name: "until"
in: "query"
description: "Only return logs before this time, as a UNIX timestamp"
type: "integer"
default: 0
- name: "timestamps"
in: "query"
description: "Add timestamps to every log line"
type: "boolean"
default: false
- name: "tail"
in: "query"
description: "Only return this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines."
type: "string"
default: "all"
tags: ["Container"]
/containers/{id}/resize:
post:
summary: "changes the size of the tty for a container"
operationId: "ContainerResize"
parameters:
- $ref: "#/parameters/id"
- name: "height"
in: "query"
description: "height of the tty"
type: "string"
- name: "width"
in: "query"
description: "width of the tty"
type: "string"
responses:
200:
description: "no error"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
tags: ["Container"]
/exec/{id}/start:
post:
summary: "Start an exec instance"
description: "Starts a previously set up exec instance. If detach is true, this endpoint returns immediately after starting the command. Otherwise, it sets up an interactive session with the command."
operationId: "ExecStart"
consumes:
- "application/json"
produces:
- "application/vnd.raw-stream"
responses:
200:
description: "No error"
404:
description: "No such exec instance"
schema:
$ref: "#/definitions/Error"
409:
description: "Container is stopped or paused"
schema:
$ref: "#/definitions/Error"
parameters:
- name: "execStartConfig"
in: "body"
schema:
$ref: "#/definitions/ExecStartConfig"
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/exec/{id}/json:
get:
summary: "Inspect an exec instance"
description: "Return low-level information about an exec instance."
operationId: "ExecInspect"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
$ref: "#/definitions/ContainerExecInspect"
404:
description: "No such exec instance"
schema:
$ref: "#/responses/404ErrorResponse"
500:
description: "Server error"
schema:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "id"
in: "path"
description: "Exec instance ID"
required: true
type: "string"
tags: ["Exec"]
/containers/{id}/attach:
post:
summary: "Attach to a container"
description: |
Attach to a container to read its output or send it input. You can attach to the same container multiple times and you can reattach to containers that have been detached.
Either the `stream` or `logs` parameter must be `true` for this endpoint to do anything.
### Hijacking
This endpoint hijacks the HTTP connection to transport `stdin`, `stdout`, and `stderr` on the same socket.
This is the response from the daemon for an attach request:
```
HTTP/1.1 200 OK
Content-Type: application/vnd.raw-stream
[STREAM]
```
After the headers and two new lines, the TCP connection can now be used for raw, bidirectional communication between the client and server.
To hint potential proxies about connection hijacking, the Pouch client can also optionally send connection upgrade headers.
For example, the client sends this request to upgrade the connection:
```
POST /containers/16253994b7c4/attach?stream=1&stdout=1 HTTP/1.1
Upgrade: tcp
Connection: Upgrade
```
The Pouch daemon will respond with a `101 UPGRADED` response, and will similarly follow with the raw stream:
```
HTTP/1.1 101 UPGRADED
Content-Type: application/vnd.raw-stream
Connection: Upgrade
Upgrade: tcp
[STREAM]
```
### Stream format
When the TTY setting is disabled in [`POST /containers/create`](#operation/ContainerCreate), the stream over the hijacked connected is multiplexed to separate out `stdout` and `stderr`. The stream consists of a series of frames, each containing a header and a payload.
The header contains the information which the stream writes (`stdout` or `stderr`). It also contains the size of the associated frame encoded in the last four bytes (`uint32`).
It is encoded on the first eight bytes like this:
```go
header := [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1, SIZE2, SIZE3, SIZE4}
```
`STREAM_TYPE` can be:
- 0: `stdin` (is written on `stdout`)
- 1: `stdout`
- 2: `stderr`
`SIZE1, SIZE2, SIZE3, SIZE4` are the four bytes of the `uint32` size encoded as big endian.
Following the header is the payload, which is the specified number of bytes of `STREAM_TYPE`.
The simplest way to implement this protocol is the following:
1. Read 8 bytes.
2. Choose `stdout` or `stderr` depending on the first byte.
3. Extract the frame size from the last four bytes.
4. Read the extracted size and output it on the correct output.
5. Goto 1.
### Stream format when using a TTY
When the TTY setting is enabled in [`POST /containers/create`](#operation/ContainerCreate), the stream is not multiplexed. The data exchanged over the hijacked connection is simply the raw data from the process PTY and client's `stdin`.
operationId: "ContainerAttach"
produces:
- "application/vnd.raw-stream"
responses:
101:
description: "no error, hints proxy about hijacking"
200:
description: "no error, no upgrade header found"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
description: "no such container"
schema:
$ref: "#/definitions/Error"
examples:
application/json:
message: "No such container: c2ada9df5af8"
500:
description: "server error"
schema:
$ref: "#/definitions/Error"
parameters:
- name: "id"
in: "path"
required: true
description: "ID or name of the container"
type: "string"
- name: "detachKeys"
in: "query"
description: "Override the key sequence for detaching a container.Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`."
type: "string"
- name: "logs"
in: "query"
description: |
Replay previous logs from the container.
This is useful for attaching to a container that has started and you want to output everything since the container started.
If `stream` is also enabled, once all the previous output has been returned, it will seamlessly transition into streaming current output.
type: "boolean"
default: false
- name: "stream"
in: "query"
description: "Stream attached streams from the time the request was made onwards"
type: "boolean"
default: false
- name: "stdin"
in: "query"
description: "Attach to `stdin`"
type: "boolean"
default: false
- name: "stdout"
in: "query"
description: "Attach to `stdout`"
type: "boolean"
default: false
- name: "stderr"
in: "query"
description: "Attach to `stderr`"
type: "boolean"
default: false
tags: ["Container"]
/containers/{id}/update:
post:
summary: "Update the configurations of a container"
operationId: "ContainerUpdate"
parameters:
- $ref: "#/parameters/id"
- name: "updateConfig"
in: "body"
schema:
$ref: "#/definitions/UpdateConfig"
responses:
200:
description: "no error"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/containers/{id}/upgrade:
post:
summary: "Upgrade a container with new image and args"
operationId: "ContainerUpgrade"
parameters:
- $ref: "#/parameters/id"
- name: "upgradeConfig"
in: "body"
schema:
$ref: "#/definitions/ContainerUpgradeConfig"
responses:
200:
description: "no error"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Container"]
/volumes:
get:
summary: "List volumes"
operationId: "VolumeList"
produces: ["application/json"]
responses:
200:
description: "Summary volume data that matches the query"
schema:
$ref: "#/definitions/VolumeListResp"
examples:
application/json:
Volumes:
- CreatedAt: "2017-07-19T12:00:26Z"
Name: "tardis"
Driver: "local"
Mountpoint: "/var/lib/pouch/volumes/tardis"
Labels:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Scope: "local"
Options:
device: "tmpfs"
o: "opt.size=100m,uid=1000"
type: "tmpfs"
Warnings: []
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "filters"
in: "query"
description: |
JSON encoded value of the filters (a `map[string][]string`) to
process on the volumes list. Available filters:
- `dangling=<boolean>` When set to `true` (or `1`), returns all
volumes that are not in use by a container. When set to `false`
(or `0`), only volumes that are in use by one or more
containers are returned.
- `driver=<volume-driver-name>` Matches volumes based on their driver.
- `label=<key>` or `label=<key>:<value>` Matches volumes based on
the presence of a `label` alone or a `label` and a value.
- `name=<volume-name>` Matches all or part of a volume name.
type: "string"
format: "json"
tags: ["Volume"]
/volumes/create:
post:
summary: "Create a volume"
operationId: "VolumeCreate"
consumes: ["application/json"]
produces: ["application/json"]
responses:
201:
description: "The volume was created successfully"
schema:
$ref: "#/definitions/VolumeInfo"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "body"
in: "body"
required: true
description: "Volume configuration"
schema:
$ref: "#/definitions/VolumeCreateConfig"
tags: ["Volume"]
/volumes/{id}:
get:
summary: "Inspect a volume"
operationId: "VolumeInspect"
produces: ["application/json"]
responses:
200:
description: "No error"
schema:
$ref: "#/definitions/VolumeInfo"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
tags: ["Volume"]
delete:
summary: "Delete a volume"
operationId: "VolumeDelete"
responses:
204:
description: "No error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
tags: ["Volume"]
/networks/create:
post:
summary: "Create a network"
operationId: "NetworkCreate"
consumes: ["application/json"]
produces: ["application/json"]
responses:
201:
description: "The network was created successfully"
schema:
$ref: "#/definitions/NetworkCreateResp"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
409:
description: "name already in use"
schema:
$ref: "#/definitions/Error"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "NetworkCreateConfig"
in: "body"
required: true
description: "Network configuration"
schema:
$ref: "#/definitions/NetworkCreateConfig"
tags: ["Network"]
/networks/{id}:
get:
summary: "Inspect a network"
operationId: "NetworkInspect"
produces:
- "application/json"
responses:
200:
description: "No error"
schema:
$ref: "#/definitions/NetworkInspectResp"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
tags: ["Network"]
delete:
summary: "Remove a network"
operationId: "NetworkDelete"
responses:
204:
description: "No error"
403:
description: "operation not supported for pre-defined networks"
schema:
$ref: "#/definitions/Error"
404:
$ref: "#/responses/404ErrorResponse"
500:
$ref: "#/responses/500ErrorResponse"
parameters:
- $ref: "#/parameters/id"
tags: ["Network"]
/networks:
get:
summary: "List networks"
operationId: "NetworkList"
produces: ["application/json"]
responses:
200:
description: "Summary networks that matches the query"
schema:
$ref: "#/definitions/NetworkResource"
500:
$ref: "#/responses/500ErrorResponse"
tags: ["Network"]
/networks/{id}/connect:
post:
summary: "Connect a container to a network"
operationId: "NetworkConnect"
consumes:
- "application/json"
responses:
200:
description: "No error"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
description: "Network or container not found"
schema:
$ref: "#/responses/404ErrorResponse"
500:
description: "Server error"
schema:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "id"
in: "path"
description: "Network ID or name"
required: true
type: "string"
- name: "container"
in: "body"
required: true
schema:
$ref: "#/definitions/NetworkConnect"
tags: ["Network"]
/networks/{id}/disconnect:
post:
summary: "Disconnect a container from a network"
operationId: "NetworkDisconnect"
consumes:
- "application/json"
responses:
200:
description: "No error"
400:
description: "bad parameter"
schema:
$ref: "#/definitions/Error"
404:
description: "Network or container not found"
schema:
$ref: "#/responses/404ErrorResponse"
500:
description: "Server error"
schema:
$ref: "#/responses/500ErrorResponse"
parameters:
- name: "id"
in: "path"
description: "Network ID or name"
required: true
type: "string"
- name: "NetworkDisconnect"
in: "body"
required: true
description: "Network disconnect parameters"
schema:
$ref: "#/definitions/NetworkDisconnect"
tags: ["Network"]
definitions:
Error:
type: "object"
properties:
message:
type: string
SystemVersion:
type: "object"
properties:
Version:
type: "string"
description: "version of Pouch Daemon"
example: "0.1.2"
ApiVersion:
type: "string"
description: "Api Version held by daemon"
example: ""
GitCommit:
type: "string"
description: "Commit ID held by the latest commit operation"
example: ""
GoVersion:
type: "string"
description: "version of Go runtime"
example: "1.8.3"
Os:
type: "string"
description: "Operating system type of underlying system"
example: "linux"
Arch:
type: "string"
description: "Arch type of underlying hardware"
example: "amd64"
KernelVersion:
type: "string"
description: "Operating system kernel version"
example: "3.13.0-106-generic"
BuildTime:
type: "string"
description: "The time when this binary of daemon is built"
example: "2017-08-29T17:41:57.729792388+00:00"
SystemInfo:
type: "object"
properties:
ID:
description: |
Unique identifier of the daemon.
<p><br /></p>
> **Note**: The format of the ID itself is not part of the API, and
> should not be considered stable.
type: "string"
example: "7TRN:IPZB:QYBB:VPBQ:UMPP:KARE:6ZNR:XE6T:7EWV:PKF4:ZOJD:TPYS"
Containers:
description: "Total number of containers on the host."
type: "integer"
example: 14
ContainersRunning:
description: |
Number of containers with status `"running"`.
type: "integer"
example: 3
ContainersPaused:
description: |
Number of containers with status `"paused"`.
type: "integer"
example: 1
ContainersStopped:
description: |
Number of containers with status `"stopped"`.
type: "integer"
example: 10
Images:
description: |
Total number of images on the host.
Both _tagged_ and _untagged_ (dangling) images are counted.
type: "integer"
example: 508
Driver:
description: "Name of the storage driver in use."
type: "string"
example: "overlay2"
DriverStatus:
description: |
Information specific to the storage driver, provided as
"label" / "value" pairs.
This information is provided by the storage driver, and formatted
in a way consistent with the output of `pouch info` on the command
line.
<p><br /></p>
> **Note**: The information returned in this field, including the
> formatting of values and labels, should not be considered stable,
> and may change without notice.
type: "array"
items:
type: "array"
items:
type: "string"
example:
- ["Backing Filesystem", "extfs"]
- ["Supports d_type", "true"]
- ["Native Overlay Diff", "true"]
PouchRootDir:
description: |
Root directory of persistent Pouch state.
Defaults to `/var/lib/pouch` on Linux.
type: "string"
example: "/var/lib/pouch"
Debug:
description: "Indicates if the daemon is running in debug-mode / with debug-level logging enabled."
type: "boolean"
example: true
LoggingDriver:
description: |
The logging driver to use as a default for new containers.
type: "string"
VolumeDrivers:
description: |
The list of volume drivers which the pouchd supports
type: "array"
items:
type: "string"
example: ["local", "tmpfs"]
CgroupDriver:
description: |
The driver to use for managing cgroups.
type: "string"
x-nullable: false
enum: ["cgroupfs", "systemd"]
default: "cgroupfs"
example: "cgroupfs"
KernelVersion:
description: |
Kernel version of the host.
On Linux, this information obtained from `uname`.
type: "string"
OperatingSystem:
description: |
Name of the host's operating system, for example: "Ubuntu 16.04.2 LTS".
type: "string"
example: "Alpine Linux v3.5"
OSType:
description: |
Generic type of the operating system of the host, as returned by the
Go runtime (`GOOS`).
Currently returned value is "linux". A full list of
possible values can be found in the [Go documentation](https://golang.org/doc/install/source#environment).
type: "string"
example: "linux"
Architecture:
description: |
Hardware architecture of the host, as returned by the Go runtime
(`GOARCH`).
A full list of possible values can be found in the [Go documentation](https://golang.org/doc/install/source#environment).
type: "string"
example: "x86_64"
NCPU:
description: |
The number of logical CPUs usable by the daemon.
The number of available CPUs is checked by querying the operating
system when the daemon starts. Changes to operating system CPU
allocation after the daemon is started are not reflected.
type: "integer"
example: 4
MemTotal:
description: |
Total amount of physical memory available on the host, in kilobytes (kB).
type: "integer"
format: "int64"
example: 2095882240
IndexServerAddress:
description: |
Address / URL of the index server that is used for image search,
and as a default for user authentication.
type: "string"
DefaultRegistry:
description: |
default registry can be defined by user.
type: "string"
RegistryConfig:
$ref: "#/definitions/RegistryServiceConfig"
HttpProxy:
description: |
HTTP-proxy configured for the daemon. This value is obtained from the
[`HTTP_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable.
Containers do not automatically inherit this configuration.
type: "string"
example: "http://user:pass@proxy.corp.example.com:8080"
HttpsProxy:
description: |
HTTPS-proxy configured for the daemon. This value is obtained from the
[`HTTPS_PROXY`](https://www.gnu.org/software/wget/manual/html_node/Proxies.html) environment variable.
Containers do not automatically inherit this configuration.
type: "string"
example: "https://user:pass@proxy.corp.example.com:4443"
Name:
description: "Hostname of the host."
type: "string"
example: "node5.corp.example.com"
Labels:
description: |
User-defined labels (key/value metadata) as set on the daemon.
type: "array"
items:
type: "string"
example: ["storage=ssd", "production"]
ExperimentalBuild:
description: |
Indicates if experimental features are enabled on the daemon.
type: "boolean"
example: true
ServerVersion:
description: |
Version string of the daemon.
type: "string"
example: "17.06.0-ce"
Runtimes:
description: |
List of [OCI compliant](https://github.com/opencontainers/runtime-spec)
runtimes configured on the daemon. Keys hold the "name" used to
reference the runtime.
The Pouch daemon relies on an OCI compliant runtime (invoked via the
`containerd` daemon) as its interface to the Linux kernel namespaces,
cgroups, and SELinux.
The default runtime is `runc`, and automatically configured. Additional
runtimes can be configured by the user and will be listed here.
type: "object"
additionalProperties:
$ref: "#/definitions/Runtime"
default:
runc:
path: "pouch-runc"
example:
runc:
path: "pouch-runc"
runc-master:
path: "/go/bin/runc"
custom:
path: "/usr/local/bin/my-oci-runtime"
runtimeArgs: ["--debug", "--systemd-cgroup=false"]
DefaultRuntime:
description: |
Name of the default OCI runtime that is used when starting containers.
The default can be overridden per-container at create time.
type: "string"
x-nullable: false
default: "runc"
example: "runc"
LiveRestoreEnabled:
description: |
Indicates if live restore is enabled.
If enabled, containers are kept running when the daemon is shutdown
or upon daemon start if running containers are detected.
type: "boolean"
x-nullable: false
default: false
example: false
LxcfsEnabled:
description: |
Indicates if lxcfs is enabled.
type: "boolean"
x-nullable: false
default: false
example: false
ContainerdCommit:
$ref: "#/definitions/Commit"
RuncCommit:
$ref: "#/definitions/Commit"
SecurityOptions:
description: |
List of security features that are enabled on the daemon, such as
apparmor, seccomp, SELinux, and user-namespaces (userns).
Additional configuration options for each security feature may
be present, and are included as a comma-separated list of key/value
pairs.
type: "array"
items:
type: "string"
example:
- "name=apparmor"
- "name=seccomp,profile=default"
- "name=selinux"
- "name=userns"
ListenAddresses:
description: "List of addresses the pouchd listens on"
type: "array"
items:
type: "string"
example:
- ["unix:///var/run/pouchd.sock", "tcp://0.0.0.0:4243"]
DaemonUpdateConfig:
type: "object"
properties:
Labels:
description: "Labels indentified the attributes of daemon"
type: "array"
items:
type: "string"
example: ["storage=ssd", "zone=hangzhou"]
ImageProxy:
description: "Image proxy used to pull image."
type: "string"
RegistryServiceConfig:
description: |
RegistryServiceConfig stores daemon registry services configuration.
type: "object"
x-nullable: true
properties:
AllowNondistributableArtifactsCIDRs:
description: |
List of IP ranges to which nondistributable artifacts can be pushed,
using the CIDR syntax [RFC 4632](https://tools.ietf.org/html/4632).
Some images contain artifacts whose distribution is restricted by license.
When these images are pushed to a registry, restricted artifacts are not
included.
This configuration override this behavior, and enables the daemon to
push nondistributable artifacts to all registries whose resolved IP
address is within the subnet described by the CIDR syntax.
This option is useful when pushing images containing
nondistributable artifacts to a registry on an air-gapped network so
hosts on that network can pull the images without connecting to
another server.
> **Warning**: Nondistributable artifacts typically have restrictions
> on how and where they can be distributed and shared. Only use this
> feature to push artifacts to private registries and ensure that you
> are in compliance with any terms that cover redistributing
> nondistributable artifacts.
x-omitempty: true
type: "array"
items:
type: "string"
example: ["::1/128", "127.0.0.0/8"]
AllowNondistributableArtifactsHostnames:
description: |
List of registry hostnames to which nondistributable artifacts can be
pushed, using the format `<hostname>[:<port>]` or `<IP address>[:<port>]`.
Some images (for example, Windows base images) contain artifacts
whose distribution is restricted by license. When these images are
pushed to a registry, restricted artifacts are not included.
This configuration override this behavior for the specified
registries.
This option is useful when pushing images containing
nondistributable artifacts to a registry on an air-gapped network so
hosts on that network can pull the images without connecting to
another server.
> **Warning**: Nondistributable artifacts typically have restrictions
> on how and where they can be distributed and shared. Only use this
> feature to push artifacts to private registries and ensure that you
> are in compliance with any terms that cover redistributing
> nondistributable artifacts.
x-omitempty: true
type: "array"
items:
type: "string"
example: ["registry.internal.corp.example.com:3000", "[2001:db8:a0b:12f0::1]:443"]
InsecureRegistryCIDRs:
description: |
List of IP ranges of insecure registries, using the CIDR syntax
([RFC 4632](https://tools.ietf.org/html/4632)). Insecure registries
accept un-encrypted (HTTP) and/or untrusted (HTTPS with certificates
from unknown CAs) communication.
By default, local registries (`127.0.0.0/8`) are configured as
insecure. All other registries are secure. Communicating with an
insecure registry is not possible if the daemon assumes that registry
is secure.
This configuration override this behavior, insecure communication with
registries whose resolved IP address is within the subnet described by
the CIDR syntax.
Registries can also be marked insecure by hostname. Those registries
are listed under `IndexConfigs` and have their `Secure` field set to
`false`.
> **Warning**: Using this option can be useful when running a local
> registry, but introduces security vulnerabilities. This option
> should therefore ONLY be used for testing purposes. For increased
> security, users should add their CA to their system's list of trusted
> CAs instead of enabling this option.
x-omitempty: true
type: "array"
items:
type: "string"
example: ["::1/128", "127.0.0.0/8"]
IndexConfigs:
x-omitempty: true
type: "object"
additionalProperties:
$ref: "#/definitions/IndexInfo"
example:
"127.0.0.1:5000":
"Name": "127.0.0.1:5000"
"Mirrors": []
"Secure": false
"Official": false
"[2001:db8:a0b:12f0::1]:80":
"Name": "[2001:db8:a0b:12f0::1]:80"
"Mirrors": []
"Secure": false
"Official": false
"registry.internal.corp.example.com:3000":
Name: "registry.internal.corp.example.com:3000"
Mirrors: []
Secure: false
Official: false
Mirrors:
description: "List of registry URLs that act as a mirror for the official registry."
x-omitempty: true
type: "array"
items:
type: "string"
example:
- "https://hub-mirror.corp.example.com:5000/"
- "https://[2001:db8:a0b:12f0::1]/"
IndexInfo:
description:
IndexInfo contains information about a registry.
type: "object"
x-nullable: true
properties:
Name:
description: |
Name of the registry.
type: "string"
Mirrors:
description: |
List of mirrors, expressed as URIs.
type: "array"
items:
type: "string"
example:
- "https://hub-mirror.corp.example.com:5000/"
Secure:
description: |
Indicates if the the registry is part of the list of insecure
registries.
If `false`, the registry is insecure. Insecure registries accept
un-encrypted (HTTP) and/or untrusted (HTTPS with certificates from
unknown CAs) communication.
> **Warning**: Insecure registries can be useful when running a local
> registry. However, because its use creates security vulnerabilities
> it should ONLY be enabled for testing purposes. For increased
> security, users should add their CA to their system's list of
> trusted CAs instead of enabling this option.
type: "boolean"
example: true
Official:
description: |
Indicates whether this is an official registry.
type: "boolean"
example: true
Runtime:
description: |
Runtime describes an [OCI compliant](https://github.com/opencontainers/runtime-spec)
runtime.
The runtime is invoked by the daemon via the `containerd` daemon. OCI
runtimes act as an interface to the Linux kernel namespaces, cgroups,
and SELinux.
type: "object"
properties:
path:
description: |
Name and, optional, path, of the OCI executable binary.
If the path is omitted, the daemon searches the host's `$PATH` for the
binary and uses the first result.
type: "string"
example: "/usr/local/bin/my-oci-runtime"
runtimeArgs:
description: |
List of command-line arguments to pass to the runtime when invoked.
type: "array"
x-nullable: true
items:
type: "string"
example: ["--debug", "--systemd-cgroup=false"]
Commit:
description: |
Commit holds the Git-commit (SHA1) that a binary was built from, as
reported in the version-string of external tools, such as `containerd`,
or `runC`.
type: "object"
properties:
ID:
description: "Actual commit ID of external tool."
type: "string"
example: "cfb82a876ecc11b5ca0977d1733adbe58599088a"
Expected:
description: |
Commit ID of external tool expected by pouchd as set at build time.
type: "string"
example: "2d41c047c83e09a6d61d464906feb2a2f3c52aa4"
AuthConfig:
type: "object"
properties:
Username:
type: "string"
Password:
type: "string"
Auth:
type: "string"
ServerAddress:
type: "string"
IdentityToken:
type: "string"
description: "IdentityToken is used to authenticate the user and get an access token for the registry"
RegistryToken:
type: "string"
description: "RegistryToken is a bearer token to be sent to a registry"
AuthResponse:
description: "The response returned by login to a registry"
type: "object"
required: [Status]
properties:
Status:
description: "The status of the authentication"
type: "string"
x-nullable: false
IdentityToken:
description: "An opaque token used to authenticate a user after a successful login"
type: "string"
x-nullable: false
ContainerCreateConfig:
description: |
ContainerCreateConfig is used for API "POST /containers/create".
It wraps all kinds of config used in container creation.
It can be used to encode client params in client and unmarshal request body in daemon side.
allOf:
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
NetworkingConfig:
$ref: "#/definitions/NetworkingConfig"
ContainerConfig:
type: "object"
description: "Configuration for a container that is portable between hosts"
required:
- Image
properties:
Hostname:
description: "The hostname to use for the container, as a valid RFC 1123 hostname."
type: "string"
format: hostname
minLength: 1
Domainname:
description: "The domain name to use for the container."
type: "string"
User:
description: "The user that commands are run as inside the container."
type: "string"
AttachStdin:
description: "Whether to attach to `stdin`."
type: "boolean"
x-nullable: false
AttachStdout:
description: "Whether to attach to `stdout`."
type: "boolean"
x-nullable: false
default: true
AttachStderr:
description: "Whether to attach to `stderr`."
type: "boolean"
x-nullable: false
default: true
DisableNetworkFiles:
description: "Whether to generate the network files(/etc/hostname, /etc/hosts and /etc/resolv.conf) for container."
type: "boolean"
x-nullable: false
default: false
ExposedPorts:
description: "An object mapping ports to an empty object in the form:`{<port>/<tcp|udp>: {}}`"
type: "object"
additionalProperties:
type: "object"
enum:
- {}
default: {}
Tty:
description: "Attach standard streams to a TTY, including `stdin` if it is not closed."
type: "boolean"
x-nullable: false
OpenStdin:
description: "Open `stdin`"
type: "boolean"
x-nullable: false
StdinOnce:
description: "Close `stdin` after one attached client disconnects"
type: "boolean"
x-nullable: false
Env:
description: |
A list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.
type: "array"
items:
type: "string"
Cmd:
description: "Command to run specified an array of strings."
type: "array"
items:
type: "string"
ArgsEscaped:
description: "Command is already escaped (Windows only)"
type: "boolean"
x-nullable: false
Image:
description: "The name of the image to use when creating the container"
type: "string"
x-nullable: false
Volumes:
description: "An object mapping mount point paths inside the container to empty objects."
type: "object"
additionalProperties:
type: "object"
enum:
- {}
default: {}
WorkingDir:
description: "The working directory for commands to run in."
type: "string"
Entrypoint:
description: |
The entry point for the container as a string or an array of strings.
If the array consists of exactly one empty string (`[""]`) then the entry point is reset to system default.
type: "array"
items:
type: "string"
NetworkDisabled:
description: "Disable networking for the container."
type: "boolean"
MacAddress:
description: "MAC address of the container."
type: "string"
OnBuild:
description: "`ONBUILD` metadata that were defined."
type: "array"
items:
type: "string"
Labels:
description: "User-defined key/value metadata."
type: "object"
additionalProperties:
type: "string"
StopSignal:
description: "Signal to stop a container as a string or unsigned integer."
type: "string"
default: "SIGTERM"
x-nullable: false
StopTimeout:
description: "Timeout to stop a container in seconds."
type: "integer"
default: 10
Shell:
description: "Shell for when `RUN`, `CMD`, and `ENTRYPOINT` uses a shell."
type: "array"
items:
type: "string"
Rich:
type: "boolean"
description: "Whether to start container in rich container mode. (default false)"
x-nullable: false
RichMode:
type: "string"
description: "Choose one rich container mode.(default dumb-init)"
enum:
- "dumb-init"
- "sbin-init"
- "systemd"
InitScript:
type: "string"
description: "Initial script executed in container. The script will be executed before entrypoint or command"
DiskQuota:
type: "object"
description: "Set disk quota for container"
x-nullable: true
additionalProperties:
type: "string"
SpecAnnotation:
description: "annotations send to runtime spec."
type: "object"
additionalProperties:
type: "string"
QuotaID:
type: "string"
description: "set disk quota by specified quota id, if id < 0, it means pouchd alloc a unique quota id"
ContainerCreateResp:
description: "response returned by daemon when container create successfully"
type: "object"
required: [Id, Warnings]
properties:
Id:
description: "The ID of the created container"
type: "string"
x-nullable: false
Name:
description: "The name of the created container"
type: "string"
Warnings:
description: "Warnings encountered when creating the container"
type: "array"
x-nullable: false
items:
type: "string"
HostConfig:
description: "Container configuration that depends on the host we are running on"
type: "object"
allOf:
- properties:
# Applicable to all platforms
Binds:
type: "array"
description: |
A list of volume bindings for this container. Each volume binding is a string in one of these forms:
- `host-src:container-dest` to bind-mount a host path into the container. Both `host-src`, and `container-dest` must be an _absolute_ path.
- `host-src:container-dest:ro` to make the bind mount read-only inside the container. Both `host-src`, and `container-dest` must be an _absolute_ path.
- `volume-name:container-dest` to bind-mount a volume managed by a volume driver into the container. `container-dest` must be an _absolute_ path.
- `volume-name:container-dest:ro` to mount the volume read-only inside the container. `container-dest` must be an _absolute_ path.
items:
type: "string"
ContainerIDFile:
type: "string"
description: "Path to a file where the container ID is written"
LogConfig:
description: "The logging configuration for this container"
type: "object"
$ref: "#/definitions/LogConfig"
RestartPolicy:
type: "object"
description: "Restart policy to be used to manage the container"
$ref: "#/definitions/RestartPolicy"
NetworkMode:
type: "string"
description: "Network mode to use for this container. Supported standard values are: `bridge`, `host`, `none`, and `container:<name|id>`. Any other value is taken as a custom network's name to which this container should connect to."
PortBindings:
type: "object"
description: "A map of exposed container ports and the host port they should map to."
$ref: "#/definitions/PortMap"
AutoRemove:
type: "boolean"
description: "Automatically remove the container when the container's process exits. This has no effect if `RestartPolicy` is set."
VolumeDriver:
type: "string"
description: "Driver that this container uses to mount volumes."
VolumesFrom:
type: "array"
description: "A list of volumes to inherit from another container, specified in the form `<container name>[:<ro|rw>]`."
items:
type: "string"
CapAdd:
type: "array"
description: "A list of kernel capabilities to add to the container."
items:
type: "string"
CapDrop:
type: "array"
description: "A list of kernel capabilities to drop from the container."
items:
type: "string"
Dns:
type: "array"
description: "A list of DNS servers for the container to use."
items:
type: "string"
DnsOptions:
type: "array"
description: "A list of DNS options."
items:
type: "string"
DnsSearch:
type: "array"
description: "A list of DNS search domains."
items:
type: "string"
ExtraHosts:
type: "array"
description: |
A list of hostnames/IP mappings to add to the container's `/etc/hosts` file. Specified in the form `["hostname:IP"]`.
items:
type: "string"
GroupAdd:
type: "array"
description: "A list of additional groups that the container process will run as."
items:
type: "string"
IpcMode:
type: "string"
description: |
IPC sharing mode for the container. Possible values are:
- `"none"`: own private IPC namespace, with /dev/shm not mounted
- `"private"`: own private IPC namespace
- `"shareable"`: own private IPC namespace, with a possibility to share it with other containers
- `"container:<name|id>"`: join another (shareable) container's IPC namespace
- `"host"`: use the host system's IPC namespace
If not specified, daemon default is used, which can either be `"private"`
or `"shareable"`, depending on daemon version and configuration.
Cgroup:
type: "string"
description: "Cgroup to use for the container."
Links:
type: "array"
description: "A list of links for the container in the form `container_name:alias`."
items:
type: "string"
OomScoreAdj:
type: "integer"
description: |
An integer value containing the score given to the container in order to tune OOM killer preferences.
The range is in [-1000, 1000].
type: "integer"
format: "int"
x-nullable: false
minimum: -1000
maximum: 1000
PidMode:
type: "string"
description: |
Set the PID (Process) Namespace mode for the container. It can be either:
- `"container:<name|id>"`: joins another container's PID namespace
- `"host"`: use the host's PID namespace inside the container
Privileged:
type: "boolean"
description: "Gives the container full access to the host."
PublishAllPorts:
type: "boolean"
description: "Allocates a random host port for all of a container's exposed ports."
ReadonlyRootfs:
type: "boolean"
description: "Mount the container's root filesystem as read only."
SecurityOpt:
type: "array"
description: "A list of string values to customize labels for MLS systems, such as SELinux."
items:
type: "string"
StorageOpt:
type: "object"
description: |
Storage driver options for this container, in the form `{"size": "120G"}`.
additionalProperties:
type: "string"
Tmpfs:
type: "object"
description: |
A map of container directories which should be replaced by tmpfs mounts, and their corresponding mount options. For example: `{ "/run": "rw,noexec,nosuid,size=65536k" }`.
additionalProperties:
type: "string"
UTSMode:
type: "string"
description: "UTS namespace to use for the container."
UsernsMode:
type: "string"
description: "Sets the usernamespace mode for the container when usernamespace remapping option is enabled."
ShmSize:
type: "integer"
description: "Size of `/dev/shm` in bytes. If omitted, the system uses 64MB."
minimum: 0
Sysctls:
type: "object"
description: |
A list of kernel parameters (sysctls) to set in the container. For example: `{"net.ipv4.ip_forward": "1"}`
additionalProperties:
type: "string"
Runtime:
type: "string"
description: "Runtime to use with this container."
# Applicable to Windows
ConsoleSize:
type: "array"
description: "Initial console size, as an `[height, width]` array. (Windows only)"
minItems: 2
maxItems: 2
items:
type: "integer"
minimum: 0
Isolation:
type: "string"
description: "Isolation technology of the container. (Windows only)"
enum:
- "default"
- "process"
- "hyperv"
EnableLxcfs:
description: "Whether to enable lxcfs."
type: "boolean"
x-nullable: false
Rich:
type: "boolean"
description: "Whether to start container in rich container mode. (default false)"
x-nullable: false
RichMode:
type: "string"
description: "Choose one rich container mode.(default dumb-init)"
enum:
- "dumb-init"
- "sbin-init"
- "systemd"
InitScript:
type: "string"
description: "Initial script executed in container. The script will be executed before entrypoint or command"
- $ref: "#/definitions/Resources"
UpdateConfig:
description: "UpdateConfig holds the mutable attributes of a Container. Those attributes can be updated at runtime."
allOf:
- $ref: "#/definitions/Resources"
- properties:
RestartPolicy:
$ref: "#/definitions/RestartPolicy"
Env:
description: |
A list of environment variables to set inside the container in the form `["VAR=value", ...]`. A variable without `=` is removed from the environment, rather than to have an empty value.
type: "array"
items:
type: "string"
Label:
description: "List of labels set to container."
type: "array"
items:
type: "string"
DiskQuota:
type: "object"
description: "update disk quota for container"
x-nullable: true
additionalProperties:
type: "string"
ContainerUpgradeConfig:
description: |
ContainerUpgradeConfig is used for API "POST /containers/upgrade".
It wraps all kinds of config used in container upgrade.
It can be used to encode client params in client and unmarshal request body in daemon side.
allOf:
- $ref: "#/definitions/ContainerConfig"
- type: "object"
properties:
HostConfig:
$ref: "#/definitions/HostConfig"
LogConfig:
description: "The logging configuration for this container"
type: "object"
properties:
Type:
type: "string"
x-go-name: "LogDriver"
enum:
- "json-file"
- "syslog"
- "journald"
- "gelf"
- "fluentd"
- "awslogs"
- "splunk"
- "etwlogs"
- "none"
Config:
type: "object"
x-go-name: "LogOpts"
additionalProperties:
type: "string"
Resources:
description: "A container's resources (cgroups config, ulimits, etc)"
type: "object"
required: [CPUShares, Memory, CgroupParent, BlkioWeight, CPUPeriod, CPUQuota, CpuRealtimePeriod,
CpuRealtimeRuntime, CpusetCpus, CpusetMems, DeviceCgroupRules, KernelMemory, MemoryReservation,
MemorySwap, MemorySwappiness, NanoCPUs, OomKillDisable, PidsLimit, CpuCount, CpuPercent,
IOMaximumIOps, IOMaximumBandwidth, IntelRdtL3Cbm, ScheLatSwitch, MemoryWmarkRatio, MemoryExtra,
MemoryForceEmptyCtl]
properties:
# Applicable to UNIX platforms
CgroupParent:
description: "Path to `cgroups` under which the container's `cgroup` is created. If the path is not absolute, the path is considered to be relative to the `cgroups` path of the init process. Cgroups are created if they do not already exist."
type: "string"
x-nullable: false
BlkioWeight:
description: "Block IO weight (relative weight), need CFQ IO Scheduler enable."
type: "integer"
format: "uint16"
x-nullable: false
minimum: 0
maximum: 1000
BlkioWeightDevice:
description: |
Block IO weight (relative device weight) in the form `[{"Path": "device_path", "Weight": weight}]`.
type: "array"
items:
$ref: "#/definitions/WeightDevice"
BlkioDeviceReadBps:
description: |
Limit read rate (bytes per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
type: "array"
items:
$ref: "#/definitions/ThrottleDevice"
BlkioDeviceWriteBps:
description: |
Limit write rate (bytes per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
type: "array"
items:
$ref: "#/definitions/ThrottleDevice"
BlkioDeviceReadIOps:
description: |
Limit read rate (IO per second) from a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
type: "array"
items:
$ref: "#/definitions/ThrottleDevice"
BlkioDeviceWriteIOps:
description: |
Limit write rate (IO per second) to a device, in the form `[{"Path": "device_path", "Rate": rate}]`.
type: "array"
items:
$ref: "#/definitions/ThrottleDevice"
CPUShares:
description: "An integer value representing this container's relative CPU weight versus other containers."
type: "integer"
x-nullable: false
CPUPeriod:
description: |
CPU CFS (Completely Fair Scheduler) period.
The length of a CPU period in microseconds.
type: "integer"
format: "int64"
minimum: 1000
maximum: 1000000
x-nullable: false
CPUQuota:
description: |
CPU CFS (Completely Fair Scheduler) quota.
Microseconds of CPU time that the container can get in a CPU period."
type: "integer"
format: "int64"
minimum: 1000
x-nullable: false
CpuRealtimePeriod:
description: "The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks."
type: "integer"
format: "int64"
x-nullable: false
CpuRealtimeRuntime:
description: "The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks."
type: "integer"
format: "int64"
x-nullable: false
CpusetCpus:
description: "CPUs in which to allow execution (e.g., `0-3`, `0,1`)"
type: "string"
example: "0-3"
x-nullable: false
CpusetMems:
description: "Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems."
type: "string"
x-nullable: false
Devices:
description: "A list of devices to add to the container."
type: "array"
items:
$ref: "#/definitions/DeviceMapping"
DeviceCgroupRules:
description: "a list of cgroup rules to apply to the container"
type: "array"
items:
type: "string"
example: "c 13:* rwm"
KernelMemory:
description: "Kernel memory limit in bytes."
type: "integer"
format: "int64"
x-nullable: false
Memory:
description: "Memory limit in bytes."
type: "integer"
default: 0
x-nullable: false
MemoryReservation:
description: "Memory soft limit in bytes."
type: "integer"
format: "int64"
x-nullable: false
MemorySwap:
description: "Total memory limit (memory + swap). Set as `-1` to enable unlimited swap."
type: "integer"
format: "int64"
x-nullable: false
MemorySwappiness:
description: "Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100."
type: "integer"
format: "int64"
minimum: 0
maximum: 100
NanoCPUs:
description: "CPU quota in units of 10<sup>-9</sup> CPUs."
type: "integer"
format: "int64"
x-nullable: false
OomKillDisable:
description: "Disable OOM Killer for the container."
type: "boolean"
x-nullable: true
PidsLimit:
description: |
Tune a container's pids limit. Set -1 for unlimited. Only on Linux 4.4 does this parameter support.
type: "integer"
format: "int64"
x-nullable: false
Ulimits:
description: |
A list of resource limits to set in the container. For example: `{"Name": "nofile", "Soft": 1024, "Hard": 2048}`"
type: "array"
items:
$ref: "#/definitions/Ulimit"
# Applicable to Windows
CpuCount:
description: |
The number of usable CPUs (Windows only).
On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.
type: "integer"
format: "int64"
x-nullable: false
CpuPercent:
description: |
The usable percentage of the available CPUs (Windows only).
On Windows Server containers, the processor resource controls are mutually exclusive. The order of precedence is `CPUCount` first, then `CPUShares`, and `CPUPercent` last.
type: "integer"
format: "int64"
x-nullable: false
IOMaximumIOps:
description: "Maximum IOps for the container system drive (Windows only)"
type: "integer"
format: "uint64"
x-nullable: false
IOMaximumBandwidth:
description: "Maximum IO in bytes per second for the container system drive (Windows only)"
type: "integer"
format: "uint64"
x-nullable: false
IntelRdtL3Cbm:
description: "IntelRdtL3Cbm specifies settings for Intel RDT/CAT group that the container is placed into to limit the resources (e.g., L3 cache) the container has available."
type: "string"
x-nullable: false
# applicable to AliKenerl 4.9
ScheLatSwitch:
description: "ScheLatSwitch enables scheduler latency count in cpuacct"
type: "integer"
format: "int64"
x-nullable: false
minimum: 0
maximum: 1
x-nullable: false
MemoryWmarkRatio:
description: |
MemoryWmarkRatio is an integer value representing this container's memory low water mark percentage.
The value of memory low water mark is memory.limit_in_bytes * MemoryWmarkRatio. The range is in [0, 100].
type: "integer"
format: "int64"
x-nullable: true
minimum: 0
maximum: 100
MemoryExtra:
description: |
MemoryExtra is an integer value representing this container's memory high water mark percentage.
The range is in [0, 100].
type: "integer"
format: "int64"
x-nullable: true
minimum: 0
maximum: 100
MemoryForceEmptyCtl:
description: "MemoryForceEmptyCtl represents whether to reclaim the page cache when deleting cgroup."
type: "integer"
format: "int64"
x-nullable: false
minimum: 0
maximum: 1
ThrottleDevice:
type: "object"
properties:
Path:
description: "Device path"
type: "string"
Rate:
description: "Rate"
type: "integer"
format: "uint64"
x-nullable: false
minimum: 0
WeightDevice:
type: "object"
description: "Weight for BlockIO Device"
properties:
Path:
description: "Weight Device"
type: "string"
Weight:
type: "integer"
format: "uint16"
x-nullable: false
minimum: 0
DeviceMapping:
type: "object"
description: "A device mapping between the host and container"
properties:
PathOnHost:
description: "path on host of the device mapping"
type: "string"
PathInContainer:
description: "path in container of the device mapping"
type: "string"
CgroupPermissions:
description: "cgroup permissions of the device"
type: "string"
example:
PathOnHost: "/dev/deviceName"
PathInContainer: "/dev/deviceName"
CgroupPermissions: "mrw"
Ulimit:
type: "object"
description: "A list of resource limits"
properties:
Name:
description: "Name of ulimit"
type: "string"
Soft:
description: "Soft limit"
type: "integer"
Hard:
description: "Hard limit"
type: "integer"
Container:
description: |
an array of Container contains response of Engine API:
GET "/containers/json"
type: "object"
properties:
Id:
description: "Container ID"
type: "string"
Names:
type: "array"
items:
type: "string"
example:
- "container_1"
- "container_2"
Image:
type: "string"
ImageID:
type: "string"
Command:
type: "string"
Created:
description: "Created time of container in daemon."
type: "integer"
format: "int64"
SizeRw:
type: "integer"
format: "int64"
SizeRootFs:
type: "integer"
format: "int64"
Labels:
type: "object"
additionalProperties:
type: "string"
State:
type: "string"
Status:
type: "string"
HostConfig:
description: |
In Moby's API, HostConfig field in Container struct has following type
struct { NetworkMode string `json:",omitempty"` }
In Pouch, we need to pick runtime field in HostConfig from daemon side to judge runtime type,
So Pouch changes this type to be the complete HostConfig.
Incompatibility exists, ATTENTION.
$ref: "#/definitions/HostConfig"
x-nullable: false
Mounts:
type: "array"
description: "Set of mount point in a container."
items:
$ref: "#/definitions/MountPoint"
NetworkSettings:
type: "object"
properties:
Networks:
additionalProperties:
$ref: "#/definitions/EndpointSettings"
x-nullable: true
NetworkingConfig:
description: "Configuration for a network used to create a container."
type: "object"
properties:
EndpointsConfig:
additionalProperties:
$ref: "#/definitions/EndpointSettings"
x-nullable: true
EndpointSettings:
description: "Configuration for a network endpoint."
type: "object"
properties:
# Configurations
IPAMConfig:
$ref: "#/definitions/EndpointIPAMConfig"
x-nullable: true
Links:
type: "array"
items:
type: "string"
example:
- "container_1"
- "container_2"
Aliases:
type: "array"
items:
type: "string"
example:
- "server_x"
- "server_y"
# Operational data
NetworkID:
description: |
Unique ID of the network.
type: "string"
example: "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"
EndpointID:
description: |
Unique ID for the service endpoint in a Sandbox.
type: "string"
example: "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"
Gateway:
description: |
Gateway address for this network.
type: "string"
example: "172.17.0.1"
IPAddress:
description: |
IPv4 address.
type: "string"
example: "172.17.0.4"
IPPrefixLen:
description: |
Mask length of the IPv4 address.
type: "integer"
example: 16
IPv6Gateway:
description: |
IPv6 gateway address.
type: "string"
example: "2001:db8:2::100"
GlobalIPv6Address:
description: |
Global IPv6 address.
type: "string"
example: "2001:db8::5689"
GlobalIPv6PrefixLen:
description: |
Mask length of the global IPv6 address.
type: "integer"
format: "int64"
example: 64
MacAddress:
description: |
MAC address for the endpoint on this network.
type: "string"
example: "02:42:ac:11:00:04"
DriverOpts:
description: |
DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
EndpointIPAMConfig:
description: "IPAM configurations for the endpoint"
type: "object"
properties:
IPv4Address:
description: "ipv4 address"
type: "string"
IPv6Address:
description: "ipv6 address"
type: "string"
LinkLocalIPs:
description: "link to the list of local ip"
type: "array"
x-nullable: false
items:
type: "string"
NetworkDisconnect:
description: "Parameters of network disconnect"
type: "object"
properties:
Container:
type: "string"
description: "The ID or name of the container to disconnect from the network."
Force:
type: "boolean"
description: "Force the container to disconnect from the network."
ImageInfo:
description: "An object containing all details of an image at API side"
type: "object"
properties:
Id:
description: "ID of an image."
type: "string"
x-nullable: false
RepoTags:
description: "repository with tag."
type: "array"
items:
type: "string"
RepoDigests:
description: "repository with digest."
type: "array"
items:
type: "string"
CreatedAt:
description: "time of image creation."
type: "string"
x-nullable: false
Size:
description: "size of image's taking disk space."
type: "integer"
x-nullable: false
Config:
$ref: "#/definitions/ContainerConfig"
Architecture:
description: "the CPU architecture."
type: "string"
x-nullable: false
Os:
description: "the name of the operating system."
type: "string"
x-nullable: false
RootFS:
description: "the rootfs key references the layer content addresses used by the image."
type: "object"
required: [Type]
properties:
Type:
description: "type of the rootfs"
type: "string"
x-nullable: false
Layers:
description: "an array of layer content hashes"
type: "array"
items:
type: "string"
BaseLayer:
description: "the base layer content hash."
type: "string"
SearchResultItem:
type: "object"
description: "search result item in search results."
properties:
description:
type: "string"
description: "description just shows the description of this image"
is_official:
type: "boolean"
description: "is_official shows if this image is marked official."
is_automated:
type: "boolean"
description: "is_automated means whether this image is automated."
name:
type: "string"
description: "name represents the name of this image"
star_count:
type: "integer"
description: "star_count refers to the star count of this image."
VolumeInfo:
type: "object"
description: "Volume represents the configuration of a volume for the container."
properties:
Name:
description: "Name is the name of the volume."
type: "string"
Driver:
description: "Driver is the Driver name used to create the volume."
type: "string"
Mountpoint:
description: "Mountpoint is the location on disk of the volume."
type: "string"
CreatedAt:
type: "string"
format: "dateTime"
description: "Date/Time the volume was created."
Status:
description: "Status provides low-level status information about the volume."
type: "object"
additionalProperties:
type: "object"
enum:
- {}
default: {}
Labels:
description: "Labels is metadata specific to the volume."
type: "object"
additionalProperties:
type: "string"
Scope:
description: |
Scope describes the level at which the volume exists
(e.g. `global` for cluster-wide or `local` for machine level)
type: "string"
VolumeCreateConfig:
description: "config used to create a volume"
type: "object"
properties:
Name:
description: "The new volume's name. If not specified, Pouch generates a name."
type: "string"
x-nullable: false
Driver:
description: "Name of the volume driver to use."
type: "string"
default: "local"
x-nullable: false
DriverOpts:
description: "A mapping of driver options and values. These options are passed directly to the driver and are driver specific."
type: "object"
additionalProperties:
type: "string"
Labels:
description: "User-defined key/value metadata."
type: "object"
additionalProperties:
type: "string"
example:
Name: "tardis"
Labels:
com.example.some-label: "some-value"
com.example.some-other-label: "some-other-value"
Driver: "custom"
VolumeListResp:
type: "object"
required: [Volumes, Warnings]
properties:
Volumes:
type: "array"
x-nullable: false
description: "List of volumes"
items:
$ref: "#/definitions/VolumeInfo"
Warnings:
type: "array"
x-nullable: false
description: "Warnings that occurred when fetching the list of volumes"
items:
type: "string"
ExecCreateConfig:
type: "object"
description: is a small subset of the Config struct that holds the configuration.
properties:
User:
type: "string"
description: "User that will run the command"
x-nullable: false
Privileged:
type: "boolean"
description: "Is the container in privileged mode"
Tty:
type: "boolean"
description: "Attach standard streams to a tty"
AttachStdin:
type: "boolean"
description: "Attach the standard input, makes possible user interaction"
AttachStderr:
type: "boolean"
description: "Attach the standard error"
AttachStdout:
type: "boolean"
description: "Attach the standard output"
Detach:
type: "boolean"
description: "Execute in detach mode"
DetachKeys:
type: "string"
description: "Escape keys for detach"
Cmd:
type: "array"
description: "Execution commands and args"
minItems: 1
items:
type: "string"
ContainerProcessList:
description: OK Response to ContainerTop operation
type: "object"
properties:
Titles:
description: "The ps column titles"
type: "array"
items:
type: "string"
Processes:
description: "Each process running in the container, where each is process is an array of values corresponding to the titles"
type: "array"
items:
type: "array"
items:
type: "string"
ExecCreateResp:
type: "object"
description: contains response of Remote API POST "/containers/{name:.*}/exec".
properties:
Id:
type: "string"
description: ID is the exec ID
ExecStartConfig:
type: "object"
description: ExecStartConfig is a temp struct used by execStart.
properties:
Detach:
description: ExecStart will first check if it's detached
type: "boolean"
Tty:
description: Check if there's a tty
type: "boolean"
example:
Detach: false
Tty: false
ContainerExecInspect:
type: "object"
description: holds information about a running process started.
required: [ID, Running, ExitCode, ProcessConfig, OpenStdin, OpenStderr, OpenStdout, CanRemove, ContainerID, DetachKeys]
properties:
ID:
x-nullable: false
type: "string"
description: "The ID of this exec"
Running:
x-nullable: false
type: "boolean"
ExitCode:
x-nullable: false
type: "integer"
description: "The last exit code of this container"
ProcessConfig:
x-nullable: false
$ref: "#/definitions/ProcessConfig"
OpenStdin:
x-nullable: false
type: "boolean"
OpenStderr:
x-nullable: false
type: "boolean"
OpenStdout:
x-nullable: false
type: "boolean"
CanRemove:
x-nullable: false
type: "boolean"
ContainerID:
x-nullable: false
type: "string"
description: "The ID of this container"
DetachKeys:
x-nullable: false
type: "string"
ProcessConfig:
type: "object"
description: ExecProcessConfig holds information about the exec process.
required: [privileged, user, tty, entrypoint, arguments]
properties:
privileged:
x-nullable: false
type: "boolean"
user:
x-nullable: false
type: "string"
tty:
x-nullable: false
type: "boolean"
entrypoint:
x-nullable: false
type: "string"
arguments:
x-nullable: false
type: "array"
items:
type: "string"
ContainerJSON:
description: |
ContainerJSON contains response of Engine API:
GET "/containers/{id}/json"
type: "object"
properties:
Id:
description: "The ID of the container"
type: "string"
Created:
description: "The time the container was created"
type: "string"
Path:
description: "The path to the command being run"
type: "string"
Args:
description: "The arguments to the command being run"
type: "array"
items:
type: "string"
State:
description: "The state of the container."
$ref: "#/definitions/ContainerState"
Image:
description: "The container's image"
type: "string"
ResolvConfPath:
type: "string"
HostnamePath:
type: "string"
HostsPath:
type: "string"
LogPath:
type: "string"
Name:
type: "string"
RestartCount:
type: "integer"
Driver:
type: "string"
MountLabel:
type: "string"
ProcessLabel:
type: "string"
AppArmorProfile:
type: "string"
ExecIDs:
description: "exec ids of container"
type: "array"
items:
type: "string"
HostConfig:
$ref: "#/definitions/HostConfig"
SizeRw:
description: "The size of files that have been created or changed by this container."
type: "integer"
format: "int64"
x-nullable: true
SizeRootFs:
description: "The total size of all the files in this container."
type: "integer"
format: "int64"
x-nullable: true
Config:
$ref: "#/definitions/ContainerConfig"
Snapshotter:
$ref: "#/definitions/SnapshotterData"
GraphDriver:
$ref: "#/definitions/GraphDriverData"
Mounts:
type: "array"
description: "Set of mount point in a container."
items:
$ref: "#/definitions/MountPoint"
NetworkSettings:
description: "NetworkSettings exposes the network settings in the API."
$ref: "#/definitions/NetworkSettings"
ContainerState:
type: "object"
required: [StartedAt, FinishedAt]
properties:
Status:
$ref: "#/definitions/Status"
Running:
description: |
Whether this container is running.
Note that a running container can be _paused_. The `Running` and `Paused`
booleans are not mutually exclusive:
When pausing a container (on Linux), the cgroups freezer is used to suspend
all processes in the container. Freezing the process requires the process to
be running. As a result, paused containers are both `Running` _and_ `Paused`.
Use the `Status` field instead to determine if a container's state is "running".
type: "boolean"
Paused:
description: "Whether this container is paused."
type: "boolean"
Restarting:
description: "Whether this container is restarting."
type: "boolean"
OOMKilled:
description: "Whether this container has been killed because it ran out of memory."
type: "boolean"
Dead:
description: "Whether this container is dead."
type: "boolean"
Pid:
description: "The process ID of this container"
type: "integer"
ExitCode:
description: "The last exit code of this container"
type: "integer"
Error:
description: "The error message of this container"
type: "string"
StartedAt:
description: "The time when this container was last started."
type: "string"
x-nullable: false
FinishedAt:
description: "The time when this container last exited."
type: "string"
x-nullable: false
ContainerLogsOptions:
type: "object"
properties:
ShowStdout:
description: "Return logs from `stdout`"
type: "boolean"
ShowStderr:
description: "Return logs from `stderr`"
type: "boolean"
Since:
description: "Only return logs after this time, as a UNIX timestamp"
type: "string"
Until:
description: "Only reture logs before this time, as a UNIX timestamp"
type: "string"
Timestamps:
description: "Add timestamps to every log line"
type: "boolean"
Follow:
description: "Return logs as a stream"
type: "boolean"
Tail:
description: "Only reture this number of log lines from the end of the logs. Specify as an integer or `all` to output all log lines."
type: "string"
Details:
description: "Show extra details provided to logs"
type: "boolean"
description: The parameters to filter the log.
Status:
description: The status of the container. For example, "running" or "exited".
type: "string"
enum: ["created", "running", "stopped", "paused", "restarting", "removing", "exited", "dead"]
SnapshotterData:
description: "Information about a container's snapshotter."
type: "object"
required: [Name, Data]
properties:
Name:
type: "string"
x-nullable: false
Data:
type: "object"
x-nullable: false
additionalProperties:
type: "string"
GraphDriverData:
description: "Information about a container's graph driver."
type: "object"
required: [Name, Data]
properties:
Name:
type: "string"
x-nullable: false
Data:
type: "object"
x-nullable: false
additionalProperties:
type: "string"
MountPoint:
type: "object"
description: "A mount point inside a container"
x-nullable: false
properties:
Type:
type: "string"
ID:
type: "string"
Name:
type: "string"
Source:
type: "string"
Destination:
type: "string"
Driver:
type: "string"
Mode:
type: "string"
RW:
type: "boolean"
CopyData:
type: "boolean"
Named:
type: "boolean"
Replace:
type: "string"
Propagation:
type: "string"
NetworkSettings:
description: "NetworkSettings exposes the network settings in the API."
type: "object"
properties:
Bridge:
description: Name of the network'a bridge (for example, `pouch-br`).
type: "string"
example: "pouch-br"
SandboxID:
description: SandboxID uniquely represents a container's network stack.
type: "string"
example: "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3"
HairpinMode:
description: "Indicates if hairpin NAT should be enabled on the virtual interface"
type: "boolean"
example: false
LinkLocalIPv6Address:
description: "IPv6 unicast address using the link-local prefix"
type: "string"
example: "fe80::42:acff:fe11:1"
LinkLocalIPv6PrefixLen:
description: Prefix length of the IPv6 unicast address.
type: "integer"
example: "64"
Ports:
$ref: "#/definitions/PortMap"
SandboxKey:
description: SandboxKey identifies the sandbox
type: "string"
example: "/var/run/pouch/netns/8ab54b426c38"
# TODO is SecondaryIPAddresses actually used?
SecondaryIPAddresses:
description: ""
type: "array"
items:
$ref: "#/definitions/IPAddress"
x-nullable: true
# TODO is SecondaryIPv6Addresses actually used?
SecondaryIPv6Addresses:
description: ""
type: "array"
items:
$ref: "#/definitions/IPAddress"
x-nullable: true
Networks:
description: "Information about all networks that the container is connected to"
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointSettings"
x-nullable: true
IPAddress:
description: Address represents an IPv4 or IPv6 IP address.
type: "object"
properties:
Addr:
description: IP address.
type: "string"
PrefixLen:
description: Mask length of the IP address.
type: "integer"
PortMap:
description: |
PortMap describes the mapping of container ports to host ports, using the
container's port-number and protocol as key in the format `<port>/<protocol>`,
for example, `80/udp`.
If a container's port is mapped for both `tcp` and `udp`, two separate
entries are added to the mapping table.
type: "object"
additionalProperties:
type: "array"
items:
$ref: "#/definitions/PortBinding"
example:
"443/tcp":
- HostIp: "127.0.0.1"
HostPort: "4443"
"80/tcp":
- HostIp: "0.0.0.0"
HostPort: "80"
- HostIp: "0.0.0.0"
HostPort: "8080"
"80/udp":
- HostIp: "0.0.0.0"
HostPort: "80"
"2377/tcp": null
PortBinding:
description: "PortBinding represents a binding between a host IP address and a host port"
type: "object"
x-nullable: true
properties:
HostIp:
description: "Host IP address that the container's port is mapped to."
type: "string"
example: "127.0.0.1"
HostPort:
description: "Host port number that the container's port is mapped to."
type: "string"
example: "4443"
RestartPolicy:
description: "Define container's restart policy"
type: "object"
properties:
Name:
type: "string"
MaximumRetryCount:
type: "integer"
NetworkConnect:
type: "object"
description: "contains the request for the remote API: POST /networks/{id:.*}/connect"
properties:
Container:
type: "string"
description: "The ID or name of the container to connect to the network."
EndpointConfig:
$ref: "#/definitions/EndpointSettings"
NetworkCreateConfig:
type: "object"
description: "contains the request for the remote API: POST /networks/create"
allOf:
- properties:
Name:
description: "Name is the name of the network."
type: "string"
- $ref: "#/definitions/NetworkCreate"
NetworkCreateResp:
type: "object"
description: "contains the response for the remote API: POST /networks/create"
properties:
Id:
description: "ID is the id of the network."
type: "string"
Warning:
description: "Warning means the message of create network result."
type: "string"
NetworkCreate:
type: "object"
description: "is the expected body of the \"create network\" http request message"
properties:
CheckDuplicate:
type: "boolean"
description: "CheckDuplicate is used to check the network is duplicate or not."
Driver:
type: "string"
description: "Driver means the network's driver."
EnableIPv6:
type: "boolean"
IPAM:
type: "object"
$ref: "#/definitions/IPAM"
Internal:
type: "boolean"
description: "Internal checks the network is internal network or not."
Options:
type: "object"
additionalProperties:
type: "string"
Labels:
type: "object"
additionalProperties:
type: "string"
NetworkInspectResp:
type: "object"
description: "is the expected body of the 'GET networks/{id}'' http request message"
properties:
Name:
type: "string"
description: "Name is the requested name of the network"
Id:
type: "string"
description: "ID uniquely identifies a network on a single machine"
Scope:
type: "string"
description: "Scope describes the level at which the network exists."
Driver:
type: "string"
description: "Driver means the network's driver."
EnableIPv6:
type: "boolean"
description: "EnableIPv6 represents whether to enable IPv6."
IPAM:
type: "object"
description: "IPAM is the network's IP Address Management."
$ref: "#/definitions/IPAM"
Internal:
type: "boolean"
description: "Internal checks the network is internal network or not."
Options:
type: "object"
description: "Options holds the network specific options to use for when creating the network."
additionalProperties:
type: "string"
Labels:
type: "object"
description: "Labels holds metadata specific to the network being created."
additionalProperties:
type: "string"
NetworkResource:
type: "object"
description: "NetworkResource is the body of the \"get network\" http response message"
properties:
Name:
description: "Name is the requested name of the network"
type: "string"
Id:
description: "ID uniquely identifies a network on a single machine"
type: "string"
Scope:
description: "Scope describes the level at which the network exists (e.g. `global` for cluster-wide or `local` for machine level)"
type: "string"
Driver:
description: "Driver is the Driver name used to create the network (e.g. `bridge`, `overlay`)"
type: "string"
EnableIPv6:
description: "EnableIPv6 represents whether to enable IPv6"
type: "boolean"
IPAM:
description: ""
type: "object"
$ref: "#/definitions/IPAM"
Internal:
description: "Internal represents if the network is used internal only"
type: "boolean"
Containers:
description: "Containers contains endpoints belonging to the network"
type: "object"
IndexConfigs:
type: "object"
additionalProperties:
$ref: "#/definitions/EndpointResource"
Options:
description: "Options holds the network specific options to use for when creating the network"
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-options: "some-option"
com.example.some-other-options: "some-other-option"
Labels:
description: "Labels holds metadata specific to the network being created"
type: "object"
x-nullable: true
additionalProperties:
type: "string"
example:
com.example.some-label: "some-label"
com.example.some-other-label: "some-other-label"
EndpointResource:
type: "object"
description: "NetworkResource is the body of the \"get network\" http response message"
properties:
Name:
description: "Name is the requested name of the network"
type: "string"
EndpointID:
description: "EndpointID represents the endpoint's id"
type: "string"
MacAddress:
description: "MacAddress represents the enpoint's mac address"
type: "string"
IPv4Address:
description: "IPv4Address represents the enpoint's ipv4 address"
type: "string"
IPv6Address:
description: "IPv4Address represents the enpoint's ipv6 address"
type: "string"
IPAM:
type: "object"
description: "represents IP Address Management"
properties:
Driver:
type: "string"
Options:
type: "object"
additionalProperties:
type: "string"
Config:
type: "array"
items:
$ref: '#/definitions/IPAMConfig'
IPAMConfig:
description: "represents IPAM configurations"
type: "object"
x-nullable: false
properties:
Subnet:
description: "subnet address for network"
type: "string"
IPRange:
description: "sub ip range in sub-network"
type: "string"
Gateway:
description: "gateway for sub-network"
type: "string"
AuxAddress:
description: "aux address in sub-network"
type: "object"
additionalProperties:
type: "string"
ResizeOptions:
description: "options of resizing container tty size"
type: "object"
properties:
Height:
type: "integer"
Width:
type: "integer"
ContainerRemoveOptions:
description: "options of remove container"
type: "object"
properties:
Force:
type: "boolean"
Volumes:
type: "boolean"
Link:
type: "boolean"
ContainerListOptions:
description: |
options of list container, filters (a `map[string][]string`) to process on the container list. Available filters:
- `id=container-id`
- `name=container-name`
- `status=running`
- `label=key` or `label=key=value`
- `network=container-network`
- `volume=volume-id`
type: "object"
properties:
All:
type: "boolean"
Since:
type: "string"
Before:
type: "string"
Limit:
type: "integer"
Filter:
type: "object"
additionalProperties:
type: "array"
items:
type: "string"
parameters:
id:
name: id
in: path
required: true
description: ID or name of the container
type: string
imageid:
name: imageid
in: path
required: true
description: Image name or id
type: string
responses:
401ErrorResponse:
description: An unexpected 401 error occurred.
schema:
$ref: "#/definitions/Error"
404ErrorResponse:
description: An unexpected 404 error occurred.
schema:
$ref: "#/definitions/Error"
500ErrorResponse:
description: An unexpected server error occurred.
schema:
$ref: "#/definitions/Error"