Skip to content

HTTP_API.md

Latest commit

 

History

History
1802 lines (1237 loc) · 62.7 KB

HTTP_API.md

File metadata and controls

1802 lines (1237 loc) · 62.7 KB

Pouch Engine API

Overview

API is an HTTP API served by Pouch Engine.

Version information

Version : 1.24

URI scheme

BasePath : /v1.24
Schemes : HTTP, HTTPS

Consumes

  • application/json
  • text/plain

Produces

  • application/json

Paths

GET /_ping

Responses

HTTP Code Description Schema
200 no error string
500 An unexpected server error occured. Error

Example HTTP response

Response 200
json :
"OK"

Create a container

POST /containers/create

Parameters

Type Name Description Schema
Query name
optional		 Assign the specified name to the container. Must match /?[a-zA-Z0-9_-]+. string
Body body
required		 Container to create ContainerCreateConfig

Responses

HTTP Code Description Schema
201 Container created successfully ContainerCreateResp
400 bad parameter Error
404 no such image Error
409 conflict Error
500 An unexpected server error occured. Error

Consumes

  • application/json

Produces

  • application/json

Tags

  • Container

Example HTTP response

Response 201
json :
{
  "Id" : "e90e34656806",
  "Warnings" : [ ]
}
Response 404
json :
{
  "message" : "image: xxx:latest: not found"
}

List containers

GET /containers/json

Parameters

Type Name Description Schema Default
Query all
optional		 Return all containers. By default, only running containers are shown boolean "false"

Responses

HTTP Code Description Schema
200 Summary containers that matches the query < Container > array
500 An unexpected server error occured. Error

Produces

  • application/json

Remove one container

DELETE /containers/{id}

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Query force
optional		 If the container is running, force query is used to kill it and remove it forcefully. boolean

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Container

Attach to a container

POST /containers/{id}/attach

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 Docker 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 Docker 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, 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:

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, 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.

Parameters

Type Name Description Schema Default
Path id
required		 ID or name of the container string
Query detachKeys
optional		 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 _. string
Query logs
optional		 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.		 boolean "false"
Query stderr
optional		 Attach to stderr boolean "false"
Query stdin
optional		 Attach to stdin boolean "false"
Query stdout
optional		 Attach to stdout boolean "false"
Query stream
optional		 Stream attached streams from the time the request was made onwards boolean "false"

Responses

HTTP Code Description Schema
101 no error, hints proxy about hijacking No Content
200 no error, no upgrade header found No Content
400 bad parameter Error
404 no such container Error
500 server error Error

Produces

  • application/vnd.raw-stream

Tags

  • Container

Example HTTP response

Response 404
json :
{
  "message" : "No such container: c2ada9df5af8"
}

Create an exec instance

POST /containers/{id}/exec

Description

Run a command inside a running container.

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Body body
required		 ExecCreateConfig

Responses

HTTP Code Description Schema
201 no error ExecCreateResp
404 An unexpected 404 error occured. Error
409 container is paused Error
500 An unexpected server error occured. Error

Consumes

  • application/json

Produces

  • application/json

Tags

  • Exec

Inspect a container

GET /containers/{id}/json

Description

Return low-level information about a container.

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Query size
optional		 Return the size of container as fields SizeRw and SizeRootFs boolean

Responses

HTTP Code Description Schema
200 no error ContainerJSON
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Produces

  • application/json

Tags

  • Container

Pause a container

POST /containers/{id}/pause

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Container

Rename a container

POST /containers/{id}/rename

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Query name
required		 New name for the container string

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
409 name already in use Error
500 An unexpected server error occured. Error

Tags

  • Container

Start a container

POST /containers/{id}/start

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Query detachKeys
optional		 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 _. string

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Container

Stop a container

POST /containers/{id}/stop

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string
Query t
optional		 Number of seconds to wait before killing the container integer

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Container

Unpause a container

POST /containers/{id}/unpause

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
204 no error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Container

Start an exec instance

POST /exec/{id}/start

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.

Parameters

Type Name Description Schema
Path id
required		 Exec instance ID string
Body execStartConfig
optional		 ExecStartConfig

Responses

HTTP Code Description Schema
200 No error No Content
404 No such exec instance Error
409 Container is stopped or paused Error

Consumes

  • application/json

Produces

  • application/vnd.raw-stream

Tags

  • Exec

Example HTTP request

Request body
json :
{
  "Detach" : false,
  "Tty" : false
}

Create an image by pulling from a registry or importing from an existing source file

POST /images/create

Parameters

Type Name Description Schema
Header X-Registry-Auth
optional		 A base64-encoded auth configuration. See the authentication section for details. string
Query fromImage
optional		 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. string
Query fromSrc
optional		 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. string
Query repo
optional		 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. string
Query tag
optional		 Tag or digest. If empty when pulling an image, this causes all tags for the given image to be pulled. string
Body inputImage
optional		 Image content if the value - has been specified in fromSrc query parameter string

Responses

HTTP Code Description Schema
200 no error No Content
404 image not found Error
500 An unexpected server error occured. Error

Consumes

  • text/plain
  • application/octet-stream

Produces

  • application/json

List Images

GET /images/json

Description

Return a list of stored images.

Parameters

Type Name Description Schema
Query all
optional		 Show all images. Only images from a final layer (no children) are shown by default. boolean
Query digests
optional		 Show digest information as a RepoDigests field on each image. boolean
Query filters
optional		 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>)		 string

Responses

HTTP Code Description Schema
200 Summary image data for the images matching the query < ImageInfo > array
500 An unexpected server error occured. Error

Produces

  • application/json

Example HTTP response

Response 200
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
} ]

Search images

GET /images/search

Responses

HTTP Code Description Schema
200 No error < SearchResultItem > array
500 An unexpected server error occured. Error

Produces

  • application/json

Remove an image

DELETE /images/{imageid}

Description

Remove an image by reference.

Parameters

Type Name Description Schema Default
Path imageid
required		 Image name or id string
Query force
optional		 Remove the image even if it is being used boolean "false"

Responses

HTTP Code Description Schema
204 No error No Content
404 no such image Error
500 An unexpected server error occured. Error

Example HTTP response

Response 404
json :
{
  "message" : "No such image: c2ada9df5af8"
}

Inspect a image

GET /images/{imageid}/json

Description

Return the information about image

Parameters

Type Name Description Schema
Path imageid
required		 Image name or id string

Responses

HTTP Code Description Schema
200 no error ImageInfo
404 no such image Error
500 An unexpected server error occured. Error

Produces

  • application/json

Example HTTP response

Response 200
json :
{
  "CreatedAt" : "2017-12-19 15:32:09",
  "Digest" : "sha256:e216a057b1cb1efc11f8a268f37ef62083e70b1b38323ba252e25ac88904a7e8",
  "ID" : "e216a057b1cb",
  "Name" : "ubuntu:12.04",
  "Size" : 103579269,
  "Tag" : "12.04"
}
Response 404
json :
{
  "message" : "No such image: e216a057b1cb"
}

Get System information

GET /info

Responses

HTTP Code Description Schema
200 no error SystemInfo
500 An unexpected server error occured. Error

Create a network

POST /networks/create

Parameters

Type Name Description Schema
Body NetworkCreateConfig
required		 Network configuration NetworkCreateConfig

Responses

HTTP Code Description Schema
201 The network was created successfully NetworkCreateResp
400 bad parameter Error
500 An unexpected server error occured. Error

Consumes

  • application/json

Produces

  • application/json

Tags

  • Network

Inspect a network

GET /networks/{id}

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
200 No error NetworkInspectResp
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Produces

  • application/json

Tags

  • Network

Remove a network

DELETE /networks/{id}

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
204 No error No Content
403 operation not supported for pre-defined networks Error
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Network

Get Pouchd version

GET /version

Responses

HTTP Code Description Schema
200 no error SystemVersion
500 An unexpected server error occured. Error

List volumes

GET /volumes

Parameters

Type Name Description Schema
Query filters
optional		 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.		 string (json)

Responses

HTTP Code Description Schema
200 Summary volume data that matches the query VolumeListResp
500 An unexpected server error occured. Error

Produces

  • application/json

Tags

  • Volume

Example HTTP response

Response 200
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" : "size=100m,uid=1000",
      "type" : "tmpfs"
    }
  } ],
  "Warnings" : [ ]
}

Create a volume

POST /volumes/create

Parameters

Type Name Description Schema
Body body
required		 Volume configuration VolumeCreateConfig

Responses

HTTP Code Description Schema
201 The volume was created successfully VolumeInfo
500 An unexpected server error occured. Error

Consumes

  • application/json

Produces

  • application/json

Tags

  • Volume

Example HTTP request

Request body
json :
{
  "Name" : "tardis",
  "Labels" : {
    "com.example.some-label" : "some-value",
    "com.example.some-other-label" : "some-other-value"
  },
  "Driver" : "custom"
}

Inspect a volume

GET /volumes/{id}

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
200 No error VolumeInfo
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Produces

  • application/json

Tags

  • Volume

Delete a volume

DELETE /volumes/{id}

Parameters

Type Name Description Schema
Path id
required		 ID or name of the container string

Responses

HTTP Code Description Schema
204 No error No Content
404 An unexpected 404 error occured. Error
500 An unexpected server error occured. Error

Tags

  • Volume

Definitions

Container

an array of Container contains response of Engine API: GET "/containers/json"

Name Description Schema
Command
optional		 string
Created
optional		 Created time of container in daemon. integer (int64)
HostConfig
optional		 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.		 HostConfig
ID
optional		 string
Image
optional		 string
ImageID
optional		 string
Labels
optional		 < string, string > map
Mounts
optional		 Set of mount point in a container. < MountPoint > array
Names
optional		 Example : [ "container_1", "container_2" ] < string > array
NetworkSettings
optional		 object
SizeRootFs
optional		 integer (int64)
SizeRw
optional		 integer (int64)
State
optional		 string
Status
optional		 string

ContainerConfig

Configuration for a container that is portable between hosts

Name Description Schema
ArgsEscaped
optional		 Command is already escaped (Windows only) boolean
AttachStderr
optional		 Whether to attach to stderr.
Default : true		 boolean
AttachStdin
optional		 Whether to attach to stdin. boolean
AttachStdout
optional		 Whether to attach to stdout.
Default : true		 boolean
Cmd
optional		 Command to run specified an array of strings. < string > array
Domainname
optional		 The domain name to use for the container. string
Entrypoint
optional		 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 (i.e., the entry point used by pouch when there is no ENTRYPOINT instruction in the Dockerfile).		 < string > array
Env
optional		 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. < string > array
ExposedPorts
optional		 An object mapping ports to an empty object in the form:{<port>/<tcp|udp>: {}} < string, object > map
Hostname
optional		 The hostname to use for the container, as a valid RFC 1123 hostname.
Minimum length : 1		 string (hostname)
Image
required		 The name of the image to use when creating the container string
Labels
optional		 User-defined key/value metadata. < string, string > map
MacAddress
optional		 MAC address of the container. string
NetworkDisabled
optional		 Disable networking for the container. boolean
OnBuild
optional		 ONBUILD metadata that were defined in the image's Dockerfile. < string > array
OpenStdin
optional		 Open stdin boolean
Shell
optional		 Shell for when RUN, CMD, and ENTRYPOINT uses a shell. < string > array
StdinOnce
optional		 Close stdin after one attached client disconnects boolean
StopSignal
optional		 Signal to stop a container as a string or unsigned integer.
Default : "SIGTERM"		 string
StopTimeout
optional		 Timeout to stop a container in seconds. integer
Tty
optional		 Attach standard streams to a TTY, including stdin if it is not closed. boolean
User
optional		 The user that commands are run as inside the container. string
Volumes
optional		 An object mapping mount point paths inside the container to empty objects. < string, object > map
WorkingDir
optional		 The working directory for commands to run in. string

ContainerCreateConfig

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.

Polymorphism : Composition

Name Description Schema
ArgsEscaped
optional		 Command is already escaped (Windows only) boolean
AttachStderr
optional		 Whether to attach to stderr.
Default : true		 boolean
AttachStdin
optional		 Whether to attach to stdin. boolean
AttachStdout
optional		 Whether to attach to stdout.
Default : true		 boolean
Cmd
optional		 Command to run specified an array of strings. < string > array
Domainname
optional		 The domain name to use for the container. string
Entrypoint
optional		 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 (i.e., the entry point used by pouch when there is no ENTRYPOINT instruction in the Dockerfile).		 < string > array
Env
optional		 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. < string > array
ExposedPorts
optional		 An object mapping ports to an empty object in the form:{<port>/<tcp|udp>: {}} < string, object > map
HostConfig
optional		 HostConfig
Hostname
optional		 The hostname to use for the container, as a valid RFC 1123 hostname.
Minimum length : 1		 string (hostname)
Image
required		 The name of the image to use when creating the container string
Labels
optional		 User-defined key/value metadata. < string, string > map
MacAddress
optional		 MAC address of the container. string
NetworkDisabled
optional		 Disable networking for the container. boolean
NetworkingConfig
optional		 NetworkingConfig
OnBuild
optional		 ONBUILD metadata that were defined in the image's Dockerfile. < string > array
OpenStdin
optional		 Open stdin boolean
Shell
optional		 Shell for when RUN, CMD, and ENTRYPOINT uses a shell. < string > array
StdinOnce
optional		 Close stdin after one attached client disconnects boolean
StopSignal
optional		 Signal to stop a container as a string or unsigned integer.
Default : "SIGTERM"		 string
StopTimeout
optional		 Timeout to stop a container in seconds. integer
Tty
optional		 Attach standard streams to a TTY, including stdin if it is not closed. boolean
User
optional		 The user that commands are run as inside the container. string
Volumes
optional		 An object mapping mount point paths inside the container to empty objects. < string, object > map
WorkingDir
optional		 The working directory for commands to run in. string

ContainerCreateResp

response returned by daemon when container create successfully

Name Description Schema
Id
required		 The ID of the created container string
Name
optional		 The name of the created container string
Warnings
required		 Warnings encountered when creating the container < string > array

ContainerJSON

ContainerJSON contains response of Engine API: GET "/containers/{id}/json"

Name Description Schema
AppArmorProfile
optional		 string
Args
optional		 The arguments to the command being run < string > array
Config
optional		 ContainerConfig
Created
optional		 The time the container was created string
Driver
optional		 string
ExecIDs
optional		 string
GraphDriver
optional		 GraphDriverData
HostConfig
optional		 HostConfig
HostnamePath
optional		 string
HostsPath
optional		 string
Id
optional		 The ID of the container string
Image
optional		 The container's image string
LogPath
optional		 string
MountLabel
optional		 string
Mounts
optional		 Set of mount point in a container. < MountPoint > array
Name
optional		 string
NetworkSettings
optional		 NetworkSettings exposes the network settings in the API. NetworkSettings
Path
optional		 The path to the command being run string
ProcessLabel
optional		 string
ResolvConfPath
optional		 string
RestartCount
optional		 integer
SizeRootFs
optional		 The total size of all the files in this container. integer (int64)
SizeRw
optional		 The size of files that have been created or changed by this container. integer (int64)
State
optional		 The state of the container. ContainerState

ContainerState

Name Description Schema
Dead
optional		 Whether this container is dead. boolean
Error
optional		 The error message of this container string
ExitCode
optional		 The last exit code of this container integer
FinishedAt
optional		 The time when this container last exited. string
OOMKilled
optional		 Whether this container has been killed because it ran out of memory. boolean
Paused
optional		 Whether this container is paused. boolean
Pid
optional		 The process ID of this container integer
Restarting
optional		 Whether this container is restarting. boolean
Running
optional		 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".		 boolean
StartedAt
optional		 The time when this container was last started. string
Status
optional		 Status

DeviceMapping

A device mapping between the host and container

Name Description Schema
CgroupPermissions
optional		 cgroup permissions of the device string
PathInContainer
optional		 path in container of the device mapping string
PathOnHost
optional		 path on host of the device mapping string

EndpointSettings

Configuration for a network endpoint.

Name Description Schema
Aliases
optional		 Example : [ "server_x", "server_y" ] < string > array
DriverOpts
optional		 DriverOpts is a mapping of driver options and values. These options
are passed directly to the driver and are driver specific.
Example : {<br> "com.example.some-label" : "some-value",<br> "com.example.some-other-label" : "some-other-value"<br>}		 < string, string > map
EndpointID
optional		 Unique ID for the service endpoint in a Sandbox.
Example : "b88f5b905aabf2893f3cbc4ee42d1ea7980bbc0a92e2c8922b1e1795298afb0b"		 string
Gateway
optional		 Gateway address for this network.
Example : "172.17.0.1"		 string
GlobalIPv6Address
optional		 Global IPv6 address.
Example : "2001:db8::5689"		 string
GlobalIPv6PrefixLen
optional		 Mask length of the global IPv6 address.
Example : 64		 integer (int64)
IPAddress
optional		 IPv4 address.
Example : "172.17.0.4"		 string
IPPrefixLen
optional		 Mask length of the IPv4 address.
Example : 16		 integer
IPv6Gateway
optional		 IPv6 gateway address.
Example : "2001:db8:2::100"		 string
Links
optional		 Example : [ "container_1", "container_2" ] < string > array
MacAddress
optional		 MAC address for the endpoint on this network.
Example : "02:42:ac:11:00:04"		 string
NetworkID
optional		 Unique ID of the network.
Example : "08754567f1f40222263eab4102e1c733ae697e8e354aa9cd6e18d7402835292a"		 string

Error

Name Schema
message
optional		 string

ExecCreateConfig

Name Description Schema
AttachStderr
optional		 Attach the standard error boolean
AttachStdin
optional		 Attach the standard input, makes possible user interaction boolean
AttachStdout
optional		 Attach the standard output boolean
Cmd
optional		 Execution commands and args < string > array
Detach
optional		 Execute in detach mode boolean
DetachKeys
optional		 Escape keys for detach string
Privileged
optional		 Is the container in privileged mode boolean
Tty
optional		 Attach standard streams to a tty boolean
User
optional		 User that will run the command string

ExecCreateResp

Name Schema
ID
optional		 string

ExecStartConfig

Name Description Schema
Detach
optional		 ExecStart will first check if it's detached boolean
Tty
optional		 Check if there's a tty boolean

GraphDriverData

Information about a container's graph driver.

Name Schema
Data
required		 < string, string > map
Name
required		 string

HostConfig

Container configuration that depends on the host we are running on

Polymorphism : Composition

Name Description Schema
AutoRemove
optional		 Automatically remove the container when the container's process exits. This has no effect if RestartPolicy is set. boolean
Binds
optional		 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.		 < string > array
BlkioDeviceReadBps
optional		 Limit read rate (bytes per second) from a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceReadIOps
optional		 Limit read rate (IO per second) from a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceWriteBps
optional		 Limit write rate (bytes per second) to a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceWriteIOps
optional		 Limit write rate (IO per second) to a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioWeight
optional		 Block IO weight (relative weight).
Minimum value : 0
Maximum value : 1000		 integer (uint16)
BlkioWeightDevice
optional		 Block IO weight (relative device weight) in the form [{"Path": "device_path", "Weight": weight}]. < BlkioWeightDevice > array
CapAdd
optional		 A list of kernel capabilities to add to the container. < string > array
CapDrop
optional		 A list of kernel capabilities to drop from the container. < string > array
Cgroup
optional		 Cgroup to use for the container. string
CgroupParent
optional		 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. string
ConsoleSize
optional		 Initial console size, as an [height, width] array. (Windows only) < integer > array
ContainerIDFile
optional		 Path to a file where the container ID is written string
CpuCount
optional		 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.		 integer (int64)
CpuPercent
optional		 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.		 integer (int64)
CpuPeriod
optional		 CPU CFS (Completely Fair Scheduler) period.
The length of a CPU period in microseconds.		 integer (int64)
CpuQuota
optional		 CPU CFS (Completely Fair Scheduler) quota.
Microseconds of CPU time that the container can get in a CPU period."		 integer (int64)
CpuRealtimePeriod
optional		 The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks. integer (int64)
CpuRealtimeRuntime
optional		 The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks. integer (int64)
CpuShares
optional		 An integer value representing this container's relative CPU weight versus other containers. integer
CpusetCpus
optional		 CPUs in which to allow execution (e.g., 0-3, 0,1)
Example : "0-3"		 string
CpusetMems
optional		 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. string
DeviceCgroupRules
optional		 a list of cgroup rules to apply to the container < string > array
Devices
optional		 A list of devices to add to the container. < DeviceMapping > array
DiskQuota
optional		 Disk limit (in bytes). integer (int64)
Dns
optional		 A list of DNS servers for the container to use. < string > array
DnsOptions
optional		 A list of DNS options. < string > array
DnsSearch
optional		 A list of DNS search domains. < string > array
EnableLxcfs
optional		 Whether to enable lxcfs. boolean
ExtraHosts
optional		 A list of hostnames/IP mappings to add to the container's /etc/hosts file. Specified in the form ["hostname:IP"]. < string > array
GroupAdd
optional		 A list of additional groups that the container process will run as. < string > array
IOMaximumBandwidth
optional		 Maximum IO in bytes per second for the container system drive (Windows only) integer (uint64)
IOMaximumIOps
optional		 Maximum IOps for the container system drive (Windows only) integer (uint64)
IpcMode
optional		 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.		 string
Isolation
optional		 Isolation technology of the container. (Windows only) enum (default, process, hyperv)
KernelMemory
optional		 Kernel memory limit in bytes. integer (int64)
Links
optional		 A list of links for the container in the form container_name:alias. < string > array
LogConfig
optional		 The logging configuration for this container LogConfig
Memory
optional		 Memory limit in bytes. integer
MemoryReservation
optional		 Memory soft limit in bytes. integer (int64)
MemorySwap
optional		 Total memory limit (memory + swap). Set as -1 to enable unlimited swap. integer (int64)
MemorySwappiness
optional		 Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
Minimum value : 0
Maximum value : 100		 integer (int64)
NanoCPUs
optional		 CPU quota in units of 10-9 CPUs. integer (int64)
NetworkMode
optional		 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. string
OomKillDisable
optional		 Disable OOM Killer for the container. boolean
OomScoreAdj
optional		 An integer value containing the score given to the container in order to tune OOM killer preferences.
Example : 500		 integer
PidMode
optional		 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		 string
PidsLimit
optional		 Tune a container's pids limit. Set -1 for unlimited. Only on Linux 4.4 does this paramter support. integer (int64)
PortBindings
optional		 A map of exposed container ports and the host port they should map to. < string, PortBinding > map
Privileged
optional		 Gives the container full access to the host. boolean
PublishAllPorts
optional		 Allocates a random host port for all of a container's exposed ports. boolean
ReadonlyRootfs
optional		 Mount the container's root filesystem as read only. boolean
RestartPolicy
optional		 Restart policy to be used to manage the container RestartPolicy
Runtime
optional		 Runtime to use with this container. string
SecurityOpt
optional		 A list of string values to customize labels for MLS systems, such as SELinux. < string > array
ShmSize
optional		 Size of /dev/shm in bytes. If omitted, the system uses 64MB.
Minimum value : 0		 integer
StorageOpt
optional		 Storage driver options for this container, in the form {"size": "120G"}. < string, string > map
Sysctls
optional		 A list of kernel parameters (sysctls) to set in the container. For example: {"net.ipv4.ip_forward": "1"} < string, string > map
Tmpfs
optional		 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" }. < string, string > map
UTSMode
optional		 UTS namespace to use for the container. string
Ulimits
optional		 A list of resource limits to set in the container. For example: {"Name": "nofile", "Soft": 1024, "Hard": 2048}" < Ulimits > array
UsernsMode
optional		 Sets the usernamespace mode for the container when usernamespace remapping option is enabled. string
VolumeDriver
optional		 Driver that this container uses to mount volumes. string
VolumesFrom
optional		 A list of volumes to inherit from another container, specified in the form <container name>[:<ro|rw>]. < string > array

BlkioWeightDevice

Name Description Schema
Path
optional		 string
Weight
optional		 Minimum value : 0 integer (uint16)

LogConfig

Name Schema
Config
optional		 < string, string > map
Type
optional		 enum (json-file, syslog, journald, gelf, fluentd, awslogs, splunk, etwlogs, none)

Ulimits

Name Description Schema
Hard
optional		 Hard limit integer
Name
optional		 Name of ulimit string
Soft
optional		 Soft limit integer

IPAM

represents IP Address Management

Name Schema
Config
optional		 < IPAMConfig > array
Driver
optional		 string
Options
optional		 < string, string > map

IPAMConfig

represents IPAM configurations

Name Schema
AuxAddress
optional		 < string, string > map
Gateway
optional		 string
IPRange
optional		 string
Subnet
optional		 string

IPAddress

Address represents an IPv4 or IPv6 IP address.

Name Description Schema
Addr
optional		 IP address. string
PrefixLen
optional		 Mask length of the IP address. integer

ImageInfo

An object containing all details of an image at API side

Name Description Schema
CreatedAt
optional		 Time of image creation string
Digest
optional		 digest of image. string
ID
optional		 ID of an image. string
Name
optional		 name of an image. string
Size
optional		 size of image's taking disk space. integer
Tag
optional		 tag of an image. string

MountPoint

A mount point inside a container

Name Schema
Destination
optional		 string
Driver
optional		 string
Mode
optional		 string
Name
optional		 string
Propagation
optional		 string
RW
optional		 boolean
Source
optional		 string
Type
optional		 string

NetworkCreate

is the expected body of the "create network" http request message

Name Description Schema
CheckDuplicate
optional		 CheckDuplicate is used to check the network is duplicate or not. boolean
Driver
optional		 Driver means the network's driver. string
EnableIPv6
optional		 boolean
IPAM
optional		 IPAM
Internal
optional		 Internal checks the network is internal network or not. boolean
Labels
optional		 < string, string > map
Options
optional		 < string, string > map

NetworkCreateConfig

contains the request for the remote API: POST /networks/create

Polymorphism : Composition

Name Description Schema
CheckDuplicate
optional		 CheckDuplicate is used to check the network is duplicate or not. boolean
Driver
optional		 Driver means the network's driver. string
EnableIPv6
optional		 boolean
IPAM
optional		 IPAM
Internal
optional		 Internal checks the network is internal network or not. boolean
Labels
optional		 < string, string > map
Name
optional		 Name is the name of the network. string
Options
optional		 < string, string > map

NetworkCreateResp

contains the response for the remote API: POST /networks/create

Name Description Schema
ID
optional		 ID is the id of the network. string
Warning
optional		 Warning means the message of create network result. string

NetworkInspectResp

is the expected body of the 'GET networks/{id}'' http request message

Name Description Schema
Driver
optional		 Driver means the network's driver. string
EnableIPv6
optional		 EnableIPv6 represents whether to enable IPv6. boolean
ID
optional		 ID uniquely identifies a network on a single machine string
IPAM
optional		 IPAM is the network's IP Address Management. IPAM
Internal
optional		 Internal checks the network is internal network or not. boolean
Labels
optional		 Labels holds metadata specific to the network being created. < string, string > map
Name
optional		 Name is the requested name of the network string
Options
optional		 Options holds the network specific options to use for when creating the network. < string, string > map
Scope
optional		 Scope describes the level at which the network exists. string

NetworkSettings

NetworkSettings exposes the network settings in the API.

Name Description Schema
Bridge
optional		 Name of the network'a bridge (for example, pouch-br).
Example : "pouch-br"		 string
HairpinMode
optional		 Indicates if hairpin NAT should be enabled on the virtual interface
Example : false		 boolean
LinkLocalIPv6Address
optional		 IPv6 unicast address using the link-local prefix
Example : "fe80::42:acff:fe11:1"		 string
LinkLocalIPv6PrefixLen
optional		 Prefix length of the IPv6 unicast address.
Example : 64		 integer
Networks
optional		 Information about all networks that the container is connected to < string, EndpointSettings > map
Ports
optional		 PortMap
SandboxID
optional		 SandboxID uniquely represents a container's network stack.
Example : "9d12daf2c33f5959c8bf90aa513e4f65b561738661003029ec84830cd503a0c3"		 string
SandboxKey
optional		 SandboxKey identifies the sandbox
Example : "/var/run/pouch/netns/8ab54b426c38"		 string
SecondaryIPAddresses
optional		 < IPAddress > array
SecondaryIPv6Addresses
optional		 < IPAddress > array

NetworkingConfig

Configuration for a network used to create a container.

Name Schema
EndpointsConfig
optional		 EndpointSettings

PortBinding

PortBinding represents a binding between a host IP address and a host port

Name Description Schema
HostIp
optional		 Host IP address that the container's port is mapped to.
Example : "127.0.0.1"		 string
HostPort
optional		 Host port number that the container's port is mapped to.
Example : "4443"		 string

PortMap

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 : < string, < PortBinding > array > map

Resources

A container's resources (cgroups config, ulimits, etc)

Name Description Schema
BlkioDeviceReadBps
optional		 Limit read rate (bytes per second) from a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceReadIOps
optional		 Limit read rate (IO per second) from a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceWriteBps
optional		 Limit write rate (bytes per second) to a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioDeviceWriteIOps
optional		 Limit write rate (IO per second) to a device, in the form [{"Path": "device_path", "Rate": rate}]. < ThrottleDevice > array
BlkioWeight
optional		 Block IO weight (relative weight).
Minimum value : 0
Maximum value : 1000		 integer (uint16)
BlkioWeightDevice
optional		 Block IO weight (relative device weight) in the form [{"Path": "device_path", "Weight": weight}]. < BlkioWeightDevice > array
CgroupParent
optional		 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. string
CpuCount
optional		 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.		 integer (int64)
CpuPercent
optional		 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.		 integer (int64)
CpuPeriod
optional		 CPU CFS (Completely Fair Scheduler) period.
The length of a CPU period in microseconds.		 integer (int64)
CpuQuota
optional		 CPU CFS (Completely Fair Scheduler) quota.
Microseconds of CPU time that the container can get in a CPU period."		 integer (int64)
CpuRealtimePeriod
optional		 The length of a CPU real-time period in microseconds. Set to 0 to allocate no time allocated to real-time tasks. integer (int64)
CpuRealtimeRuntime
optional		 The length of a CPU real-time runtime in microseconds. Set to 0 to allocate no time allocated to real-time tasks. integer (int64)
CpuShares
optional		 An integer value representing this container's relative CPU weight versus other containers. integer
CpusetCpus
optional		 CPUs in which to allow execution (e.g., 0-3, 0,1)
Example : "0-3"		 string
CpusetMems
optional		 Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. string
DeviceCgroupRules
optional		 a list of cgroup rules to apply to the container < string > array
Devices
optional		 A list of devices to add to the container. < DeviceMapping > array
DiskQuota
optional		 Disk limit (in bytes). integer (int64)
IOMaximumBandwidth
optional		 Maximum IO in bytes per second for the container system drive (Windows only) integer (uint64)
IOMaximumIOps
optional		 Maximum IOps for the container system drive (Windows only) integer (uint64)
KernelMemory
optional		 Kernel memory limit in bytes. integer (int64)
Memory
optional		 Memory limit in bytes. integer
MemoryReservation
optional		 Memory soft limit in bytes. integer (int64)
MemorySwap
optional		 Total memory limit (memory + swap). Set as -1 to enable unlimited swap. integer (int64)
MemorySwappiness
optional		 Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
Minimum value : 0
Maximum value : 100		 integer (int64)
NanoCPUs
optional		 CPU quota in units of 10-9 CPUs. integer (int64)
OomKillDisable
optional		 Disable OOM Killer for the container. boolean
PidsLimit
optional		 Tune a container's pids limit. Set -1 for unlimited. Only on Linux 4.4 does this paramter support. integer (int64)
Ulimits
optional		 A list of resource limits to set in the container. For example: {"Name": "nofile", "Soft": 1024, "Hard": 2048}" < Ulimits > array

BlkioWeightDevice

Name Description Schema
Path
optional		 string
Weight
optional		 Minimum value : 0 integer (uint16)

Ulimits

Name Description Schema
Hard
optional		 Hard limit integer
Name
optional		 Name of ulimit string
Soft
optional		 Soft limit integer

RestartPolicy

Define container's restart policy

Name Schema
MaximumRetryCount
optional		 integer
Name
optional		 string

SearchResultItem

search result item in search results.

Name Description Schema
description
optional		 description just shows the description of this image string
is_automated
optional		 is_automated means whether this image is automated. boolean
is_official
optional		 is_official shows if this image is marked official. boolean
name
optional		 name represents the name of this image string
star_count
optional		 star_count refers to the star count of this image. integer

Status

The status of the container. For example, "running" or "exited".

Type : enum (created, running, stopped, paused, restarting, removing, exited, dead)

SystemInfo

Name Schema
Architecture
optional		 string
Containers
optional		 integer
ContainersPaused
optional		 integer
ContainersRunning
optional		 integer
ContainersStopped
optional		 integer

SystemVersion

Name Description Schema
ApiVersion
optional		 Api Version held by daemon
Example : ""		 string
Arch
optional		 Arch type of underlying hardware
Example : "amd64"		 string
BuildTime
optional		 The time when this binary of daemon is built
Example : "2017-08-29T17:41:57.729792388+00:00"		 string
GitCommit
optional		 Commit ID held by the latest commit operation
Example : ""		 string
GoVersion
optional		 version of Go runtime
Example : "1.8.3"		 string
KernelVersion
optional		 Operating system kernel version
Example : "3.13.0-106-generic"		 string
Os
optional		 Operating system type of underlying system
Example : "linux"		 string
Version
optional		 version of Pouch Daemon
Example : "0.1.2"		 string

ThrottleDevice

Name Description Schema
Path
optional		 Device path string
Rate
optional		 Rate
Minimum value : 0		 integer (uint64)

VolumeCreateConfig

config used to create a volume

Name Description Schema
Driver
optional		 Name of the volume driver to use.
Default : "local"		 string
DriverOpts
optional		 A mapping of driver options and values. These options are passed directly to the driver and are driver specific. < string, string > map
Labels
optional		 User-defined key/value metadata. < string, string > map
Name
optional		 The new volume's name. If not specified, Docker generates a name. string

VolumeInfo

Volume represents the configuration of a volume for the container.

Name Description Schema
CreatedAt
optional		 Date/Time the volume was created. string (dateTime)
Driver
optional		 Driver is the Driver name used to create the volume. string
Labels
optional		 Labels is metadata specific to the volume. < string, string > map
Mountpoint
optional		 Mountpoint is the location on disk of the volume. string
Name
optional		 Name is the name of the volume. string
Scope
optional		 Scope describes the level at which the volume exists
(e.g. global for cluster-wide or local for machine level)		 string
Status
optional		 Status provides low-level status information about the volume. < string, object > map

VolumeListResp

Name Description Schema
Volumes
required		 List of volumes < VolumeInfo > array
Warnings
required		 Warnings that occurred when fetching the list of volumes < string > array