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..9b8227fac9 100644 --- a/website/source/docs/enterprise/index.html.md +++ b/website/source/docs/enterprise/index.html.md @@ -23,3 +23,14 @@ 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). 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. 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