diff --git a/website/content/docs/enterprise/index.mdx b/website/content/docs/enterprise/index.mdx index 0903b522cc..15c51bad91 100644 --- a/website/content/docs/enterprise/index.mdx +++ b/website/content/docs/enterprise/index.mdx @@ -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. \ No newline at end of file diff --git a/website/content/docs/enterprise/license/faq.mdx b/website/content/docs/enterprise/license/faq.mdx new file mode 100644 index 0000000000..2147b2f1f6 --- /dev/null +++ b/website/content/docs/enterprise/license/faq.mdx @@ -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) + + + +- [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. diff --git a/website/content/docs/enterprise/license/overview.mdx b/website/content/docs/enterprise/license/overview.mdx new file mode 100644 index 0000000000..09ba358c5a --- /dev/null +++ b/website/content/docs/enterprise/license/overview.mdx @@ -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. diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index a87da54f2c..75791414d8 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -830,6 +830,19 @@ { "title": "Sentinel", "path": "enterprise/sentinel" + }, + { + "title": "License", + "routes": [ + { + "title": "Overview", + "path": "enterprise/license/overview" + }, + { + "title": "FAQ", + "path": "enterprise/license/faq" + } + ] } ] }, diff --git a/website/redirects.next.js b/website/redirects.next.js index bae01767a8..74bc816cfa 100644 --- a/website/redirects.next.js +++ b/website/redirects.next.js @@ -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',