From f792b577a0740966abb084750806a70a8b56a926 Mon Sep 17 00:00:00 2001 From: Chelsea Holland Komlo Date: Wed, 11 Apr 2018 11:39:41 -0400 Subject: [PATCH 1/4] add paragraph to explain rpc_migrate_mode when migrating a cluster Update documentation on dynamically reloading TLS configuration --- website/source/guides/securing-nomad.html.md | 27 +++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/website/source/guides/securing-nomad.html.md b/website/source/guides/securing-nomad.html.md index cc96f5e81..182db1770 100644 --- a/website/source/guides/securing-nomad.html.md +++ b/website/source/guides/securing-nomad.html.md @@ -469,16 +469,31 @@ tls { ``` ## Migrating a cluster to TLS -Nomad supports dynamically reloading it's TLS configuration. To reload Nomad's -configuration, first update the configuration file and then send the Nomad -agent a SIGHUP signal. Note that this will only reload a subset of the -configuration file, including the TLS configuration. +### Reloading TLS configuration via SIGHUP + +Nomad supports dynamically reloading both client and server TLS configuration. +To reload an agent's TLS configuration, first update the TLS block in the +agent's configuration file and then send the Nomad agent a SIGHUP signal. +Note that this will only reload a subset of the configuration file, +including the TLS configuration. When reloading the configuration, if there is a change to the TLS configuration, the agent will reload all network connections and when -establishing new connections, will use the new configuration. This process -works for both upgrading and downgrading TLS (but we recommend upgrading). +establishing new connections, will use the new configuration. The agent will +also close any outstanding old connections. This process works for both +upgrading and downgrading TLS (but we recommend upgrading). +### RPC Upgrade Mode for Nomad Servers + +When migrating to TLS, the `rpc_upgrade_mode` option (default false) in the +TLS configuration for a Nomad server can be set to true. This allows a server +to accept both TLS and non-TLS connections, which is helpful to ensure that +Nomad clients are not marked for failure by a server simply because the +operator has not yet migrated that client to TLS. However, it is important to +note that `rpc_upgrade_mode` should be used ad a temporary solution in the +process of migration, and this option should be re-set to false (meaning that +the server will strictly accept only TLS connections) once the entire cluster +has been migrated. [cfssl]: https://cfssl.org/ [cfssl.json]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/cfssl.json From 8acc0129ddf1fb1f6b428d12ed8eb2c0e37dad22 Mon Sep 17 00:00:00 2001 From: Chelsea Holland Komlo Date: Wed, 11 Apr 2018 12:00:52 -0400 Subject: [PATCH 2/4] add link to rpc_upgrade_mode docs --- website/source/guides/securing-nomad.html.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/website/source/guides/securing-nomad.html.md b/website/source/guides/securing-nomad.html.md index 182db1770..03ea12440 100644 --- a/website/source/guides/securing-nomad.html.md +++ b/website/source/guides/securing-nomad.html.md @@ -485,7 +485,7 @@ upgrading and downgrading TLS (but we recommend upgrading). ### RPC Upgrade Mode for Nomad Servers -When migrating to TLS, the `rpc_upgrade_mode` option (default false) in the +When migrating to TLS, the [ `rpc_upgrade_mode` ][rpc_upgrade_mode] option (default false) in the TLS configuration for a Nomad server can be set to true. This allows a server to accept both TLS and non-TLS connections, which is helpful to ensure that Nomad clients are not marked for failure by a server simply because the @@ -502,6 +502,7 @@ has been migrated. [guide-server]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/server.hcl [heartbeat_grace]: /docs/agent/configuration/server.html#heartbeat_grace [letsencrypt]: https://letsencrypt.org/ +[rpc_upgrade_mode]: https://www.nomadproject.io/docs/agent/configuration/tls.html#rpc_upgrade_mode/ [tls]: https://en.wikipedia.org/wiki/Transport_Layer_Security [tls_block]: /docs/agent/configuration/tls.html [vagrantfile]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/Vagrantfile From 446454b26ebb7d8ccb053722af12b6c4f44128ae Mon Sep 17 00:00:00 2001 From: Chelsea Holland Komlo Date: Wed, 11 Apr 2018 13:31:10 -0400 Subject: [PATCH 3/4] code review rewording recommendations --- website/source/guides/securing-nomad.html.md | 25 +++++++++++--------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/website/source/guides/securing-nomad.html.md b/website/source/guides/securing-nomad.html.md index 03ea12440..82ce3d13a 100644 --- a/website/source/guides/securing-nomad.html.md +++ b/website/source/guides/securing-nomad.html.md @@ -477,20 +477,23 @@ agent's configuration file and then send the Nomad agent a SIGHUP signal. Note that this will only reload a subset of the configuration file, including the TLS configuration. -When reloading the configuration, if there is a change to the TLS -configuration, the agent will reload all network connections and when -establishing new connections, will use the new configuration. The agent will -also close any outstanding old connections. This process works for both -upgrading and downgrading TLS (but we recommend upgrading). +The agent reloads all its network connections when there are changes to its TLS +configuration during a config reload via SIGHUP. Any new connections +established will use the updated configuration, and any outstanding old +connections will be closed. This process works both when upgrading to TLS, or +downgrading from it, as well as rolling certificates. We recommend upgrading +to TLS. ### RPC Upgrade Mode for Nomad Servers -When migrating to TLS, the [ `rpc_upgrade_mode` ][rpc_upgrade_mode] option (default false) in the -TLS configuration for a Nomad server can be set to true. This allows a server -to accept both TLS and non-TLS connections, which is helpful to ensure that -Nomad clients are not marked for failure by a server simply because the -operator has not yet migrated that client to TLS. However, it is important to -note that `rpc_upgrade_mode` should be used ad a temporary solution in the +When migrating to TLS, the [ `rpc_upgrade_mode` ][rpc_upgrade_mode] option +(defaults to `false`) in the +TLS configuration for a Nomad server can be set to true. When set to true, +servers will accept both TLS and non-TLS connections. By accepting non-TLS +connections, operators can upgrade clients to TLS without the clients being +marked as lost because the server is rejecting the client connection due to +the connection not being over TLS. However, it is important to note that +`rpc_upgrade_mode` should be used ad a temporary solution in the process of migration, and this option should be re-set to false (meaning that the server will strictly accept only TLS connections) once the entire cluster has been migrated. From aad039905e3d6aa3f9e545ab253c46bc7b4c363f Mon Sep 17 00:00:00 2001 From: Chelsea Holland Komlo Date: Wed, 11 Apr 2018 13:36:35 -0400 Subject: [PATCH 4/4] minor spelling/punctuation fixups --- website/source/guides/securing-nomad.html.md | 21 ++++++++++---------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/website/source/guides/securing-nomad.html.md b/website/source/guides/securing-nomad.html.md index 82ce3d13a..c5ab6b937 100644 --- a/website/source/guides/securing-nomad.html.md +++ b/website/source/guides/securing-nomad.html.md @@ -480,23 +480,22 @@ including the TLS configuration. The agent reloads all its network connections when there are changes to its TLS configuration during a config reload via SIGHUP. Any new connections established will use the updated configuration, and any outstanding old -connections will be closed. This process works both when upgrading to TLS, or +connections will be closed. This process works when upgrading to TLS, downgrading from it, as well as rolling certificates. We recommend upgrading to TLS. ### RPC Upgrade Mode for Nomad Servers When migrating to TLS, the [ `rpc_upgrade_mode` ][rpc_upgrade_mode] option -(defaults to `false`) in the -TLS configuration for a Nomad server can be set to true. When set to true, -servers will accept both TLS and non-TLS connections. By accepting non-TLS -connections, operators can upgrade clients to TLS without the clients being -marked as lost because the server is rejecting the client connection due to -the connection not being over TLS. However, it is important to note that -`rpc_upgrade_mode` should be used ad a temporary solution in the -process of migration, and this option should be re-set to false (meaning that -the server will strictly accept only TLS connections) once the entire cluster -has been migrated. +(defaults to `false`) in the TLS configuration for a Nomad server can be set +to true. When set to true, servers will accept both TLS and non-TLS +connections. By accepting non-TLS connections, operators can upgrade clients +to TLS without the clients being marked as lost because the server is +rejecting the client connection due to the connection not being over TLS. +However, it is important to note that `rpc_upgrade_mode` should be used as a +temporary solution in the process of migration, and this option should be +re-set to false (meaning that the server will strictly accept only TLS +connections) once the entire cluster has been migrated. [cfssl]: https://cfssl.org/ [cfssl.json]: https://raw.githubusercontent.com/hashicorp/nomad/master/demo/vagrant/cfssl.json