From c8dad44c326d9d2131f94babbc535e7f442db290 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Wed, 19 Jul 2017 12:27:24 +0200 Subject: [PATCH] Add API documentation for plugable secret backends Documents the API changes introduced in 0304c98d85404fe75a1b4a35d3c111931e062f41 and 08f7cf05268782a0dd8e4c41a4cc65fdf78d09f2 Signed-off-by: Sebastiaan van Stijn --- api/swagger.yaml | 80 +++++++++++++++++++++++++++++++++---- api/types/swarm/common.go | 2 +- docs/api/version-history.md | 8 ++++ 3 files changed, 81 insertions(+), 9 deletions(-) diff --git a/api/swagger.yaml b/api/swagger.yaml index fbada93bc2..59c9fa71e6 100644 --- a/api/swagger.yaml +++ b/api/swagger.yaml @@ -2822,6 +2822,27 @@ definitions: type: "array" items: $ref: "#/definitions/Mount" + + Driver: + description: "Driver represents a driver (network, logging, secrets)." + type: "object" + required: [Name] + properties: + Name: + description: "Name of the driver." + type: "string" + x-nullable: false + example: "some-driver" + Options: + description: "Key/value map of driver-specific options." + type: "object" + x-nullable: false + additionalProperties: + type: "string" + example: + OptionA: "value for driver-specific option A" + OptionB: "value for driver-specific option B" + SecretSpec: type: "object" properties: @@ -2833,24 +2854,38 @@ definitions: type: "object" additionalProperties: type: "string" + example: + com.example.some-label: "some-value" + com.example.some-other-label: "some-other-value" Data: - description: "Base64-url-safe-encoded secret data" - type: "array" - items: - type: "string" + description: | + Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2)) + data to store as secret. + + This field is only used to _create_ a secret, and is not returned by + other endpoints. + type: "string" + example: "" + Driver: + description: "Name of the secrets driver used to fetch the secret's value from an external secret store" + $ref: "#/definitions/Driver" + Secret: type: "object" properties: ID: type: "string" + example: "blt1owaxmitz71s9v5zh81zun" Version: $ref: "#/definitions/ObjectVersion" CreatedAt: type: "string" format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" UpdatedAt: type: "string" format: "dateTime" + example: "2017-07-20T13:55:28.678958722Z" Spec: $ref: "#/definitions/SecretSpec" ConfigSpec: @@ -2865,10 +2900,10 @@ definitions: additionalProperties: type: "string" Data: - description: "Base64-url-safe-encoded config data" - type: "array" - items: - type: "string" + description: | + Base64-url-safe-encoded ([RFC 4648](https://tools.ietf.org/html/rfc4648#section-3.2)) + config data. + type: "string" Config: type: "object" properties: @@ -8460,6 +8495,20 @@ paths: items: $ref: "#/definitions/Secret" example: + - ID: "blt1owaxmitz71s9v5zh81zun" + Version: + Index: 85 + CreatedAt: "2017-07-20T13:55:28.678958722Z" + UpdatedAt: "2017-07-20T13:55:28.678958722Z" + Spec: + Name: "mysql-passwd" + Labels: + some.label: "some.value" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" - ID: "ktnbjxoalbkvbvedmg1urrz8h" Version: Index: 11 @@ -8467,6 +8516,8 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" + Labels: + foo: "bar" 500: description: "server error" schema: @@ -8530,6 +8581,11 @@ paths: Labels: foo: "bar" Data: "VEhJUyBJUyBOT1QgQSBSRUFMIENFUlRJRklDQVRFCg==" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" tags: ["Secret"] /secrets/{id}: get: @@ -8551,6 +8607,14 @@ paths: UpdatedAt: "2016-11-05T01:20:17.327670065Z" Spec: Name: "app-dev.crt" + Labels: + foo: "bar" + Driver: + Name: "secret-bucket" + Options: + OptionA: "value for driver option A" + OptionB: "value for driver option B" + 404: description: "secret not found" schema: diff --git a/api/types/swarm/common.go b/api/types/swarm/common.go index 54af82b31b..2834cf2022 100644 --- a/api/types/swarm/common.go +++ b/api/types/swarm/common.go @@ -20,7 +20,7 @@ type Annotations struct { Labels map[string]string `json:"Labels"` } -// Driver represents a driver (network, logging). +// Driver represents a driver (network, logging, secrets backend). type Driver struct { Name string `json:",omitempty"` Options map[string]string `json:",omitempty"` diff --git a/docs/api/version-history.md b/docs/api/version-history.md index e5d9d8d4ca..3fbece49ce 100644 --- a/docs/api/version-history.md +++ b/docs/api/version-history.md @@ -19,6 +19,14 @@ keywords: "API, Docker, rcli, REST, documentation" * `DELETE /secrets/(name)` now returns status code 404 instead of 500 when the secret does not exist. * `POST /secrets/create` now returns status code 409 instead of 500 when creating an already existing secret. +* `POST /secrets/create` now accepts a `Driver` struct, allowing the + `Name` and driver-specific `Options` to be passed to store a secrets + in an external secrets store. The `Driver` property can be omitted + if the default (internal) secrets store is used. +* `GET /secrets/(id)` and `GET /secrets` now return a `Driver` struct, + containing the `Name` and driver-specific `Options` of the external + secrets store used to store the secret. The `Driver` property is + omitted if no external store is used. * `POST /secrets/(name)/update` now returns status code 400 instead of 500 when updating a secret's content which is not the labels. * `POST /nodes/(name)/update` now returns status code 400 instead of 500 when demoting last node fails. * `GET /networks/(id or name)` now takes an optional query parameter `scope` that will filter the network based on the scope (`local`, `swarm`, or `global`).