mirror of https://github.com/status-im/consul.git
Add licensing documentation.
This commit is contained in:
Matt Keeler
parent
cceb79cbc5
commit
7c2afd2951
|
|
@ -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": []
|
||||
}
|
||||
```
|
||||
|
|
@ -23,7 +23,7 @@ no arguments:
|
|||
|
||||
```text
|
||||
$ consul
|
||||
usage: consul [--version] [--help] <command> [<args>]
|
||||
Usage: consul [--version] [--help] <command> [<args>]
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -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 <subcommand> [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 "<license blob>"
|
||||
|
||||
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
|
||||
```
|
||||
|
|
@ -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).
|
||||
|
|
|
|||
|
|
@ -51,6 +51,9 @@
|
|||
<li<%= sidebar_current("api-operator-keyring") %>>
|
||||
<a href="/api/operator/keyring.html">Keyring</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-operator-license") %>>
|
||||
<a href="/api/operator/license.html">License</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("api-operator-raft") %>>
|
||||
<a href="/api/operator/raft.html">Raft</a>
|
||||
</li>
|
||||
|
|
|
|||
|
|
@ -115,6 +115,9 @@
|
|||
<li<%= sidebar_current("docs-commands-leave") %>>
|
||||
<a href="/docs/commands/leave.html">leave</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-license") %>>
|
||||
<a href="/docs/commands/license.html">license</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-commands-lock") %>>
|
||||
<a href="/docs/commands/lock.html">lock</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue