Skip to content

[wip] Update the --external-ca flag for swarm update/ca #1182

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
cyli wants to merge 1 commit into
base: master
Choose a base branch
from
Open

[wip] Update the --external-ca flag for swarm update/ca #1182

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion cli/command/swarm/opts.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -217,7 +217,8 @@ func parseExternalCA(caSpec string) (*swarm.ExternalCA, error) {

func addSwarmCAFlags(flags *pflag.FlagSet, opts *swarmCAOptions) {
flags.DurationVar(&opts.nodeCertExpiry, flagCertExpiry, 90*24*time.Hour, "Validity period for node certificates (ns|us|ms|s|m|h)")
flags.Var(&opts.externalCA, flagExternalCA, "Specifications of one or more certificate signing endpoints")
flags.Var(&opts.externalCA, flagExternalCA,
"Specifications of one or more certificate signing endpoints in the form: \"protocol=<protocol>,url=<url>\"")
}

func addSwarmFlags(flags *pflag.FlagSet, opts *swarmOptions) {
Expand Down
2 changes: 1 addition & 1 deletion cli/command/swarm/testdata/update-noargs.golden
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ Flags:
--autolock Change manager autolocking setting (true|false)
--cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
--dispatcher-heartbeat duration Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s)
--external-ca external-ca Specifications of one or more certificate signing endpoints
--external-ca external-ca Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"
-h, --help help for update
--max-snapshots uint Number of additional Raft snapshots to retain
--snapshot-interval uint Number of log entries between Raft snapshots (default 10000)
Expand Down
2 changes: 2 additions & 0 deletions cli/command/swarm/update_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ import (
"github.com/docker/docker/api/types"
"github.com/docker/docker/api/types/swarm"
"github.com/pkg/errors"

// Import builders to get the builder function as package function
. "github.com/docker/cli/internal/test/builders"
"gotest.tools/assert"
Expand Down Expand Up @@ -173,6 +174,7 @@ func TestSwarmUpdate(t *testing.T) {
}
cmd.SetOutput(cli.OutBuffer())
assert.NilError(t, cmd.Execute())
fmt.Println(cli.OutBuffer().String())
golden.Assert(t, cli.OutBuffer().String(), fmt.Sprintf("update-%s.golden", tc.name))
}
}
4 changes: 2 additions & 2 deletions contrib/completion/zsh/_docker
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2284,7 +2284,7 @@ __docker_swarm_subcommand() {
"($help)--availability=[Availability of the node]:availability:(active drain pause)" \
"($help)--cert-expiry=[Validity period for node certificates]:duration: " \
"($help)--dispatcher-heartbeat=[Dispatcher heartbeat period]:duration: " \
"($help)*--external-ca=[Specifications of one or more certificate signing endpoints]:endpoint: " \
"($help)*--external-ca=[Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"]:endpoint: " \
"($help)--force-new-cluster[Force create a new cluster from current state]" \
"($help)--listen-addr=[Listen address]:ip\:port: " \
"($help)--max-snapshots[Number of additional Raft snapshots to retain]" \
Expand Down Expand Up @@ -2329,7 +2329,7 @@ __docker_swarm_subcommand() {
"($help)--autolock[Enable manager autolocking]" \
"($help)--cert-expiry=[Validity period for node certificates]:duration: " \
"($help)--dispatcher-heartbeat=[Dispatcher heartbeat period]:duration: " \
"($help)*--external-ca=[Specifications of one or more certificate signing endpoints]:endpoint: " \
"($help)*--external-ca=[Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"]:endpoint: " \
"($help)--max-snapshots[Number of additional Raft snapshots to retain]" \
"($help)--snapshot-interval[Number of log entries between Raft snapshots]" \
"($help)--task-history-limit=[Task history retention limit]:limit: " && ret=0
Expand Down
33 changes: 31 additions & 2 deletions docs/reference/commandline/swarm_ca.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,15 +25,18 @@ Options:
--ca-key pem-file Path to the PEM-formatted root CA key to use for the new cluster
--cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
-d, --detach Exit immediately instead of waiting for the root rotation to converge
--external-ca external-ca Specifications of one or more certificate signing endpoints
--external-ca external-ca Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"
--help Print usage
-q, --quiet Suppress progress output
--rotate Rotate the swarm CA - if no certificate or key are provided, new ones will be generated
```

## Description

View or rotate the current swarm CA certificate. This command must target a manager node.
View or rotate the current swarm CA certificate. This command must target a manager node. If no CA certificate
is provided, a new certificate and key will be generated and used.

A CA certificate, along with either a CA key and/or an external CA URL, may optionally be provided instead.

## Examples

Expand Down Expand Up @@ -112,6 +115,32 @@ see if any nodes are down or otherwise unable to rotate TLS certificates.
Initiate the root CA rotation, but do not wait for the completion of or display the
progress of the rotation.

## `--external-ca`

Provide an external CA URL to the managers - this CA will be used to issue all new
node certificates. One or more of these flags can be passed in order to provide
multiple alternative URLs - the swarm will try each one in order before falling
back on the next. If a key and an external CA are both provided, swarm will only
use the external CA.

This flag must be passed in conjunction with the `--ca-cert` flag, to specify
which CA certificate will be used by these external URLs to sign certificates.

The only protocol currently supported for external CAs is the CFSSL signing
protocol, and the URL provided should be to the [`/api/v1/cfssl/sign`](https://github.com/cloudflare/cfssl/blob/master/doc/api/endpoint_sign.txt)
endpoint on a CFSSL server.

The URL must be HTTPS, and the TLS certificate for the external URL must be signed
by the CA certificate provided via the `--ca-cert` flag.

Example usage:

`--external-ca=protocol=cfssl,url=https://my.cfssl.server/api/v1/cfssl/sign`

External CAs can be removed though by passing an empty string, e.g.
`--external-ca=""`.


## Related commands

* [swarm init](swarm_init.md)
Expand Down
2 changes: 1 addition & 1 deletion docs/reference/commandline/swarm_init.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Options:
--cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
--data-path-addr string Address or interface to use for data path traffic (format: <ip|interface>)
--dispatcher-heartbeat duration Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s)
--external-ca external-ca Specifications of one or more certificate signing endpoints
--external-ca external-ca Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"
--force-new-cluster Force create a new cluster from current state
--help Print usage
--listen-addr node-addr Listen address (format: <ip|interface>[:port]) (default 0.0.0.0:2377)
Expand Down
24 changes: 23 additions & 1 deletion docs/reference/commandline/swarm_update.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Options:
--autolock Change manager autolocking setting (true|false)
--cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
--dispatcher-heartbeat duration Dispatcher heartbeat period (ns|us|ms|s|m|h) (default 5s)
--external-ca external-ca Specifications of one or more certificate signing endpoints
--external-ca external-ca Specifications of one or more certificate signing endpoints in the form: "protocol=<protocol>,url=<url>"
--help Print usage
--max-snapshots uint Number of additional Raft snapshots to retain
--snapshot-interval uint Number of log entries between Raft snapshots (default 10000)
Expand All @@ -41,6 +41,28 @@ Updates a swarm with new parameter values. This command must target a manager no
$ docker swarm update --cert-expiry 720h
```

## `--external-ca`

Provide an external CA URL to the managers - this CA will be used to issue all new
node certificates. One or more of these flags can be passed in order to provide
multiple alternative URLs - the swarm will try each one in order before falling
back on the next. If an external CA URL is added, swarm will only use the external CA
even if it has access to the CA key.

The only protocol currently supported for external CAs is the CFSSL signing
protocol, and the URL provided should be to the [`/api/v1/cfssl/sign`](https://github.com/cloudflare/cfssl/blob/master/doc/api/endpoint_sign.txt)
endpoint on a CFSSL server.

The URL must be HTTPS, and the TLS certificate for the external URL must be signed
by the CA certificate currently used by the swarm.

Example usage:

`--external-ca=protocol=cfssl,url=https://my.cfssl.server/api/v1/cfssl/sign`

External CAs can be removed though by passing an empty string, e.g.
`--external-ca=""`.

## Related commands

* [swarm ca](swarm_ca.md)
Expand Down