Document locking and unlocking swarm managers #694

mdlinville · 2016-11-22T20:30:02Z

Describe the proposed changes

Document locking a swarm.

Unreleased project version

Engine 1.13

cyli · 2016-11-22T20:52:10Z

engine/swarm/swarm_manager_locking.md

+When Docker restarts or a new manager attempts to join the swarm, or whenever
+the encryption key needs to be loaded from disk to a node's memory, you must
+[unlock the swarm](swarm_manager_locking.md#unlock-a-swarm) first, using a key
+provided by you or generated by Docker when the swarm was locked. You can rotate


Users cannot provide their own key - it's similar to join tokens. It is generated by docker when you enable auto-locking, or when you rotate the unlock key.

cyli · 2016-11-22T20:58:08Z

engine/swarm/swarm_manager_locking.md

+
+When Docker restarts, the encryption key needed to encrypt and decrypt RAFT logs
+is loaded into each manager node's running memory from disk. Docker 1.13
+introduces the ability to protect the encryption key at rest by _autolocking_


It also protects the TLS key (the same unlock key is used to encrypt the TLS key) that the manager node uses to connect to the rest of the swarm, because having a mTLS connection to the rest of the swarm means that you can get all the swarm data (including secrets).

cyli · 2016-11-22T21:04:37Z

engine/swarm/swarm_manager_locking.md

+introduces the ability to protect the encryption key at rest by _autolocking_
+your swarm.
+
+When Docker restarts or a new manager attempts to join the swarm, or whenever


When a new manager joins, the unlock key does not need to be provided, because that new manager does not have any data on disk that needs to be loaded. The new manager will obtain the the unlock key from the raft leader via propagation of the rest of the raft data.

cyli · 2016-11-22T21:05:46Z

engine/swarm/swarm_manager_locking.md

+```
+
+To disable autolock, set `--autolock` to `false`. The encryption key used to
+read and write RAFT logs will be stored unencrypted on disk, so this


Maybe "The mutual TLS key and the encryption key used to ..."?

cyli · 2016-11-22T21:11:02Z

Thanks for the great work and quick turnaround on this @mstanleyjones! A couple of nitpicks, but this looks fantastic.

mdlinville · 2016-11-22T22:34:40Z

Addressed feedback so far.

diogomonica

Looks good! Left a few small nits.

diogomonica · 2016-11-22T23:04:27Z

engine/swarm/swarm_manager_locking.md

+When Docker restarts, both the TLS key used to encrypt communication among
+swarm nodes, and the key used to encrypt and decrypt RAFT logs on disk, are
+loaded into each manager node's running memory from disk. Docker 1.13 introduces
+the ability to protect the encryption key at rest by _autolocking_ your swarm.


by allowing you to take ownership of this key and require manual unlocking of your managers. We call this feature autolocking.

@diogomonica ownership of both the encryption and TLS key you mean? Or of the unlock key?

diogomonica · 2016-11-22T23:05:02Z

engine/swarm/swarm_manager_locking.md

+When Docker restarts or whenever the encryption key needs to be loaded from disk
+to a node's memory, you must
+[unlock the swarm](swarm_manager_locking.md#unlock-a-swarm) first, using a key
+generated by Docker when the swarm was locked. When a new node joins the swarm,


I don't think this When a new node joins the swarm... part.

I think making it clear here that the unlock key does not need to be provided when adding a manager (only the join token is needed, because the unlock key is propagated via the raft) could be useful - the user might think it needs to be added otherwise, if they're not sure when loading from disk is necessary.

Nitpick though, "the is" is missing a word :) Maybe "the key is propagated..."?

diogomonica · 2016-11-22T23:06:21Z

engine/swarm/swarm_manager_locking.md

+
+To disable autolock, set `--autolock` to `false`. The mutual TLS key and the
+encryption key used to read and write RAFT logs will be stored unencrypted on
+disk, so this configuration is not recommended.


so, depending on the level of security you're striving for, this configuration might not be recommended.

diogomonica · 2016-11-22T23:06:47Z

engine/swarm/swarm_manager_locking.md

+Please enter unlock key:
+```
+
+Enter the encryption key that was emitted when you locked the swarm, and the


emitted -> generated.

Well, it was generated but it was also emitted to standard output... let me see what I can do.

mdlinville · 2016-11-23T17:32:43Z

PTAL again. Thanks!

diogomonica

Getting better and better. Still a few things we should change.

diogomonica · 2016-11-23T20:21:59Z

engine/swarm/swarm_manager_locking.md

+
+When Docker restarts, both the TLS key used to encrypt communication among swarm
+nodes, and the key used to encrypt and decrypt RAFT logs on disk, are loaded
+into each manager node's running memory from disk. Docker 1.13 introduces the


drop "from disk"?

diogomonica · 2016-11-23T20:22:14Z

engine/swarm/swarm_manager_locking.md

+nodes, and the key used to encrypt and decrypt RAFT logs on disk, are loaded
+into each manager node's running memory from disk. Docker 1.13 introduces the
+ability to protect the mutual TLS encryption key and the key used to encrypt and
+decrypt RAFT logs at rest (on disk), by allowing you to take ownership of this


drop "on disk"

diogomonica · 2016-11-23T20:22:46Z

engine/swarm/swarm_manager_locking.md

+into each manager node's running memory from disk. Docker 1.13 introduces the
+ability to protect the mutual TLS encryption key and the key used to encrypt and
+decrypt RAFT logs at rest (on disk), by allowing you to take ownership of this
+key and to require manual unlocking of your managers. This feature is called


This feature is called autolock.

diogomonica · 2016-11-23T20:24:05Z

engine/swarm/swarm_manager_locking.md

+key and to require manual unlocking of your managers. This feature is called
+_autolocking_ your swarm.
+
+When Docker restarts or whenever the encryption key needs to be loaded from disk


"When a Docker restarts and needs to access the encrypted RAFT state on disk, you must..."

There aren't other motives to unlock a manager other than starting it (or restarting it).

diogomonica · 2016-11-23T20:24:17Z

engine/swarm/swarm_manager_locking.md

+generated by Docker when the swarm was locked. You can rotate this key at any time.
+
+>**Note**: You don't need to unlock the swarm when a new node joins the swarm,
+because the key is propagated to it over mutual TLS.. You only need to provide


diogomonica · 2016-11-23T20:25:49Z

engine/swarm/swarm_manager_locking.md

+    SWMKEY-1-WuYH/IX284+lRcXuoVf38viIDK3HJEKY13MIHX+tTt8
+```
+
+Record the key in a safe place.


Record -> Store?

Also add: We recommend a password manager?

diogomonica · 2016-11-23T20:26:49Z

engine/swarm/swarm_manager_locking.md

+
+Record the key in a safe place.
+
+When Docker restarts, a new manager node attempts to join the swarm, or Docker


please remove: a new manager node attempts to join the swarm

diogomonica · 2016-11-23T20:28:02Z

engine/swarm/swarm_manager_locking.md

+encryption key used to read and write RAFT logs will be stored unencrypted on
+disk. There is a trade-off between the risk of storing the encryption key
+unencrypted at rest and the convenience of being able to restart a swarm without
+needing to unlock the swarm.


without needing to unlock each manager.

There is no swarm-wide unlock. This is individual per manager (if all nodes go down, and you have a 3 manager swarm, you need to unlock each manager individually).

diogomonica · 2016-11-23T20:30:03Z

engine/swarm/swarm_manager_locking.md

+
+Consider a situation where your swarm is
+running as expected, then manager node becomes unavailable. You troubleshoot the
+problem and bring the physical node back online, but you need to rejoin the


You're not rejoining the node to the swarm. I think we should only use "join" when it's the first time a node is actually joining the swarm. Maybe rephrase:

You troubleshoot the problem and bring the physical node back online, but you need to provide the key necessary to read the encrypted credentials and RAFT logs on disk.

diogomonica · 2016-11-23T20:31:04Z

engine/swarm/swarm_manager_locking.md

+will not be able to restart the manager.
+```
+
+If you ever need to view the unlock key in this way,


Doesn't make a lot of sense, since rotating a swarm also displays the new key. I think we should remove it, or at least replace it with a warning around: please don't share this key anywhere, and store it securely, etc`

mdlinville · 2016-11-23T23:24:00Z

Addressed @diogomonica's feedback. Please let me know if you see more areas for improvement.

aaronlehmann · 2016-11-28T23:03:45Z

engine/swarm/swarm_manager_locking.md

+title: Lock your swarm to protect its encryption key
+---
+
+In Docker 1.13 and higher, the RAFT logs used by swarm managers are encrypted on


In other docs we seem to use the capitalization Raft. This is also what the paper calls it.

Good catch, thanks, It's not an acronym.

aaronlehmann · 2016-11-28T23:10:38Z

engine/swarm/swarm_manager_locking.md

+To enable autolock on an existing swarm, set the `autolock` flag to `true`.
+
+```bash
+$ docker swarm update --autolock="true"


The quotes around true are not necessary.

But do they cause a problem? I have a strong preference for using them.

It's technically valid, but it's very atypical to have double quotes there. You could also write it as docker "swarm" "update" "--autolock"=true, but people don't do that either. So it looks like there are quotation marks in an arbitrary place where they do nothing, and I think it would look strange to people who understand the shell's syntax rules.

OK, removed the quotes.

aaronlehmann · 2016-11-28T23:10:48Z

engine/swarm/swarm_manager_locking.md

+needing to unlock each manager.
+
+```bash
+$ docker swarm update --autolock="false"


The quotes around false are not necessary.

aaronlehmann · 2016-11-28T23:12:53Z

engine/swarm/swarm_manager_locking.md

+---
+
+In Docker 1.13 and higher, the RAFT logs used by swarm managers are encrypted on
+disk by default. This at-rest encryption protects your service's configuration


We always encrypt the logs, but may or may not store the key alongside them. --autolock=true sets it up not to store the key.

mdlinville · 2016-11-30T16:48:04Z

OK, I think this is ready to merge, just need some +1s.

diogomonica · 2016-12-01T04:29:09Z

LGTM

cyli · 2016-12-01T18:17:06Z

engine/swarm/swarm_manager_locking.md

+nodes, and the key used to encrypt and decrypt Raft logs on disk, are loaded
+into each manager node's memory. Docker 1.13 introduces the ability to protect
+the mutual TLS encryption key and the key used to encrypt and decrypt Raft logs
+at rest, by allowing you to take ownership of this key and to require manual


Minor nitpick: The first part of the sentence mentions 2 keys, and the second part says "take ownership of this key" - should it be "these keys"? Or is this referring to the key-encrypting-key (then unlock key) (which hasn't been mentioned before).

cyli · 2016-12-01T18:20:07Z

engine/swarm/swarm_manager_locking.md

+unlocking of your managers. This feature is called _autolock_.
+
+When Docker restarts, you must
+[unlock the swarm](swarm_manager_locking.md#unlock-a-swarm) first, using a key


Non-blocking: I don't know whether it'd be too much detail to mention that this is a key encrypting key - there are two other keys already mentioned in this section, and it might be useful to provide more disambiguation. Not sure whether it'd just be more confusing, though.

cyli · 2016-12-01T18:21:06Z

One minor nitpick, but this LGTM. Thanks @mstanleyjones!

mdlinville · 2016-12-01T22:29:22Z

Addressed @cyli feedback. If this is good to go, I will merge it after the rebase of vnext-engine branch is complete.

cyli

LGTM! (Apologies, didn't see the follow-up comment)

CE-EE Node Activate

mdlinville added this to the engine/1.13.0 milestone Nov 22, 2016

mdlinville changed the base branch from master to vnext-engine November 22, 2016 20:30

cyli reviewed Nov 22, 2016

View reviewed changes

diogomonica approved these changes Nov 22, 2016

View reviewed changes

mdlinville mentioned this pull request Nov 23, 2016

Document secrets #568

Merged

diogomonica suggested changes Nov 23, 2016

View reviewed changes

aaronlehmann reviewed Nov 28, 2016

View reviewed changes

mdlinville changed the title ~~Unlock swarm~~ Document locking and unlocking swarm managers Nov 28, 2016

aaronlehmann reviewed Nov 28, 2016

View reviewed changes

cyli reviewed Dec 1, 2016

View reviewed changes

Document swarm locking

af7dfdb

cyli approved these changes Dec 7, 2016

View reviewed changes

mdlinville merged commit 76f8872 into docker:vnext-engine Dec 9, 2016

mdlinville deleted the unlock_swarm branch December 9, 2016 17:11

mdlinville mentioned this pull request Jan 9, 2017

Document locking and unlocking of swarm managers #689

Closed

mdlinville mentioned this pull request Jan 23, 2017

Reapply pr 694 #1340

Merged

bermudezmt pushed a commit that referenced this pull request Nov 7, 2018

Merge pull request #694 from docker/node-activate-673

af40416

CE-EE Node Activate


		Record the key in a safe place.

		When Docker restarts, a new manager node attempts to join the swarm, or Docker

Document locking and unlocking swarm managers #694

Document locking and unlocking swarm managers #694

Uh oh!

Conversation

mdlinville commented Nov 22, 2016

Describe the proposed changes

Unreleased project version

Related issue

Related issue or PR in another project

Please take a look

Uh oh!

cyli Nov 22, 2016 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cyli commented Nov 22, 2016

Uh oh!

mdlinville commented Nov 22, 2016

Uh oh!

diogomonica left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdlinville commented Nov 23, 2016

Uh oh!

diogomonica left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mdlinville commented Nov 23, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

cyli Nov 22, 2016 •

edited

Loading