From 090414db151815fa4f6277e488662055601d9265 Mon Sep 17 00:00:00 2001 From: Kyle Havlovitz Date: Wed, 5 Jul 2017 23:05:22 -0700 Subject: [PATCH] Add network area TLS setting to docs --- website/source/api/operator/area.html.md | 49 ++++++++++++++++++- website/source/docs/agent/encryption.html.md | 7 ++- .../commands/operator/area.html.markdown.erb | 35 +++++++++++++ 3 files changed, 88 insertions(+), 3 deletions(-) diff --git a/website/source/api/operator/area.html.md b/website/source/api/operator/area.html.md index dbe5b57636..dfb36d0d7e 100644 --- a/website/source/api/operator/area.html.md +++ b/website/source/api/operator/area.html.md @@ -64,12 +64,16 @@ The table below shows this endpoint's support for If this list is not supplied, joining can be done with a call to the [join endpoint](#area-join) once the network area is created. +- `UseTLS` `(bool: )` - Specifies whether gossip over this area should be + encrypted with TLS if possible. + ### Sample Payload ```json { "PeerDatacenter": "dc2", - "RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ] + "RetryJoin": [ "10.1.2.3", "10.1.2.4", "10.1.2.5" ], + "UseTLS": false } ``` @@ -132,6 +136,49 @@ $ curl \ ] ``` +## Update Network Area + +This endpoint updates a network area to the given configuration. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `PUT` | `/operator/area/:uuid` | `application/json` | + +The table below shows this endpoint's support for +[blocking queries](/api/index.html#blocking-queries), +[consistency modes](/api/index.html#consistency-modes), and +[required ACLs](/api/index.html#acls). + +| Blocking Queries | Consistency Modes | ACL Required | +| ---------------- | ----------------- | ---------------- | +| `NO` | `none` | `operator:write` | + +### Parameters + +- `dc` `(string: "")` - Specifies the datacenter to query. This will default to + the datacenter of the agent being queried. This is specified as a URL query + parameter. + +- `UseTLS` `(bool: )` - Specifies whether gossip over this area should be + encrypted with TLS if possible. + +### Sample Payload + +```json +{ + "UseTLS": true +} +``` + +### Sample Request + +```text +$ curl \ + --request PUT \ + --data @payload.json \ + https://consul.rocks/v1/operator/area/8f246b77-f3e1-ff88-5b48-8ec93abf3e05 +``` + ## List Specific Network Area This endpoint lists a specific network area. diff --git a/website/source/docs/agent/encryption.html.md b/website/source/docs/agent/encryption.html.md index a100c98bec..814c89a5f2 100644 --- a/website/source/docs/agent/encryption.html.md +++ b/website/source/docs/agent/encryption.html.md @@ -123,8 +123,11 @@ options are set to `false`. HTTPS for the API can be enabled at this point by setting the [`https`](/docs/agent/options.html#http_port) port. 2. Perform a rolling restart of each agent in the cluster. After this step, TLS should be enabled everywhere but the agents will not yet be enforcing TLS. -3. Change the `verify_incoming` and `verify_outgoing` settings (as well as `verify_server_hostname` +3. (Optional, Enterprise-only) If applicable, set the `UseTLS` setting in any network areas to `true`. +This can be done either through the [`consul operator area update`](/docs/commands/operator/area.html) +command or the [Operator API](api/operator/area.html). +4. Change the `verify_incoming` and `verify_outgoing` settings (as well as `verify_server_hostname` if applicable) to `true`. -4. Perform another rolling restart of each agent in the cluster. +5. Perform another rolling restart of each agent in the cluster. At this point, full TLS encryption for RPC communication should be enabled. diff --git a/website/source/docs/commands/operator/area.html.markdown.erb b/website/source/docs/commands/operator/area.html.markdown.erb index cb93d5957c..239657a7e0 100644 --- a/website/source/docs/commands/operator/area.html.markdown.erb +++ b/website/source/docs/commands/operator/area.html.markdown.erb @@ -42,6 +42,7 @@ Subcommands: join Join Consul servers into an existing network area list List network areas members Display Consul server members present in network areas + update Update the configuration of a network area ``` If ACLs are enabled, the client will need to supply an ACL Token with `operator` @@ -67,6 +68,9 @@ where the area was created, and the peer datacenter. This is required. * `-retry-join=` Specifies the address of a Consul server to join to, such as an IP or hostname with an optional port number. This is optional and can be specified multiple times. +* `-use-tls=` Specifies whether gossip over this area should be encrypted with +TLS if possible. Must be either `true` or `false`. + The output looks like this, displaying the ID of the newly-created network area: ``` @@ -216,3 +220,34 @@ to the given server, in a human-readable format. This is computed using [network coordinates](/docs/internals/coordinates.html). The return code will indicate success or failure. + +## update + +This command updates the configuration of network area. + +Usage: `consul operator area update [options]` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +#### Command Options + +* `-id=` - Looks up the area to operate on by its ID. This can be given +instead of a peer datacenter. + +* `-peer-datacenter=` - Declares the peer Consul datacenter that will make up the other +side of this network area. Network areas always involve a pair of datacenters: the datacenter +where the area was created, and the peer datacenter. This is required. + +* `-use-tls=` Specifies whether gossip over this area should be encrypted with +TLS if possible. Must be either `true` or `false`. + +The output looks like this: + +``` +Updated area "d2872ec5-68ea-b862-b75d-0bee99aca100" +``` + +The return code will indicate success or failure. \ No newline at end of file