From 82dc9301a91768c9c46d10c55546bfeea54e6eb4 Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sat, 27 May 2017 22:37:36 +0200 Subject: [PATCH 1/7] Fix typo in swagger doc Signed-off-by: Tobias Gesellchen (cherry picked from commit 56da4f2fb2509f9b2c2bc1c1c609c1dabeaec07d) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 5df349e390..037f51108c 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -3119,7 +3119,7 @@ paths: 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 determin if a container's state is "running". + Use the `Status` field instead to determine if a container's state is "running". type: "boolean" Paused: description: "Whether this container is paused." From e0fe1f5bf697ac2ac7830c7270d507f98c0d6130 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 6 Jul 2017 18:59:29 -0700 Subject: [PATCH 2/7] Service privileges: API docs This documents the Service privileges API changes, that were added in: 091b5e68ea735bf4e8ece708bbc8c413a32eab73 Signed-off-by: Sebastiaan van Stijn (cherry picked from commit d0a8e73e7b60f61db0c3799643aaccbbf33f3601) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 51 +++++++++++++++++++ components/engine/docs/api/version-history.md | 2 + 2 files changed, 53 insertions(+) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 037f51108c..787a1c4cc0 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -2003,6 +2003,57 @@ definitions: description: "A list of additional groups that the container process will run as." items: type: "string" + Privileges: + type: "object" + description: "Security options for the container" + properties: + CredentialSpec: + type: "object" + description: "CredentialSpec for managed service account (Windows only)" + properties: + File: + type: "string" + description: | + Load credential spec from this file. The file is read by the daemon, and must be present in the + `CredentialSpecs` subdirectory in the docker data directory, which defaults to + `C:\ProgramData\Docker\` on Windows. + + For example, specifying `spec.json` loads `C:\ProgramData\Docker\CredentialSpecs\spec.json`. + +


+ + > **Note**: `CredentialSpec.File` and `CredentialSpec.Registry` are mutually exclusive. + Registry: + type: "string" + description: | + Load credential spec from this value in the Windows registry. The specified registry value must be + located in: + + `HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\Virtualization\Containers\CredentialSpecs` + +


+ + + > **Note**: `CredentialSpec.File` and `CredentialSpec.Registry` are mutually exclusive. + SELinuxContext: + type: "object" + description: "SELinux labels of the container" + properties: + Disable: + type: "boolean" + description: "Disable SELinux" + User: + type: "string" + description: "SELinux user label" + Role: + type: "string" + description: "SELinux role label" + Type: + type: "string" + description: "SELinux type label" + Level: + type: "string" + description: "SELinux level label" TTY: description: "Whether a pseudo-TTY should be allocated." type: "boolean" diff --git a/components/engine/docs/api/version-history.md b/components/engine/docs/api/version-history.md index 8cb95b2948..8cfc6eec14 100644 --- a/components/engine/docs/api/version-history.md +++ b/components/engine/docs/api/version-history.md @@ -43,6 +43,8 @@ keywords: "API, Docker, rcli, REST, documentation" * `POST /containers/create`, `POST /service/create` and `POST /services/(id or name)/update` now takes the field `StartPeriod` as a part of the `HealthConfig` allowing for specification of a period during which the container should not be considered unhealthy even if health checks do not pass. * `GET /services/(id)` now accepts an `insertDefaults` query-parameter to merge default values into the service inspect output. * `POST /containers/prune`, `POST /images/prune`, `POST /volumes/prune`, and `POST /networks/prune` now support a `label` filter to filter containers, images, volumes, or networks based on the label. The format of the label filter could be `label=`/`label==` to remove those with the specified labels, or `label!=`/`label!==` to remove those without the specified labels. +* `POST /services/create` now accepts `Privileges` as part of `ContainerSpec`. Privileges currently include + `CredentialSpec` and `SELinuxContext`. ## v1.28 API changes From 9ec7c03cf225e52a27d4526bf3472b9868579696 Mon Sep 17 00:00:00 2001 From: allencloud Date: Mon, 10 Jul 2017 16:31:54 +0800 Subject: [PATCH 3/7] add cluster events details in swagger.yml Signed-off-by: allencloud (cherry picked from commit f596fb7683227021b74d299ad1613a1e3263cf30) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 787a1c4cc0..3a71b35bfa 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -5647,16 +5647,22 @@ paths: Various objects within Docker report events when something happens to them. - Containers report these events: `attach, commit, copy, create, destroy, detach, die, exec_create, exec_detach, exec_start, export, health_status, kill, oom, pause, rename, resize, restart, start, stop, top, unpause, update` + Containers report these events: `attach`, `commit`, `copy`, `create`, `destroy`, `detach`, `die`, `exec_create`, `exec_detach`, `exec_start`, `export`, `health_status`, `kill`, `oom`, `pause`, `rename`, `resize`, `restart`, `start`, `stop`, `top`, `unpause`, and `update` - Images report these events: `delete, import, load, pull, push, save, tag, untag` + Images report these events: `delete`, `import`, `load`, `pull`, `push`, `save`, `tag`, and `untag` - Volumes report these events: `create, mount, unmount, destroy` + Volumes report these events: `create`, `mount`, `unmount`, and `destroy` - Networks report these events: `create, connect, disconnect, destroy` + Networks report these events: `create`, `connect`, `disconnect`, `destroy`, `update`, and `remove` The Docker daemon reports these events: `reload` + Services report these events: `create`, `update`, and `remove` + + Nodes report these events: `create`, `update`, and `remove` + + Secrets report these events: `create`, `update`, and `remove` + operationId: "SystemEvents" produces: - "application/json" @@ -5730,7 +5736,8 @@ paths: - `label=` image or container label - `network=` network name or ID - `plugin`= plugin name or ID - - `type=` object to filter by, one of `container`, `image`, `volume`, `network`, or `daemon` + - `scope`＝ local or swarm + - `type=` object to filter by, one of `container`, `image`, `volume`, `network`, `daemon`, `plugin`, `node`, `service` or `secret` - `volume=` volume name or ID type: "string" tags: ["System"] From 8e88731cf290684ecf634cfc6e1d3b26efe895ee Mon Sep 17 00:00:00 2001 From: allencloud Date: Wed, 12 Jul 2017 09:22:07 +0800 Subject: [PATCH 4/7] add cluster events change in version_history.md Signed-off-by: allencloud (cherry picked from commit e9da15a6603f288a4c0005fc8f4161b45390e26b) Signed-off-by: Sebastiaan van Stijn --- components/engine/docs/api/version-history.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/components/engine/docs/api/version-history.md b/components/engine/docs/api/version-history.md index 8cfc6eec14..4af8272a60 100644 --- a/components/engine/docs/api/version-history.md +++ b/components/engine/docs/api/version-history.md @@ -31,6 +31,9 @@ keywords: "API, Docker, rcli, REST, documentation" * `POST /containers/(name)/wait` now accepts a `condition` query parameter to indicate which state change condition to wait for. Also, response headers are now returned immediately to acknowledge that the server has registered a wait callback for the client. * `POST /swarm/init` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic * `POST /swarm/join` now accepts a `DataPathAddr` property to set the IP-address or network interface to use for data traffic +* `GET /events` now supports service, node and secret events which are emmited when users create, update and remove service, node and secret +* `GET /events` now supports network remove event which is emmitted when users remove a swarm scoped network +* `GET /events` now supports a filter type `scope` in which supported value could be swarm and local ## v1.29 API changes From f30bfbf6c499ca251f664c004f41f14af5d13e92 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 19 Jul 2017 00:22:05 +0200 Subject: [PATCH 5/7] Fix API docs for GET /secrets/{id}, GET /secrets The swagger.yml defined these endpoints to return a "ServiceSpec" instead of a "SecretSpec". Signed-off-by: Sebastiaan van Stijn (cherry picked from commit f6954bea9f28c62c50b88c895968045cf801aa81) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 3a71b35bfa..82fa9194ff 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -2739,7 +2739,7 @@ definitions: type: "string" format: "dateTime" Spec: - $ref: "#/definitions/ServiceSpec" + $ref: "#/definitions/SecretSpec" paths: /containers/json: get: From 7b48a2700dbfb922946cbeb71c5aa575b214bbde Mon Sep 17 00:00:00 2001 From: Aaron Lehmann Date: Tue, 18 Jul 2017 16:51:51 -0700 Subject: [PATCH 6/7] api: Update swagger.yaml for configs Also fix bad reference to ServiceSpec. Signed-off-by: Aaron Lehmann (cherry picked from commit ea1d14a189d62df34427b037a6d043ae3028760b) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 267 ++++++++++++++++++++++++++++- 1 file changed, 261 insertions(+), 6 deletions(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 82fa9194ff..346e40b43f 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -711,7 +711,7 @@ definitions: - "process" - "hyperv" - Config: + ContainerConfig: description: "Configuration for a container that is portable between hosts" type: "object" properties: @@ -908,7 +908,7 @@ definitions: type: "string" x-nullable: false ContainerConfig: - $ref: "#/definitions/Config" + $ref: "#/definitions/ContainerConfig" DockerVersion: type: "string" x-nullable: false @@ -916,7 +916,7 @@ definitions: type: "string" x-nullable: false Config: - $ref: "#/definitions/Config" + $ref: "#/definitions/ContainerConfig" Architecture: type: "string" x-nullable: false @@ -2136,6 +2136,37 @@ definitions: SecretName is the name of the secret that this references, but this is just provided for lookup/display purposes. The secret in the reference will be identified by its ID. type: "string" + Configs: + description: "Configs contains references to zero or more configs that will be exposed to the service." + type: "array" + items: + type: "object" + properties: + File: + description: "File represents a specific target that is backed by a file." + type: "object" + properties: + Name: + description: "Name represents the final filename in the filesystem." + type: "string" + UID: + description: "UID represents the file UID." + type: "string" + GID: + description: "GID represents the file GID." + type: "string" + Mode: + description: "Mode represents the FileMode of the file." + type: "integer" + format: "uint32" + ConfigID: + description: "ConfigID represents the ID of the specific config that we're referencing." + type: "string" + ConfigName: + description: | + ConfigName is the name of the config that this references, but this is just provided for + lookup/display purposes. The config in the reference will be identified by its ID. + type: "string" Resources: description: "Resource requirements which apply to each individual container created as part of the service." @@ -2740,6 +2771,38 @@ definitions: format: "dateTime" Spec: $ref: "#/definitions/SecretSpec" + ConfigSpec: + type: "object" + properties: + Name: + description: "User-defined name of the config." + type: "string" + Labels: + description: "User-defined key/value metadata." + type: "object" + additionalProperties: + type: "string" + Data: + description: "Base64-url-safe-encoded config data" + type: "array" + items: + type: "string" + Config: + type: "object" + properties: + ID: + type: "string" + Version: + $ref: "#/definitions/ObjectVersion" + CreatedAt: + type: "string" + format: "dateTime" + UpdatedAt: + type: "string" + format: "dateTime" + Spec: + $ref: "#/definitions/ConfigSpec" + paths: /containers/json: get: @@ -2944,7 +3007,7 @@ paths: description: "Container to create" schema: allOf: - - $ref: "#/definitions/Config" + - $ref: "#/definitions/ContainerConfig" - type: "object" properties: HostConfig: @@ -3242,7 +3305,7 @@ paths: items: $ref: "#/definitions/MountPoint" Config: - $ref: "#/definitions/Config" + $ref: "#/definitions/ContainerConfig" NetworkSettings: $ref: "#/definitions/NetworkConfig" examples: @@ -5608,7 +5671,7 @@ paths: in: "body" description: "The container configuration" schema: - $ref: "#/definitions/Config" + $ref: "#/definitions/ContainerConfig" - name: "container" in: "query" description: "The ID or name of the container to commit" @@ -8458,6 +8521,198 @@ paths: format: "int64" required: true tags: ["Secret"] + /configs: + get: + summary: "List configs" + operationId: "ConfigList" + produces: + - "application/json" + responses: + 200: + description: "no error" + schema: + type: "array" + items: + $ref: "#/definitions/Config" + example: + - ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "server.conf" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + 503: + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "filters" + in: "query" + type: "string" + description: | + A JSON encoded value of the filters (a `map[string][]string`) to process on the configs list. Available filters: + + - `id=` + - `label= or label==value` + - `name=` + - `names=` + tags: ["Config"] + /configs/create: + post: + summary: "Create a config" + operationId: "ConfigCreate" + consumes: + - "application/json" + produces: + - "application/json" + responses: + 201: + description: "no error" + schema: + type: "object" + properties: + ID: + description: "The ID of the created config." + type: "string" + example: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + 409: + description: "name conflicts with an existing object" + schema: + $ref: "#/definitions/ErrorResponse" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + 503: + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "body" + in: "body" + schema: + allOf: + - $ref: "#/definitions/ConfigSpec" + - type: "object" + example: + Name: "server.conf" + Labels: + foo: "bar" + Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + tags: ["Config"] + /configs/{id}: + get: + summary: "Inspect a config" + operationId: "ConfigInspect" + produces: + - "application/json" + responses: + 200: + description: "no error" + schema: + $ref: "#/definitions/Config" + examples: + application/json: + ID: "ktnbjxoalbkvbvedmg1urrz8h" + Version: + Index: 11 + CreatedAt: "2016-11-05T01:20:17.327670065Z" + UpdatedAt: "2016-11-05T01:20:17.327670065Z" + Spec: + Name: "app-dev.crt" + 404: + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + 503: + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + delete: + summary: "Delete a config" + operationId: "ConfigDelete" + produces: + - "application/json" + responses: + 204: + description: "no error" + 404: + description: "config not found" + schema: + $ref: "#/definitions/ErrorResponse" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + 503: + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + required: true + type: "string" + description: "ID of the config" + tags: ["Config"] + /configs/{id}/update: + post: + summary: "Update a Config" + operationId: "ConfigUpdate" + responses: + 200: + description: "no error" + 400: + description: "bad parameter" + schema: + $ref: "#/definitions/ErrorResponse" + 404: + description: "no such config" + schema: + $ref: "#/definitions/ErrorResponse" + 500: + description: "server error" + schema: + $ref: "#/definitions/ErrorResponse" + 503: + description: "node is not part of a swarm" + schema: + $ref: "#/definitions/ErrorResponse" + parameters: + - name: "id" + in: "path" + description: "The ID or name of the config" + type: "string" + required: true + - name: "body" + in: "body" + schema: + $ref: "#/definitions/ConfigSpec" + description: "The spec of the config to update. Currently, only the Labels field can be updated. All other fields must remain unchanged from the [ConfigInspect endpoint](#operation/ConfigInspect) response values." + - name: "version" + in: "query" + description: "The version number of the config object being updated. This is required to avoid conflicting writes." + type: "integer" + format: "int64" + required: true + tags: ["Config"] /distribution/{name}/json: get: summary: "Get image information from the registry" From 513bac34fe8e2050c6284048cc4ed8c7ffc4df27 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 19 Jul 2017 16:08:38 +0200 Subject: [PATCH 7/7] Improve API docs for UsageData The docs did not mention when this information was set, and what the `-1` value indicated. Signed-off-by: Sebastiaan van Stijn (cherry picked from commit 194f635ce7d097f550986bc3169ab59158f5aa68) Signed-off-by: Sebastiaan van Stijn --- components/engine/api/swagger.yaml | 22 ++++++++++++++++------ components/engine/api/types/volume.go | 14 +++++++++++--- 2 files changed, 27 insertions(+), 9 deletions(-) diff --git a/components/engine/api/swagger.yaml b/components/engine/api/swagger.yaml index 346e40b43f..89619ac31d 100644 --- a/components/engine/api/swagger.yaml +++ b/components/engine/api/swagger.yaml @@ -1078,17 +1078,27 @@ definitions: type: "string" UsageData: type: "object" + x-nullable: true required: [Size, RefCount] + description: | + Usage details about the volume. This information is used by the + `GET /system/df` endpoint, and omitted in other endpoints. properties: Size: type: "integer" - description: "The disk space used by the volume (local driver only)" default: -1 + description: | + Amount of disk space used by the volume (in bytes). This information + is only available for volumes created with the `"local"` volume + driver. For volumes created with other volume drivers, this field + is set to `-1` ("not available") x-nullable: false RefCount: type: "integer" default: -1 - description: "The number of containers referencing this volume." + description: | + The number of containers referencing this volume. This field + is set to `-1` if the reference-count is not available. x-nullable: false example: @@ -5881,13 +5891,13 @@ paths: - Name: "my-volume" Driver: "local" - Mountpoint: "" + Mountpoint: "/var/lib/docker/volumes/my-volume/_data" Labels: null - Scope: "" + Scope: "local" Options: null UsageData: - Size: 0 - RefCount: 0 + Size: 10920104 + RefCount: 2 500: description: "server error" schema: diff --git a/components/engine/api/types/volume.go b/components/engine/api/types/volume.go index da4f8ebd9c..71813be538 100644 --- a/components/engine/api/types/volume.go +++ b/components/engine/api/types/volume.go @@ -44,15 +44,23 @@ type Volume struct { UsageData *VolumeUsageData `json:"UsageData,omitempty"` } -// VolumeUsageData volume usage data +// VolumeUsageData Usage details about the volume. This information is used by the +// `GET /system/df` endpoint, and omitted in other endpoints. +// // swagger:model VolumeUsageData type VolumeUsageData struct { - // The number of containers referencing this volume. + // The number of containers referencing this volume. This field + // is set to `-1` if the reference-count is not available. + // // Required: true RefCount int64 `json:"RefCount"` - // The disk space used by the volume (local driver only) + // Amount of disk space used by the volume (in bytes). This information + // is only available for volumes created with the `"local"` volume + // driver. For volumes created with other volume drivers, this field + // is set to `-1` ("not available") + // // Required: true Size int64 `json:"Size"` }