luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #10336 from hashicorp/docs/licensing-updates 

[Docs] Update documentation with information about v1.10 licensing changes.
This commit is contained in:
Matt Keeler 2021-06-03 10:50:55 -04:00 committed by GitHub
parent b99f237b3c 14ffc7331d
commit fd97cf9ecc
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 177 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/api-docs/operator/license.mdx
View File

@ -2,7 +2,7 @@
layout: api layout: api
page_title: License - Operator - HTTP API page_title: License - Operator - HTTP API
description: |- description: |-
The /operator/license endpoints allow for setting and retrieving the Consul The /operator/license endpoint allows for retrieving the Consul
Enterprise License. Enterprise License.
--- ---
@ -76,6 +76,9 @@ $ curl \
## Updating the Consul License ## Updating the Consul License
-> **Deprecated** This endpoint was removed in Consul v1.10.0 along with
the ability to manage the cluster's license via the API.
This endpoint updates the Consul license and returns some of the This endpoint updates the Consul license and returns some of the
license contents as well as any warning messages regarding its validity. license contents as well as any warning messages regarding its validity.
@ -144,6 +147,9 @@ $ curl \
## Resetting the Consul License ## Resetting the Consul License
-> **Deprecated** This endpoint was removed in Consul v1.10.0 along with
the ability to manage the cluster's license via the API.
This endpoint resets the Consul license to the license included in the Enterprise binary. If the included license is not valid, the replace will fail. This endpoint resets the Consul license to the license included in the Enterprise binary. If the included license is not valid, the replace will fail.
| Method | Path | Produces | | Method | Path | Produces |

15
website/content/commands/license.mdx
View File

@ -2,7 +2,7 @@
layout: commands layout: commands
page_title: 'Commands: License' page_title: 'Commands: License'
description: > description: >
The license command provides datacenter-level management of the Consul The license command provides a datacenter-level view of the Consul
Enterprise license. Enterprise license.
--- ---
@ -12,7 +12,10 @@ Command: `consul license`
<EnterpriseAlert /> <EnterpriseAlert />
The `license` command provides datacenter-level management of the Consul Enterprise license. This was added in Consul 1.1.0. The `license` command provides datacenter-level view of the Consul Enterprise license. This was added
in Consul 1.1.0 but Consul 1.10.0 removed the ability to set and reset the license using the CLI.
See the [licensing documentation](/docs/enterprise#licensing) for more information about
Consul Enterprise license management.
If ACLs are enabled then a token with operator privileges may be required in 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 order to use this command. Requests are forwarded internally to the leader
@ -56,6 +59,10 @@ Subcommands:
## put ## put
-> **Deprecated** The ability to manage the cluster's license via the CLI
was removed in Consul 1.10. While the CLI command still exists it will
always return an error. This command will be fully removed in a future release.
This command sets the Consul Enterprise license. This command sets the Consul Enterprise license.
Usage: `consul license put [options] LICENSE` Usage: `consul license put [options] LICENSE`
@ -116,6 +123,10 @@ Licensed Features:
## reset ## reset
-> **Deprecated** The ability to manage the cluster's license via the CLI
was removed in Consul 1.10. While the CLI command still exists it will
always return an error. This command will be fully removed in a future release.
Resets license for the datacenter to the one builtin in Consul binary, if it is still valid. Resets license for the datacenter to the one builtin in Consul binary, if it is still valid.
If the builtin license is invalid, the current one stays active. If the builtin license is invalid, the current one stays active.

18
website/content/commands/snapshot/agent.mdx
View File

@ -150,6 +150,7 @@ Usage: `consul snapshot agent [options]`
"ca_path": "", "ca_path": "",
"cert_file": "", "cert_file": "",
"key_file": "", "key_file": "",
"license_path": "",
"tls_server_name": "", "tls_server_name": "",
"log": { "log": {
"level": "INFO", "level": "INFO",
@ -378,3 +379,20 @@ $ consul snapshot agent -interval=0
Please see the [HTTP API](/api/snapshot) documentation for Please see the [HTTP API](/api/snapshot) documentation for
more details about snapshot internals. more details about snapshot internals.
## Licensing
The snapshot agent requires a license when it starts before it will perform any other
actions. This can be provided using the `license_path` configuration item, the
`CONSUL_LICENSE_PATH` environment variable or the `CONSUL_LICENSE` environment variable.
The `license_path` configuration and `CONSUL_LICENSE_PATH` variable should point to
files that contain the license whereas the `CONSUL_LICENSE` variable value should be
the contents of the license itself. If a license is present in multiple ways the
then the order of precedence is as follows:
1. `CONSUL_LICENSE` variable
2. `CONSUL_LICENSE_PATH` variable
3. `license_path` configuration.
See the [licensing documentation](/docs/enterprise#licensing) for more information about
Consul Enterprise license management.

2
website/content/docs/agent/options.mdx
View File

@ -1636,6 +1636,8 @@ bind_addr = "{{ GetPrivateInterfaces | include \"network\" \"10.0.0.0/8\" | attr
- `leave_on_terminate` If enabled, when the agent receives a TERM signal, it will send a `Leave` message to the rest of the cluster and gracefully leave. The default behavior for this feature varies based on whether or not the agent is running as a client or a server (prior to Consul 0.7 the default value was unconditionally set to `false`). On agents in client-mode, this defaults to `true` and for agents in server-mode, this defaults to `false`. - `leave_on_terminate` If enabled, when the agent receives a TERM signal, it will send a `Leave` message to the rest of the cluster and gracefully leave. The default behavior for this feature varies based on whether or not the agent is running as a client or a server (prior to Consul 0.7 the default value was unconditionally set to `false`). On agents in client-mode, this defaults to `true` and for agents in server-mode, this defaults to `false`.
- `license_path` <EnterpriseAlert inline /> This specifies the path to a file that contains the Consul Enterprise license. See the [licensing documentation](/docs/enterprise#licensing) for more information about Consul Enterprise license management.
- `limits` Available in Consul 0.9.3 and later, this is a nested - `limits` Available in Consul 0.9.3 and later, this is a nested
object that configures limits that are enforced by the agent. Prior to Consul 1.5.2, object that configures limits that are enforced by the agent. Prior to Consul 1.5.2,
this only applied to agents in client mode, not Consul servers. The following parameters this only applied to agents in client mode, not Consul servers. The following parameters

98
website/content/docs/agent/telemetry.mdx
View File

@ -249,6 +249,23 @@ Note that if servers don't restart often, then the snapshot could have grown
significantly since the last restore happened so last restore times might not significantly since the last restore happened so last restore times might not
reflect what would happen if an agent restarts now. reflect what would happen if an agent restarts now.
### License Expiration <EnterpriseAlert inline />
| Metric Name | Description | Unit | Type |
| :-------------------------------- | :--------------------------------------------------------------- | :---- | :---- |
| `consul.system.licenseExpiration` | Number of hours until the Consul Enterprise license will expire. | hours | gauge |
**Why they're important:**
This measurement indicates how many hours are left before the Consul Enterprise license expires. When the license expires some
Consul Enterprise features will cease to work. An example of this is that after expiration, it is no longer possible to create
or modify resources in non-default namespaces or to manage namespace definitions themselves even though reads of namespaced
resources will still work.
**What to look for:**
This metric should be monitored to ensure that the license doesn't expire to prevent degradation of functionality.
## Metrics Reference ## Metrics Reference
@ -256,51 +273,52 @@ This is a full list of metrics emitted by Consul.
| Metric | Description | Unit | Type | | Metric | Description | Unit | Type |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- | | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | ------- |
| `consul.acl.blocked.{check,service}.deregistration` | Increments whenever a deregistration fails for an entity (check or service) is blocked by an ACL. | requests | counter | | `consul.acl.blocked.{check,service}.deregistration` | Increments whenever a deregistration fails for an entity (check or service) is blocked by an ACL. | requests | counter |
| `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter | | `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter |
| `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer | | `consul.api.http` | Migrated from consul.http.. this samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer |
| `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter |
| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | | `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/options#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter |
| `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter |
| `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter |
| `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter |
| `consul.client.rpc.error.catalog_register.` | Increments whenever a Consul agent receives an RPC error for a catalog register request. | errors | counter | | `consul.client.rpc.error.catalog_register.` | Increments whenever a Consul agent receives an RPC error for a catalog register request. | errors | counter |
| `consul.client.api.catalog_deregister.` | Increments whenever a Consul agent receives a catalog deregister request. | requests | counter | | `consul.client.api.catalog_deregister.` | Increments whenever a Consul agent receives a catalog deregister request. | requests | counter |
| `consul.client.api.success.catalog_deregister.` | Increments whenever a Consul agent successfully responds to a catalog deregister request. | requests | counter | | `consul.client.api.success.catalog_deregister.` | Increments whenever a Consul agent successfully responds to a catalog deregister request. | requests | counter |
| `consul.client.rpc.error.catalog_deregister.` | Increments whenever a Consul agent receives an RPC error for a catalog deregister request. | errors | counter | | `consul.client.rpc.error.catalog_deregister.` | Increments whenever a Consul agent receives an RPC error for a catalog deregister request. | errors | counter |
| `consul.client.api.catalog_datacenters.` | Increments whenever a Consul agent receives a request to list datacenters in the catalog. | requests | counter | | `consul.client.api.catalog_datacenters.` | Increments whenever a Consul agent receives a request to list datacenters in the catalog. | requests | counter |
| `consul.client.api.success.catalog_datacenters.` | Increments whenever a Consul agent successfully responds to a request to list datacenters. | requests | counter | | `consul.client.api.success.catalog_datacenters.` | Increments whenever a Consul agent successfully responds to a request to list datacenters. | requests | counter |
| `consul.client.rpc.error.catalog_datacenters.` | Increments whenever a Consul agent receives an RPC error for a request to list datacenters. | errors | counter | | `consul.client.rpc.error.catalog_datacenters.` | Increments whenever a Consul agent receives an RPC error for a request to list datacenters. | errors | counter |
| `consul.client.api.catalog_nodes.` | Increments whenever a Consul agent receives a request to list nodes from the catalog. | requests | counter | | `consul.client.api.catalog_nodes.` | Increments whenever a Consul agent receives a request to list nodes from the catalog. | requests | counter |
| `consul.client.api.success.catalog_nodes.` | Increments whenever a Consul agent successfully responds to a request to list nodes. | requests | counter | | `consul.client.api.success.catalog_nodes.` | Increments whenever a Consul agent successfully responds to a request to list nodes. | requests | counter |
| `consul.client.rpc.error.catalog_nodes.` | Increments whenever a Consul agent receives an RPC error for a request to list nodes. | errors | counter | | `consul.client.rpc.error.catalog_nodes.` | Increments whenever a Consul agent receives an RPC error for a request to list nodes. | errors | counter |
| `consul.client.api.catalog_services.` | Increments whenever a Consul agent receives a request to list services from the catalog. | requests | counter | | `consul.client.api.catalog_services.` | Increments whenever a Consul agent receives a request to list services from the catalog. | requests | counter |
| `consul.client.api.success.catalog_services.` | Increments whenever a Consul agent successfully responds to a request to list services. | requests | counter | | `consul.client.api.success.catalog_services.` | Increments whenever a Consul agent successfully responds to a request to list services. | requests | counter |
| `consul.client.rpc.error.catalog_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services. | errors | counter | | `consul.client.rpc.error.catalog_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services. | errors | counter |
| `consul.client.api.catalog_service_nodes.` | Increments whenever a Consul agent receives a request to list nodes offering a service. | requests | counter | | `consul.client.api.catalog_service_nodes.` | Increments whenever a Consul agent receives a request to list nodes offering a service. | requests | counter |
| `consul.client.api.success.catalog_service_nodes.` | Increments whenever a Consul agent successfully responds to a request to list nodes offering a service. | requests | counter | | `consul.client.api.success.catalog_service_nodes.` | Increments whenever a Consul agent successfully responds to a request to list nodes offering a service. | requests | counter |
| `consul.client.api.error.catalog_service_nodes.` | Increments whenever a Consul agent receives an RPC error for request to list nodes offering a service. | requests | counter | | `consul.client.api.error.catalog_service_nodes.` | Increments whenever a Consul agent receives an RPC error for request to list nodes offering a service. | requests | counter |
| `consul.client.rpc.error.catalog_service_nodes.` | Increments whenever a Consul agent receives an RPC error for a request to list nodes offering a service. | errors | counter | | `consul.client.rpc.error.catalog_service_nodes.` | Increments whenever a Consul agent receives an RPC error for a request to list nodes offering a service.   | errors | counter |
| `consul.client.api.catalog_node_services.` | Increments whenever a Consul agent receives a request to list services registered in a node. | requests | counter | | `consul.client.api.catalog_node_services.` | Increments whenever a Consul agent receives a request to list services registered in a node.   | requests | counter |
| `consul.client.api.success.catalog_node_services.` | Increments whenever a Consul agent successfully responds to a request to list services in a node. | requests | counter | | `consul.client.api.success.catalog_node_services.` | Increments whenever a Consul agent successfully responds to a request to list services in a node.   | requests | counter |
| `consul.client.rpc.error.catalog_node_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services in a node. | errors | counter | | `consul.client.rpc.error.catalog_node_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services in a node.   | errors | counter |
| `consul.client.api.catalog_node_service_list` | Increments whenever a Consul agent receives a request to list a node's registered services. | requests | counter | | `consul.client.api.catalog_node_service_list` | Increments whenever a Consul agent receives a request to list a node's registered services. | requests | counter |
| `consul.client.rpc.error.catalog_node_service_list` | Increments whenever a Consul agent receives an RPC error for request to list a node's registered services. | errors | counter | | `consul.client.rpc.error.catalog_node_service_list` | Increments whenever a Consul agent receives an RPC error for request to list a node's registered services. | errors | counter |
| `consul.client.api.success.catalog_node_service_list` | Increments whenever a Consul agent successfully responds to a request to list a node's registered services. | requests | counter | | `consul.client.api.success.catalog_node_service_list` | Increments whenever a Consul agent successfully responds to a request to list a node's registered services. | requests | counter |
| `consul.client.api.catalog_gateway_services.` | Increments whenever a Consul agent receives a request to list services associated with a gateway. | requests | counter | | `consul.client.api.catalog_gateway_services.` | Increments whenever a Consul agent receives a request to list services associated with a gateway. | requests | counter |
| `consul.client.api.success.catalog_gateway_services.` | Increments whenever a Consul agent successfully responds to a request to list services associated with a gateway. | requests | counter | | `consul.client.api.success.catalog_gateway_services.` | Increments whenever a Consul agent successfully responds to a request to list services associated with a gateway. | requests | counter |
| `consul.client.rpc.error.catalog_gateway_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services associated with a gateway. | errors | counter | | `consul.client.rpc.error.catalog_gateway_services.` | Increments whenever a Consul agent receives an RPC error for a request to list services associated with a gateway. | errors | counter |
| `consul.runtime.num_goroutines` | Tracks the number of running goroutines and is a general load pressure indicator. This may burst from time to time but should return to a steady state value. | number of goroutines | gauge | | `consul.runtime.num_goroutines` | Tracks the number of running goroutines and is a general load pressure indicator. This may burst from time to time but should return to a steady state value. | number of goroutines | gauge |
| `consul.runtime.alloc_bytes` | Measures the number of bytes allocated by the Consul process. This may burst from time to time but should return to a steady state value. | bytes | gauge | | `consul.runtime.alloc_bytes` | Measures the number of bytes allocated by the Consul process. This may burst from time to time but should return to a steady state value. | bytes | gauge |
| `consul.runtime.heap_objects` | Measures the number of objects allocated on the heap and is a general memory pressure indicator. This may burst from time to time but should return to a steady state value. | number of objects | gauge | | `consul.runtime.heap_objects` | Measures the number of objects allocated on the heap and is a general memory pressure indicator. This may burst from time to time but should return to a steady state value. | number of objects | gauge |
| `consul.state.nodes` | Measures the current number of nodes registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge | | `consul.state.nodes` | Measures the current number of nodes registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.state.services` | Measures the current number of unique services registered with Consul, based on service name. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge | | `consul.state.services` | Measures the current number of unique services registered with Consul, based on service name. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.state.service_instances` | Measures the current number of unique service instances registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge | | `consul.state.service_instances` | Measures the current number of unique service instances registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge |
| `consul.dns.stale_queries` | Increments when an agent serves a query within the allowed stale threshold. | queries | counter | | `consul.dns.stale_queries` | Increments when an agent serves a query within the allowed stale threshold. | queries | counter |
| `consul.dns.ptr_query.` | Measures the time spent handling a reverse DNS query for the given node. | ms | timer | | `consul.dns.ptr_query.` | Measures the time spent handling a reverse DNS query for the given node. | ms | timer |
| `consul.dns.domain_query.` | Measures the time spent handling a domain query for the given node. | ms | timer | | `consul.dns.domain_query.` | Measures the time spent handling a domain query for the given node. | ms | timer |
| `consul.http...` | DEPRECATED IN 1.9: Tracks how long it takes to service the given HTTP request for the given verb and path. Paths do not include details like service or key names, for these an underscore will be present as a placeholder (eg. `consul.http.GET.v1.kv._`) | ms | timer | | `consul.http...` | DEPRECATED IN 1.9: Tracks how long it takes to service the given HTTP request for the given verb and path. Paths do not include details like service or key names, for these an underscore will be present as a placeholder (eg. `consul.http.GET.v1.kv._`) | ms | timer |
| `consul.version` | Measures the count of running agents. | agents | guage | | `consul.system.licenseExpiration` | <EnterpriseAlert inline /> This measures the number of hours remaining on the agents license. | hours | gauge |
| `consul.version` | Measures the count of running agents. | agents | guage |
## Server Health ## Server Health

64
website/content/docs/enterprise/index.mdx
View File

@ -28,13 +28,18 @@ Enterprise](https://www.hashicorp.com/consul).
## Licensing ## Licensing
Licensing capabilities were added to Consul Enterprise v1.1.0. The license is set All Consul Enterprise agents must be licensed when they are started. Where that license comes from will depend
once for a datacenter and will automatically propagate to all nodes within the on which binary is in use, whether the agent is a server, client or snapshot agent and whether ACLs have been
datacenter over a period of time scaled between 1 and 20 minutes depending on the enabled for the cluster.
number of nodes in the datacenter. There are two methods for licensing Consul
enterprise.
### Included in the Enterprise Package -> ** Consul Enterprise v1.10.0 removed temporary licensing.** In previous versions Consul Enterprise
agents could start without a license and then have a license applied to them later on via the CLI
or API. That functionality has been removed and replaced with the ability to load licenses from the
agent's configuration or environment. Also prior to v1.10.0 server agents would automatically propagate
the license between themselves. This no longer occurs and the license must be present on each server
when they are started.
### Binaries with Built In Licenses
If you are downloading Consul from Amazon S3, then the license is included If you are downloading Consul from Amazon S3, then the license is included
in the binary and you do not need to take further action. This is the in the binary and you do not need to take further action. This is the
@ -44,16 +49,41 @@ In the S3 bucket you will find three Enterprise zip packages. The packages with
`+prem` in the name, are the binaries that include the license. The package `+prem` in the name, are the binaries that include the license. The package
with `+ent` in the name does not include the license. with `+ent` in the name does not include the license.
### Applied after Bootstrapping When using these binaries no further action is necessary to configure the license.
If you are downloading the enterprise binary from the [releases.hashicorp.com](https://releases.hashicorp.com/consul/) or the `+ent` package from Amazon S3, you will need to apply ### Binaries Without Built In Licenses
the license to the cluster, after completing the bootstrapping process.
You can set the license on any agent within the cluster and it will be
forwarded to the leading server via the RPC forwarding functionality.
Below are your two options for setting the license file.
You can set the license via the For binaries that do not include built in licenses a license must be available at the time the agent starts.
[API](/api/operator/license) or the [CLI](/commands/license). When For server agents this means that they must either have the [`license_path`](/docs/agent/opts#license_path)
you first start Consul, a 30-minute temporary license is available to allow you configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or
time to license the datacenter. You should set the license within ten minutes of `CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH`
starting the first Consul process to allow time for the license to propagate. environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment
variable should contain the license as the value. If multiple of these are set the order of precedence is:
1. `CONSUL_LICENSE` environment variable
2. `CONSUL_LICENSE_PATH` environment variable
3. `license_path` configuration item.
Both client agents and the snapshot agent may also be licensed in the very same manner. However to prevent
the need to configure the license on many client agents and snapshot agents those agents have the capability
to retrieve the license automatically under specific circumstances.
#### Client Agent License Retrieval
When a client agent starts without a license in its configuration or environment, it will try to retrieve the
license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the
request but the token doesn't need any particular permissions. As the license is required before the client
actually joins the cluster, where to make those RPC requests to is inferred from the [`start_join`](/docs/agent/opts#start_join)
or [`retry_join`](/docs/agent/opts#retry_join) configurations. If those are both unset or no
[`agent` token](/docs/agent/opts#acl_tokens_agent) is set then the client agent will immediately shut itself down.
If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to
request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a
license within that time frame it will shut itself down.
#### Snapshot Agent License Retrieval
The snapshot agent has similar functionality to the client agent for automatically retrieving the license. However,
instead of requiring a server agent to talk to, the snapshot agent can request the license from the server or
client agent it would use for all other operations. It still requires an ACL token to authorize the request. Also
like client agents, the snapshot agent will shut itself down after being unable to retrieve the license for 5
minutes.

32
website/content/docs/upgrading/upgrade-specific.mdx
View File

@ -14,6 +14,38 @@ provided for their upgrades as a result of new features or changed behavior.
This page is used to document those details separately from the standard This page is used to document those details separately from the standard
upgrade flow. upgrade flow.
## Consul 1.10.0 <EnterpriseAlert inline />
Consul Enterprise 1.10 has removed temporary licensing capabilities from the binaries
found on https://releases.hashicorp.com. Servers will no longer load a license previously
set through the CLI or API. Instead the license must be present in the server's configuration
or environment prior to starting. See the [licensing documentation](/docs/enterprise#licensing)
for more information about how to configure the license. Client agents previously retrieved their
license from the servers in the cluster within 30 minutes of starting and the snapshot agent
would similarly retrieve its license from the server or client agent it was configured to use. As
of Consul Enterprise 1.10 both the snapshot agent and client agent have gained the ability to
have a license loaded from a configuration file or from their environment the same way server
agents must have the license specified. Both agents can still perform automatic retrieval of their
license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs
are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client
agents require that either the [`start_join`](/docs/agent/opts#start_join) or
[`retry_join`](/docs/agent/opts#retry_join) configurations are set and that they resolve to server
agents. If those stipulations are not met, attempting to start the client or snapshot agent will
result in it immediately shutting down.
### Migration <EnterpriseAlert inline />
Prior to upgrading Consul Enterprise to v1.10 you should ensure the license is set in all the right places.
In general following these steps should be all thats necessary to ensure a smooth upgrade.
1. Retrieve the existing license from your existing cluster by running `consul license get -signed`
2. Ensure that the license is configured on all your servers by setting the one of the `license_path`
configuration item, the `CONSUL_LICENSE_PATH` environment variable or the `CONSUL_LICENSE`
environment variable.
3. If ACLs are not in use or if not all client agents are configured with the necessary `start_join` /
`retry_join` configurations pointing to servers, then repeat step 2 for all client agents.
4. If ACLs are not in use then repeat step 2 for all snapshot agents.
5. Now proceed with the [standard upgrade procedure](/docs/upgrading#standard-upgrades).
## Consul 1.9.0 ## Consul 1.9.0
### Changes to Raft Protocol Support ### Changes to Raft Protocol Support