mirror of https://github.com/status-im/consul.git
docs: adding an faq in preperation for Consul Enterprise 1.10.0
This commit is contained in:
Karl Cardenas
parent
429f9d8bb8
commit
97bcee3be6
|
|
@ -25,65 +25,3 @@ Features include:
|
|||
|
||||
These features are part of [Consul
|
||||
Enterprise](https://www.hashicorp.com/consul).
|
||||
|
||||
## Licensing
|
||||
|
||||
All Consul Enterprise agents must be licensed when they are started. Where that license comes from will depend
|
||||
on which binary is in use, whether the agent is a server, client or snapshot agent and whether ACLs have been
|
||||
enabled for the cluster.
|
||||
|
||||
-> ** 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
|
||||
in the binary and you do not need to take further action. This is the
|
||||
most common use case.
|
||||
|
||||
In the S3 bucket you will find three Enterprise zip packages. The packages with `+pro` and
|
||||
`+prem` in the name, are the binaries that include the license. The package
|
||||
with `+ent` in the name does not include the license.
|
||||
|
||||
When using these binaries no further action is necessary to configure the license.
|
||||
|
||||
### Binaries Without Built In Licenses
|
||||
|
||||
For binaries that do not include built in licenses a license must be available at the time the agent starts.
|
||||
For server agents this means that they must either have the [`license_path`](/docs/agent/opts#license_path)
|
||||
configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or
|
||||
`CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH`
|
||||
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.
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Consul Enterprise License FAQ
|
||||
description: Frequently Asked Questions pertaining to Consul Enterprise Licensing.
|
||||
---
|
||||
|
||||
# Frequently Asked Questions (FAQ)
|
||||
|
||||
This FAQ is for the license changes introduced in Consul Enterprise version v1.10.0+ent.
|
||||
Consul Enterprise automatically load Consul licenses when a Consul server agent starts using Consul Enterprise.
|
||||
|
||||
## Q: Can I get a quick summary of the Consul changes?
|
||||
|
||||
Starting with Consul Enterprise v1.10.0, the license enablement process is different.
|
||||
|
||||
HashiCorp Enterprise servers will no longer start without a license. When the server instance initializes the license watcher, the server reads from either an environment variable or file.
|
||||
If the license is missing, invalid, or expired, the server will immediately exit.
|
||||
This check is part of the server boot-up process.
|
||||
|
||||
In previous versions of HashiCorp enterprise products, one server could distribute a license to other servers via the Raft protocol.
|
||||
This will no longer work since each server must be able to find a valid license during the startup process.
|
||||
|
||||
## Q: What resources are available?
|
||||
|
||||
The list below is a great starting point for learning more about the license changes introduced in Consul Enterprise v1.10.0+ent.
|
||||
|
||||
- [Consul Enterprise Upgrade Documentation](https://www.consul.io/docs/enterprise/upgrades)
|
||||
|
||||
- [Consul License Documentation](http://localhost:3000/docs/enterprise/license)
|
||||
|
||||
<!-- - [License configuration values documentation]() -->
|
||||
|
||||
- [Install a HashiCorp Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?in=consul/enterprise)
|
||||
|
||||
## Q: Do these changes impact all customers/licenses?
|
||||
|
||||
The license changes introduced in v1.10.0 only affect Consul Enterprise.
|
||||
This impacts customers that have an enterprise binarie (EVAL / non-EVAL licenses) downloaded from releases.hashicorp.com.
|
||||
The license changes do not, at this time, impact customers with the baked-in licensed binaries (Pro/Premium). In a later release of Consul Enterprise, baked-in binaries will be deprecated.
|
||||
|
||||
## Q: What is the product behavior change introduced by the licensing changes?
|
||||
|
||||
Starting with Consul Enterprise 1.10.0+ent, a valid license is required on-disk (auto-loading) or as an environment variable for Consul Enterprise to successfully boot-up.
|
||||
The in-storage license feature will not be supported starting with Consul Enteprise 1.10.0+ent. All Consul Enterprise clusters using v1.10.0+ent must ensure that there is a valid license on-disk (auto-loaded) or as an environment variable.
|
||||
|
||||
## Q: What is the impact on EVAL licenses due to this change?
|
||||
|
||||
The 6-hour trial period for EVAL licenses will be deprecated as of Consul Enterprise 1.10.0.
|
||||
This means that any clusters deployed with Consul 1.10.0+ent binaries will need to have a valid license on the disk (auto-loaded) or as an environment variable.
|
||||
Failure in providing a valid license key will result in the Consul server agent not starting.
|
||||
|
|
@ -0,0 +1,69 @@
|
|||
---
|
||||
layout: docs
|
||||
page_title: Consul Enterprise License
|
||||
description: Consul Enterprise License Overview.
|
||||
---
|
||||
|
||||
# Consul Enterprise License
|
||||
|
||||
## Licensing
|
||||
|
||||
All Consul Enterprise agents must be licensed when they are started. Where that license comes from will depend
|
||||
on which binary is in use, whether the agent is a server, client or snapshot agent and whether ACLs have been
|
||||
enabled for the cluster.
|
||||
|
||||
-> ** 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
|
||||
in the binary and you do not need to take further action. This is the
|
||||
most common use case.
|
||||
|
||||
In the S3 bucket you will find three Enterprise zip packages. The packages with `+pro` and
|
||||
`+prem` in the name, are the binaries that include the license. The package
|
||||
with `+ent` in the name does not include the license.
|
||||
|
||||
When using these binaries no further action is necessary to configure the license.
|
||||
|
||||
### Binaries Without Built In Licenses
|
||||
|
||||
For binaries that do not include built in licenses a license must be available at the time the agent starts.
|
||||
For server agents this means that they must either have the [`license_path`](/docs/agent/opts#license_path)
|
||||
configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or
|
||||
`CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH`
|
||||
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.
|
||||
|
|
@ -830,6 +830,19 @@
|
|||
{
|
||||
"title": "Sentinel",
|
||||
"path": "enterprise/sentinel"
|
||||
},
|
||||
{
|
||||
"title": "License",
|
||||
"routes": [
|
||||
{
|
||||
"title": "Overview",
|
||||
"path": "enterprise/license/overview"
|
||||
},
|
||||
{
|
||||
"title": "FAQ",
|
||||
"path": "enterprise/license/faq"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
|
|
@ -81,6 +81,11 @@ module.exports = [
|
|||
destination: '/docs/connect/registration/sidecar-service',
|
||||
permanent: true,
|
||||
},
|
||||
{
|
||||
source: '/docs/enterprise/license',
|
||||
destination: '/docs/enterprise/license/overview',
|
||||
permanent: true,
|
||||
},
|
||||
{
|
||||
source: '/docs/enterprise/connect-multi-datacenter',
|
||||
destination: '/docs/enterprise',
|
||||
|
|
|
|||
Loading…
Reference in New Issue