mirror of https://github.com/docker/docs.git
Add information about how CA rotation works to the swarm mode PKI doc (#3439)
This commit is contained in:
Ying Li
Misty Stanley-Jones
parent
52a42bcd3e
commit
5d344c4250
|
|
@ -325,7 +325,7 @@ guides:
|
|||
- path: /engine/swarm/how-swarm-mode-works/services/
|
||||
title: How services work
|
||||
- path: /engine/swarm/how-swarm-mode-works/pki/
|
||||
title: How PKI works in swarm mode
|
||||
title: Manage swarm security with PKI
|
||||
- path: /engine/swarm/swarm-mode/
|
||||
title: Run Docker Engine in swarm mode
|
||||
- path: /engine/swarm/join-nodes/
|
||||
|
|
|
|||
|
|
@ -1,43 +1,42 @@
|
|||
---
|
||||
description: How PKI works in swarm mode
|
||||
keywords: docker, container, cluster, swarm mode, node, tls, pki
|
||||
title: How PKI works in swarm mode
|
||||
keywords: swarm, security, tls, pki,
|
||||
title: Manage swarm security with public key infrastructure (PKI)
|
||||
---
|
||||
|
||||
The swarm mode public key infrastructure (PKI) system built into Docker Engine
|
||||
The swarm mode public key infrastructure (PKI) system built into Docker
|
||||
makes it simple to securely deploy a container orchestration system. The nodes
|
||||
in a swarm use mutual Transport Layer Security (TLS) to authenticate, authorize,
|
||||
and encrypt the communications between themselves and other nodes in the swarm.
|
||||
and encrypt the communications with other nodes in the swarm.
|
||||
|
||||
When you create a swarm by running `docker swarm init`, the Docker Engine
|
||||
designates itself as a manager node. By default, the manager node generates
|
||||
itself a new root Certificate Authority (CA) along with a key pair to secure
|
||||
communications with other nodes that join the swarm. If you prefer, you can pass
|
||||
the `--external-ca` flag to specify a root CA external to the swarm. Refer to
|
||||
the [docker swarm init](../../reference/commandline/swarm_init.md) CLI
|
||||
reference.
|
||||
When you create a swarm by running `docker swarm init`, Docker designates itself
|
||||
as a manager node. By default, the manager node generates a new root Certificate
|
||||
Authority (CA) along with a key pair, which are used to secure communications
|
||||
with other nodes that join the swarm. If you prefer, you can specify your own
|
||||
externally-generated root CA, using the the `--external-ca` flag of the
|
||||
[docker swarm init](/engine/reference/commandline/swarm_init.md) command.
|
||||
|
||||
The manager node also generates two tokens to use when you join additional nodes
|
||||
to the swarm: one worker token and one manager token. Each token includes the
|
||||
digest of the root CA's certificate and a randomly generated secret. When a node
|
||||
joins the swarm, it uses the digest to validate the root CA certificate from the
|
||||
remote manager. It uses the secret to ensure the node is an approved node.
|
||||
to the swarm: one **worker token** and one **manager token**. Each token
|
||||
includes the digest of the root CA's certificate and a randomly generated
|
||||
secret. When a node joins the swarm, the joining node uses the digest to
|
||||
validate the root CA certificate from the remote manager. The remote manager
|
||||
uses the secret to ensure the joining node is an approved node.
|
||||
|
||||
Each time a new node joins the swarm, the manager issues a certificate to the
|
||||
node that contains a randomly generated node id to identify the node under the
|
||||
certificate common name (CN) and the role under the organizational unit (OU).
|
||||
The node id serves as the cryptographically secure node identity for the
|
||||
lifetime of the node in the current swarm.
|
||||
node. The certificate contains a randomly generated node ID to identify the node
|
||||
under the certificate common name (CN) and the role under the organizational
|
||||
unit (OU). The node ID serves as the cryptographically secure node identity for
|
||||
the lifetime of the node in the current swarm.
|
||||
|
||||
The diagram below illustrates how worker manager nodes and worker nodes encrypt
|
||||
communications using a minimum of TLS 1.2.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
The example below shows the information from a certificate from a worker node:
|
||||
|
||||
```bash
|
||||
```none
|
||||
Certificate:
|
||||
Data:
|
||||
Version: 3 (0x2)
|
||||
|
|
@ -53,10 +52,55 @@ Certificate:
|
|||
```
|
||||
|
||||
By default, each node in the swarm renews its certificate every three months.
|
||||
You can run `docker swarm update --cert-expiry <TIME PERIOD>` to configure the
|
||||
frequency for nodes to renew their certificates. The minimum rotation value is 1
|
||||
hour. Refer to the [docker swarm update](../../reference/commandline/swarm_update.md)
|
||||
CLI reference.
|
||||
You can configure this interval by running the `docker swarm update
|
||||
--cert-expiry <TIME PERIOD>` command. The minimum rotation value is 1 hour.
|
||||
Refer to the
|
||||
[docker swarm update](/engine/reference/commandline/swarm_update.md) CLI
|
||||
reference for details.
|
||||
|
||||
## Rotating the CA certificate
|
||||
|
||||
In the event that a cluster CA key or a manager node is compromised, you can
|
||||
rotate the swarm root CA so that none of the nodes will trust certificates
|
||||
signed by the old root CA anymore.
|
||||
|
||||
Run `docker swarm ca --rotate` to generate a new CA certificate and key. If you
|
||||
prefer, you can pass the `--ca-cert` and `--external-ca` flags to specify the
|
||||
root certificate and and to use a root CA external to the swarm. Alternately,
|
||||
you can pass the `--ca-cert` and `--ca-key` flags to specify the exact
|
||||
certificate and key you would like the swarm to use.
|
||||
|
||||
When you issue the `docker swarm ca --rotate` command, the following things
|
||||
happen in sequence:
|
||||
|
||||
1. Docker generates a cross-signed certificate. This means that a version of
|
||||
the new root CA certificate is signed with the old root CA certificate.
|
||||
This cross-signed certificate is used as an intermediate certificate for all
|
||||
new node certificates. This ensures that nodes that still trust the old root
|
||||
CA will be able to validate a certificate signed by the new CA.
|
||||
|
||||
2. In Docker 17.06 and higher, Docker also tells all nodes to immediately
|
||||
renew their TLS certificates. This process may take several minutes,
|
||||
depending on the number of nodes in the swarm.
|
||||
|
||||
> **Note**: If your swarm has nodes with different Docker versions, the
|
||||
> following two things are true:
|
||||
> - Only a manager that is running as the leader **and** running Docker 17.06
|
||||
> or higher will tell nodes to renew their TLS certificates.
|
||||
> - Only nodes running Docker 17.06 or higher will obey this directive.
|
||||
>
|
||||
> For the most predictable behavior, ensure that all swarm nodes are running
|
||||
> Docker 17.06 or higher.
|
||||
|
||||
3. After every node in the swarm has a new TLS certificate signed by the new CA,
|
||||
Docker will forget about the old CA certificate and key material, and tell
|
||||
all the nodes to trust the new CA certificate only.
|
||||
|
||||
This will also cause a change in the swarm's join tokens. The previous
|
||||
join tokens will no longer be valid.
|
||||
|
||||
From this point on, all new node certificates issued will be signed with the new
|
||||
root CA, and will not contain any intermediates.
|
||||
|
||||
## Learn More
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue