From 7c2afd295171fa0adb065d3a096a740cc989740a Mon Sep 17 00:00:00 2001 From: Matt Keeler Date: Tue, 22 May 2018 12:07:13 -0400 Subject: [PATCH 1/2] Add licensing documentation. --- website/source/api/operator/license.html.md | 143 ++++++++++++++++++ website/source/docs/commands/index.html.md | 3 +- .../docs/commands/license.html.markdown.erb | 109 +++++++++++++ website/source/docs/enterprise/index.html.md | 8 + website/source/layouts/api.erb | 3 + website/source/layouts/docs.erb | 3 + 6 files changed, 268 insertions(+), 1 deletion(-) create mode 100644 website/source/api/operator/license.html.md create mode 100644 website/source/docs/commands/license.html.markdown.erb diff --git a/website/source/api/operator/license.html.md b/website/source/api/operator/license.html.md new file mode 100644 index 0000000000..c0e046e72e --- /dev/null +++ b/website/source/api/operator/license.html.md @@ -0,0 +1,143 @@ +--- +layout: api +page_title: License - Operator - HTTP API +sidebar_current: api-operator-license +description: |- + The /operator/license endpoints allow for setting and retrieving the Consul + Enterprise License. +--- + +# License - Operator HTTP API + +~> **Enterprise Only!** This API endpoint and functionality only exists in +Consul Enterprise. This is not present in the open source version of Consul. + +The licensing functionality described here is available only in +[Consul Enterprise](https://www.hashicorp.com/products/consul/) version 1.1.0 and later. + +## Getting the Consul License + +This endpoint gets information about the current license. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `GET` | `/operator/license` | `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` | `all` | `none` | + +### Parameters + +- `dc` `(string: "")` - Specifies the datacenter whose license should be retrieved. + This will default to the datacenter of the agent serving the HTTP request. + This is specified as a URL query parameter. + +### Sample Request + +```text +$ curl \ + https://consul.rocks/v1/operator/license +``` + +### Sample Response + +```json +{ + "Valid": true, + "License": { + "license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c", + "customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b", + "installation_id": "*", + "issue_time": "2018-05-21T20:03:35.911567355Z", + "start_time": "2018-05-21T04:00:00Z", + "expiration_time": "2019-05-22T03:59:59.999Z", + "product": "consul", + "flags": { + "package": "premium" + }, + "features": [ + "Automated Backups", + "Automated Upgrades", + "Enhanced Read Scalability", + "Network Segments", + "Redundancy Zone", + "Advanced Network Federation" + ], + "temporary": false + }, + "Warnings": [] +} +``` + +## Updating the Consul License + +This endpoint updates the Consul license and returns some of the +license contents as well as any warning messages regarding its validity. + +| Method | Path | Produces | +| ------ | ---------------------------- | -------------------------- | +| `PUT` | `/operator/license` | `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 whose license should be updated. + This will default to the datacenter of the agent serving the HTTP request. + This is specified as a URL query parameter. + +### Sample Payload + +The payload is the raw license blob. + +### Sample Request + +```text +$ curl \ + --request PUT \ + --data @consul.license \ + https://consul.rocks/v1/operator/license +``` + +### Sample Response + +```json +{ + "Valid": true, + "License": { + "license_id": "2afbf681-0d1a-0649-cb6c-333ec9f0989c", + "customer_id": "0259271d-8ffc-e85e-0830-c0822c1f5f2b", + "installation_id": "*", + "issue_time": "2018-05-21T20:03:35.911567355Z", + "start_time": "2018-05-21T04:00:00Z", + "expiration_time": "2019-05-22T03:59:59.999Z", + "product": "consul", + "flags": { + "package": "premium" + }, + "features": [ + "Automated Backups", + "Automated Upgrades", + "Enhanced Read Scalability", + "Network Segments", + "Redundancy Zone", + "Advanced Network Federation" + ], + "temporary": false + }, + "Warnings": [] +} +``` diff --git a/website/source/docs/commands/index.html.md b/website/source/docs/commands/index.html.md index 64e081554f..68c55a5b14 100644 --- a/website/source/docs/commands/index.html.md +++ b/website/source/docs/commands/index.html.md @@ -23,7 +23,7 @@ no arguments: ```text $ consul -usage: consul [--version] [--help] [] +Usage: consul [--version] [--help] [] Available commands are: agent Runs a Consul agent @@ -37,6 +37,7 @@ Available commands are: keyring Manages gossip layer encryption keys kv Interact with the key-value store leave Gracefully leaves the Consul cluster and shuts down + license Get/Put the Consul Enterprise license (Enterprise-only) lock Execute a command holding a lock maint Controls node or service maintenance mode members Lists the members of a Consul cluster diff --git a/website/source/docs/commands/license.html.markdown.erb b/website/source/docs/commands/license.html.markdown.erb new file mode 100644 index 0000000000..b65d171d17 --- /dev/null +++ b/website/source/docs/commands/license.html.markdown.erb @@ -0,0 +1,109 @@ +--- +layout: "docs" +page_title: "Commands: License" +sidebar_current: "docs-commands-license" +description: > + The license command provides datacenter-level management of the Consul Enterprise license. +--- + +# Consul License + +Command: `consul license` + +<%= enterprise_alert :consul %> + +The `license` command provides datacenter-level management of the Consul Enterprise license. This was added in Consul 1.1.0. + +If ACLs are enabled then a token with operator privileges may be required in +order to use this command. Requests are forwarded internally to the leader +if required, so this can be run from any Consul node in a cluster. See the +[ACL Guide](/docs/guides/acl.html#operator) for more information. + + +```text +Usage: consul license [options] [args] + + This command has subcommands for managing the Consul Enterprise license + Here are some simple examples, and more detailed examples are + available in the subcommands or the documentation. + + Install a new license from a file: + + $ consul license put @consul.license + + Install a new license from stdin: + + $ consul license put - + + Install a new license from a string: + + $ consul license put "" + + Retrieve the current license: + + $ consul license get + + For more examples, ask for subcommand help or view the documentation. + +Subcommands: + get Get the current license + put Puts a new license in the datacenter +``` + +## put + +This command sets the Consul Enterprise license. + +Usage: `consul license put [options] LICENSE` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +The output looks like this: + +``` +License is valid +License ID: 2afbf681-0d1a-0649-cb6c-333ec9f0989c +Customer ID: 0259271d-8ffc-e85e-0830-c0822c1f5f2b +Expires At: 2019-05-22 03:59:59.999 +0000 UTC +Datacenter: * +Package: premium +Licensed Features: + Automated Backups + Automated Upgrades + Enhanced Read Scalability + Network Segments + Redundancy Zone + Advanced Network Federation +``` + +## get + +This command gets the Consul Enterprise license. + +Usage: `consul license get [options]` + +#### API Options + +<%= partial "docs/commands/http_api_options_client" %> +<%= partial "docs/commands/http_api_options_server" %> + +The output looks like this: + +``` +License is valid +License ID: 2afbf681-0d1a-0649-cb6c-333ec9f0989c +Customer ID: 0259271d-8ffc-e85e-0830-c0822c1f5f2b +Expires At: 2019-05-22 03:59:59.999 +0000 UTC +Datacenter: * +Package: premium +Licensed Features: + Automated Backups + Automated Upgrades + Enhanced Read Scalability + Network Segments + Redundancy Zone + Advanced Network Federation +``` \ No newline at end of file diff --git a/website/source/docs/enterprise/index.html.md b/website/source/docs/enterprise/index.html.md index f61453a51e..402c511d42 100644 --- a/website/source/docs/enterprise/index.html.md +++ b/website/source/docs/enterprise/index.html.md @@ -23,3 +23,11 @@ increases both scalability and resilience. Features include: These features are part of [Consul Enterprise](https://www.hashicorp.com/consul.html). + +## Licensing + +Licensing capabilities were added to Consul Enterprise v1.1.0. The license is set +once for a datacenter and will automatically propagate to all nodes within the +datacenter over a period of time scaled between 1 and 20 minutes depending on the +number of nodes in the datacenter. The license can be set via the +[API](/api/operator/license.html) or the [CLI](/docs/commands/license.html). diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index 98604b12bc..72dac9af50 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -51,6 +51,9 @@ > Keyring + > + License + > Raft diff --git a/website/source/layouts/docs.erb b/website/source/layouts/docs.erb index cbe7d88023..d503bdb5da 100644 --- a/website/source/layouts/docs.erb +++ b/website/source/layouts/docs.erb @@ -115,6 +115,9 @@ > leave + > + license + > lock From f3f07967c57f8442a3571885948af74ca25578e3 Mon Sep 17 00:00:00 2001 From: Matt Keeler Date: Thu, 31 May 2018 13:58:28 -0400 Subject: [PATCH 2/2] Update docs to describe the 30 minute temp license --- website/source/docs/enterprise/index.html.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/website/source/docs/enterprise/index.html.md b/website/source/docs/enterprise/index.html.md index 402c511d42..9b8227fac9 100644 --- a/website/source/docs/enterprise/index.html.md +++ b/website/source/docs/enterprise/index.html.md @@ -30,4 +30,7 @@ Licensing capabilities were added to Consul Enterprise v1.1.0. The license is se once for a datacenter and will automatically propagate to all nodes within the datacenter over a period of time scaled between 1 and 20 minutes depending on the number of nodes in the datacenter. The license can be set via the -[API](/api/operator/license.html) or the [CLI](/docs/commands/license.html). +[API](/api/operator/license.html) or the [CLI](/docs/commands/license.html). When +Consul is first started, a 30 minute temporary license is available to allow for +time to license the datacenter. The license should be set within ten minutes of +starting the first Consul process to allow time for the license to propagate.