centersl/docker-docs
1
0
Fork 0
mirror of https://github.com/docker/docs.git synced 2026-04-12 06:19:22 +07:00
Code Issues Packages Projects Releases Wiki Activity

Add volume API/CLI

Browse Source 
Signed-off-by: Brian Goff <cpuguy83@gmail.com>
This commit is contained in:
Brian Goff
2015-06-12 09:25:32 -04:00
parent 7ef08f39ed
commit b3b7eb2723
49 changed files with 1457 additions and 396 deletions
Download Patch File Download Diff File Expand all files Collapse all files

350
docs/reference/api/docker_remote_api.md
View File

@@ -10,39 +10,48 @@ parent = "smn_remoteapi"
# Docker Remote API
- By default the Docker daemon listens on `unix:///var/run/docker.sock`
and the client must have `root` access to interact with the daemon.
- If you are using `docker-machine`, the Docker daemon is on a virtual host that uses an encrypted TCP socket. In this situation, you need to add extra
parameters to `curl` or `wget` when making test API requests:
`curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://YOUR_VM_IP:2376/images/json`
or
`wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem --private-key=$DOCKER_CERT_PATH/key.pem https://your_vm_ip:2376/images/json -O - -q`
- If a group named `docker` exists on your system, docker will apply
ownership of the socket to the group.
- The API tends to be REST, but for some complex commands, like attach
or pull, the HTTP connection is hijacked to transport STDOUT, STDIN,
and STDERR.
- Since API version 1.2, the auth configuration is now handled client
side, so the client has to send the `authConfig` as a `POST` in `/images/(name)/push`.
- authConfig, set as the `X-Registry-Auth` header, is currently a Base64
encoded (JSON) string with the following structure:
`{"username": "string", "password": "string", "email": "string",
"serveraddress" : "string", "auth": ""}`. Notice that `auth` is to be left
empty, `serveraddress` is a domain/ip without protocol, and that double
quotes (instead of single ones) are required.
- The Remote API uses an open schema model. In this model, unknown
properties in incoming messages will be ignored.
Client applications need to take this into account to ensure
they will not break when talking to newer Docker daemons.
Docker's Remote API uses an open schema model. In this model, unknown
properties in incoming messages are ignored. Client applications need to take
this behavior into account to ensure they do not break when talking to newer
Docker daemons.
The current version of the API is v1.21
The API tends to be REST, but for some complex commands, like attach or pull,
the HTTP connection is hijacked to transport STDOUT, STDIN, and STDERR.
By default the Docker daemon listens on `unix:///var/run/docker.sock` and the
client must have `root` access to interact with the daemon. If a group named
`docker` exists on your system, `docker` applies ownership of the socket to the
group.
Calling `/info` is the same as calling
`/v1.21/info`.
You can still call an old version of the API using
The current version of the API is v1.21 which means calling `/info` is the same
as calling `/v1.21/info`. To call an older version of the API use
`/v1.20/info`.
## Authentication
Since API version 1.2, the auth configuration is now handled client side, so the
client has to send the `authConfig` as a `POST` in `/images/(name)/push`. The
`authConfig`, set as the `X-Registry-Auth` header, is currently a Base64 encoded
(JSON) string with the following structure:
```
{"username": "string", "password": "string", "email": "string",
"serveraddress" : "string", "auth": ""}
```
Callers should leave the `auth` empty. The `serveraddress` is a domain/ip
without protocol. Throughout this structure, double quotes are required.
## Using Docker Machine with the API
If you are using `docker-machine`, the Docker daemon is on a virtual host that uses an encrypted TCP socket. This means, for Docker Machine users, you need to add extra parameters to `curl` or `wget` when making test API requests, for example:
```
curl --insecure --cert ~/.docker/cert.pem --key ~/.docker/key.pem https://YOUR_VM_IP:2376/images/json
wget --no-check-certificate --certificate=$DOCKER_CERT_PATH/cert.pem --private-key=$DOCKER_CERT_PATH/key.pem https://your_vm_ip:2376/images/json -O - -q
```
## Docker Events
The following diagram depicts the container states accessible through the API.
@@ -59,248 +68,109 @@ Running `docker rmi` emits an **untag** event when removing an image name. The
> **Acknowledgement**: This diagram and the accompanying text were used with the permission of Matt Good and Gilder Labs. See Matt's original blog post [Docker Events Explained](http://gliderlabs.com/blog/2015/04/14/docker-events-explained/).
## v1.21
## Version history
### Full documentation
This section lists each version from latest to oldest. Each listing includes a link to the full documentation set and the changes relevant in that release.
[*Docker Remote API v1.21*](/reference/api/docker_remote_api_v1.21/)
### v1.21 API changes
## v1.20
[Docker Remote API v1.21](/reference/api/docker_remote_api_v1.21/) documentation
### Full documentation
* `GET /volumes` lists volumes from all volume drivers.
* `POST /volumes` to create a volume.
* `GET /volumes/(name)` get low-level information about a volume.
* `DELETE /volumes/(name)`remove a volume with the specified name.
[*Docker Remote API v1.20*](/reference/api/docker_remote_api_v1.20/)
### What's new
### v1.20 API changes
`GET /containers/(id)/archive`
[Docker Remote API v1.20](/reference/api/docker_remote_api_v1.20/) documentation
**New!**
Get an archive of filesystem content from a container.
* `GET /containers/(id)/archive` get an archive of filesystem content from a container.
* `PUT /containers/(id)/archive` upload an archive of content to be extracted to
an existing directory inside a container's filesystem.
* `POST /containers/(id)/copy` is deprecated in favor of the above `archive`
endpoint which can be used to download files and directories from a container.
* The `hostConfig` option now accepts the field `GroupAdd`, which specifies a
list of additional groups that the container process will run as.
`PUT /containers/(id)/archive`
### v1.19 API changes
**New!**
Upload an archive of content to be extracted to an
existing directory inside a container's filesystem.
[Docker Remote API v1.19](/reference/api/docker_remote_api_v1.19/) documentation
`POST /containers/(id)/copy`
**Deprecated!**
This copy endpoint has been deprecated in favor of the above `archive` endpoint
which can be used to download files and directories from a container.
**New!**
The `hostConfig` option now accepts the field `GroupAdd`, which specifies a list of additional
groups that the container process will run as.
## v1.19
### Full documentation
[*Docker Remote API v1.19*](/reference/api/docker_remote_api_v1.19/)
### What's new
**New!**
When the daemon detects a version mismatch with the client, usually when
* When the daemon detects a version mismatch with the client, usually when
the client is newer than the daemon, an HTTP 400 is now returned instead
of a 404.
* `GET /containers/(id)/stats` now accepts `stream` bool to get only one set of stats and disconnect.
* `GET /containers/(id)/logs` now accepts a `since` timestamp parameter.
* `GET /info` The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and
`SwapLimit` are now returned as boolean instead of as an int. In addition, the
end point now returns the new boolean fields `CpuCfsPeriod`, `CpuCfsQuota`, and
`OomKillDisable`.
`GET /containers/(id)/stats`
### v1.18 API changes
**New!**
You can now supply a `stream` bool to get only one set of stats and
disconnect
[Docker Remote API v1.18](/reference/api/docker_remote_api_v1.18/) documentation
`GET /containers/(id)/logs`
* `GET /version` now returns `Os`, `Arch` and `KernelVersion`.
* `POST /containers/create` and `POST /containers/(id)/start`allow you to set ulimit settings for use in the container.
* `GET /info` now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
* `GET /images/json` added a `RepoDigests` field to include image digest information.
* `POST /build` can now set resource constraints for all containers created for the build.
* `CgroupParent` can be passed in the host config to setup container cgroups under a specific cgroup.
* `POST /build` closing the HTTP request cancels the build
* `POST /containers/(id)/exec` includes `Warnings` field to response.
**New!**
### v1.17 API changes
This endpoint now accepts a `since` timestamp parameter.
[Docker Remote API v1.17](/reference/api/docker_remote_api_v1.17/) documentation
`GET /info`
**New!**
The fields `Debug`, `IPv4Forwarding`, `MemoryLimit`, and `SwapLimit`
are now returned as boolean instead of as an int.
In addition, the end point now returns the new boolean fields
`CpuCfsPeriod`, `CpuCfsQuota`, and `OomKillDisable`.
## v1.18
### Full documentation
[*Docker Remote API v1.18*](/reference/api/docker_remote_api_v1.18/)
### What's new
`GET /version`
**New!**
This endpoint now returns `Os`, `Arch` and `KernelVersion`.
`POST /containers/create`
`POST /containers/(id)/start`
**New!**
You can set ulimit settings to be used within the container.
`GET /info`
**New!**
This endpoint now returns `SystemTime`, `HttpProxy`,`HttpsProxy` and `NoProxy`.
`GET /images/json`
**New!**
Added a `RepoDigests` field to include image digest information.
`POST /build`
**New!**
Builds can now set resource constraints for all containers created for the build.
**New!**
(`CgroupParent`) can be passed in the host config to setup container cgroups under a specific cgroup.
`POST /build`
**New!**
Closing the HTTP request will now cause the build to be canceled.
`POST /containers/(id)/exec`
**New!**
Add `Warnings` field to response.
## v1.17
### Full documentation
[*Docker Remote API v1.17*](/reference/api/docker_remote_api_v1.17/)
### What's new
The build supports `LABEL` command. Use this to add metadata
to an image. For example you could add data describing the content of an image.
`LABEL "com.example.vendor"="ACME Incorporated"`
**New!**
`POST /containers/(id)/attach` and `POST /exec/(id)/start`
**New!**
Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
`POST /containers/create`
**New!**
You can set labels on container create describing the container.
`GET /containers/json`
**New!**
The endpoint returns the labels associated with the containers (`Labels`).
`GET /containers/(id)/json`
**New!**
This endpoint now returns the list current execs associated with the container (`ExecIDs`).
This endpoint now returns the container labels (`Config.Labels`).
`POST /containers/(id)/rename`
**New!**
New endpoint to rename a container `id` to a new name.
`POST /containers/create`
`POST /containers/(id)/start`
**New!**
(`ReadonlyRootfs`) can be passed in the host config to mount the container's
root filesystem as read only.
`GET /containers/(id)/stats`
**New!**
This endpoint returns a live stream of a container's resource usage statistics.
`GET /images/json`
**New!**
This endpoint now returns the labels associated with each image (`Labels`).
* The build supports `LABEL` command. Use this to add metadata to an image. For
example you could add data describing the content of an image. `LABEL
"com.example.vendor"="ACME Incorporated"`
* `POST /containers/(id)/attach` and `POST /exec/(id)/start`
* The Docker client now hints potential proxies about connection hijacking using HTTP Upgrade headers.
* `POST /containers/create` sets labels on container create describing the container.
* `GET /containers/json` returns the labels associated with the containers (`Labels`).
* `GET /containers/(id)/json` returns the list current execs associated with the
container (`ExecIDs`). This endpoint now returns the container labels
(`Config.Labels`).
* `POST /containers/(id)/rename` renames a container `id` to a new name.*
* `POST /containers/create` and `POST /containers/(id)/start` callers can pass
`ReadonlyRootfs` in the host config to mount the container's root filesystem as
read only.
* `GET /containers/(id)/stats` returns a live stream of a container's resource usage statistics.
* `GET /images/json` returns the labels associated with each image (`Labels`).
## v1.16
### v1.16 API changes
### Full documentation
[Docker Remote API v1.16](/reference/api/docker_remote_api_v1.16/)
[*Docker Remote API v1.16*](/reference/api/docker_remote_api_v1.16/)
### What's new
`GET /info`
**New!**
`info` now returns the number of CPUs available on the machine (`NCPU`),
* `GET /info` returns the number of CPUs available on the machine (`NCPU`),
total memory available (`MemTotal`), a user-friendly name describing the running Docker daemon (`Name`), a unique ID identifying the daemon (`ID`), and
a list of daemon labels (`Labels`).
* `POST /containers/create` callers can set the new container's MAC address explicitly.
* Volumes are now initialized when the container is created.
* `POST /containers/(id)/copy` copies data which is contained in a volume.
`POST /containers/create`
### v1.15 API changes
**New!**
You can set the new container's MAC address explicitly.
[Docker Remote API v1.15](/reference/api/docker_remote_api_v1.15/) documentation
**New!**
Volumes are now initialized when the container is created.
`POST /containers/create` you can set a container's `HostConfig` when creating a
container. Previously this was only available when starting a container.
`POST /containers/(id)/copy`
### v1.14 API changes
**New!**
You can now copy data which is contained in a volume.
[Docker Remote API v1.14](/reference/api/docker_remote_api_v1.14/) documentation
## v1.15
### Full documentation
[*Docker Remote API v1.15*](/reference/api/docker_remote_api_v1.15/)
### What's new
`POST /containers/create`
**New!**
It is now possible to set a container's HostConfig when creating a container.
Previously this was only available when starting a container.
## v1.14
### Full documentation
[*Docker Remote API v1.14*](/reference/api/docker_remote_api_v1.14/)
### What's new
`DELETE /containers/(id)`
**New!**
When using `force`, the container will be immediately killed with SIGKILL.
`POST /containers/(id)/start`
**New!**
The `hostConfig` option now accepts the field `CapAdd`, which specifies a list of capabilities
* `DELETE /containers/(id)` when using `force`, the container will be immediately killed with SIGKILL.
* `POST /containers/(id)/start` the `hostConfig` option accepts the field `CapAdd`, which specifies a list of capabilities
to add, and the field `CapDrop`, which specifies a list of capabilities to drop.
`POST /images/create`
**New!**
The `fromImage` and `repo` parameters now supports the `repo:tag` format.
Consequently, the `tag` parameter is now obsolete. Using the new format and
the `tag` parameter at the same time will return an error.
* `POST /images/create` th `fromImage` and `repo` parameters supportthe
`repo:tag` format. Consequently, the `tag` parameter is now obsolete. Using the
new format and the `tag` parameter at the same time will return an error.

120
docs/reference/api/docker_remote_api_v1.21.md
View File

@@ -2245,6 +2245,126 @@ Status Codes:
- **404** – no such exec instance
- **500** - server error
## 2.4 Volumes
### List volumes
`GET /volumes`
**Example request**:
GET /volumes HTTP/1.1
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Volumes": [
{
"Name": "tardis",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/tardis"
}
]
}
Query Parameters:
- **filter** - JSON encoded value of the filters (a `map[string][]string`) to process on the volumes list. There is one available filter: `dangling=true`
Status Codes:
- **200** - no error
- **500** - server error
### Create a volume
`POST /volumes`
Create a volume
**Example request**:
POST /volumes HTTP/1.1
Content-Type: application/json
{
"Name": "tardis"
}
**Example response**:
HTTP/1.1 201 Created
Content-Type: application/json
{
"Name": "tardis"
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/tardis"
}
Status Codes:
- **201** - no error
- **500** - server error
JSON Parameters:
- **Name** - The new volume's name. If not specified, Docker generates a name.
- **Driver** - Name of the volume driver to use. Defaults to `local` for the name.
- **DriverOpts** - A mapping of driver options and values. These options are
passed directly to the driver and are driver specific.
### Inspect a volume
`GET /volumes/(name)`
Return low-level information on the volume `name`
**Example request**:
GET /volumes/tardis
**Example response**:
HTTP/1.1 200 OK
Content-Type: application/json
{
"Name": "tardis",
"Driver": "local",
"Mountpoint": "/var/lib/docker/volumes/tardis"
}
Status Codes:
- **200** - no error
- **404** - no such volume
- **500** - server error
### Remove a volume
`DELETE /volumes/(name)`
Instruct the driver to remove the volume (`name`).
**Example request**:
DELETE /volumes/local/tardis HTTP/1.1
**Example response**:
HTTP/1.1 204 No Content
Status Codes
- **204** - no error
- **404** - no such volume or volume driver
- **409** - volume is in use and cannot be removed
- **500** - server error
# 3. Going further
## 3.1 Inside `docker run`