Frequently Asked Questions (FAQ)

This FAQ is for the license changes introduced in Consul Enterprise version 1.10.0. Consul Enterprise automatically loads Consul licenses when the server agent starts.

Q: Can I get a quick summary of the Consul changes?

Starting with Consul Enterprise 1.10.0, the license enablement process is different.

HashiCorp Enterprise servers will no longer start without a license. Servers require licenses to be provided 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 are the upgrade requirements?

All customers on Consul Enterprise 1.8/1.9 must first upgrade their client and server agents to the latest patch release. During the upgrade the license file must also be configured on client agents in an environment variable or file path, otherwise the Consul agents will fail to retrieve the license with a valid agent token. The upgrade process varies if ACLs are enabled or disabled in the cluster. Refer to the instructions on upgrading to 1.10.x for details.

Q: Is there a tutorial available for the license configuration steps?

Please visit the Enterprise License Tutorial.

Q: What resources are available?

The list below is a great starting point for learning more about the license changes introduced in Consul Enterprise 1.10.0+ent.

Q: Do these changes impact all customers/licenses?

The license changes introduced in 1.10.0 only affect Consul Enterprise. This impacts customers that have an enterprise binary (trial or non-trial licenses) downloaded from https://releases.hashicorp.com. The license changes do not impact customers with the baked-in licensed binaries. 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, 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 Enterprise 1.10.0+ent. All Consul Enterprise clusters using 1.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 trial licenses due to this change?

Consul Enterprise 1.10.0+ server agents require a valid license to start. The license can be provided on disk (auto-loaded) or as an environment variable. There is no longer a 6-hour trial period in which Consul Enterprise server agents can operate without a license.

Q: Is there a grace period when licenses expire?

Yes—Consul will continue normal operation after license expiration as defined in expiration_time. As license expiration is approached or passed, Consul will issue warnings in the system logs.

Consul will only cease operation after license termination, which occurs 10 years after license expiration and is defined in termination_time.

Q: Does this affect client agents?

There are upgrade requirements that affect Consul Enterprise clients. Please review the upgrade requirements documentation.

Q: Does this affect snapshot agents?

Same behavior as Consul clients. See answer for Does this affect client agents?

Q: What is the behavior if the license is missing?

Consul server agents will detect the absence of the license and immediately exit.

Consul client agents will attempt to retrieve the license from servers if certain conditions are met:

  • ACLs are enabled.
  • An ACL token is provided to the client agent.
  • The client agents configuration contains start_join/retry_join addresses.
  • The start/retry join addresses are addresses of the Consul servers.

Consul snapshot agents will attempt to retrieve the license from servers if certain conditions are met: ACLs are enabled, a ACL token is provided to the client agent, the client agents configuration contains start_join/retry_join addresses, the start/retry join addresses are addresses of the Consul servers.

Q: Where can users get a trial license for Consul Enterprise?

Visit consul.io/trial for a free 30-day trial license.

Trial install will cease operation 24 hours after 30-day license expiration: Trial licenses are not meant to be used in production. This is unlike non-trial licenses which provide a 10 year grace period as described in the answer for Q: Is there a grace period when licenses expire?.

Q: How can I renew a license?

Contact your organization’s HashiCorp account team or email support-softwaredelivery@hashicorp.com for information on how to renew your organization’s enterprise license.

Q: I’m an existing enterprise customer but don’t have my license, how can I get it?

Contact your organization’s HashiCorp account team or email support-softwaredelivery@hashicorp.com for information on how to renew your organization’s enterprise license.

Q: Are the license files locked to a specific cluster?

The license files are not locked to a specific cluster or cluster node. The above changes apply to all nodes in a cluster.

Q: Will this impact HCP Consul?

This will not impact HCP Consul.

Q: Does this need to happen every time a node restarts, or is this a one-time check?

Consul Enterprise binaries starting with 1.10.0+ent, will be subject to EULA check. Release 1.10.0+ent introduces the EULA check for trial licenses (non-trial licenses already go through EULA check during contractual agreement).

The agreement to a EULA happens only once (when the user gets their license), Consul Enterprise will check for the presence of a valid license every time a node restarts.

When a customer upgrades existing clusters to a 1.10.0+ent release, they need to have a valid license to successfully upgrade. This valid license must be auto-loaded.

When a customer deploys new clusters to a 1.10.0+ent release, they need to have a valid license to successfully upgrade. This valid license must be on-disk (auto-loaded).

Q: What are the scenarios that a customer must plan for because of these changes?

New Consul cluster deployments using 1.10.0+ent will need to have a valid license on servers to successfully deploy. This valid license must be on-disk (auto-loaded) or as an environment variable. Please see the upgrade requirements.

Q: What is the migration path for customers who want to migrate from their existing license-as-applied-via-the-CLI flow to the license on disk flow?

VM

  1. Run consul license get -signed to extract the license from their running cluster. Store the license in a secure location on disk.
  2. Set up the necessary configuration so that when Consul Enterprise reboots it will have access to the required license. This could be via the client agent configuration file or an environment variable.
  3. Visit the Enterprise License Tutorial for detailed steps on how to install the license key.
  4. Follow the Consul upgrade documentation.

Kubernetes

NOTE: If you are not upgrading Consul or your Helm chart version then no action is required.

  1. In order to use Consul Enterprise 1.10.0 or greater on Kubernetes you must use version 0.32.0 or greater of the Helm chart.
  2. You should already have a Consul Enterprise license set as a Kubernetes secret. If you do not, refer to how to obtain a copy of your license. Once you have the license then create a Kubernetes secret containing the license as described in Kubernetes - Consul Enterprise.
  3. Follow the Kubernetes Upgrade Docs to upgrade. No changes to your values.yaml file are needed to enable enterprise autoloading since this support is built in to consul-helm 0.32.0 and greater.

WARNING: If you are upgrading the Helm chart but not upgrading the Consul version, you must set server.enterpriseLicense.enableLicenseAutoload: false. See Kubernetes - Consul Enterprise for more details.

Q: What is the migration path for customers who want to migrate from their existing perpetually-licensed binaries to the license on disk flow?

VM

  1. Acquire a valid Consul Enterprise license. If you are an existing HashiCorp enterprise customer you may contact your organization’s customer success manager (CSM) or email support-softwaredelivery@hashicorp.com for information on how to get your organization’s enterprise license.
  2. Store the license in a secure location on disk.
  3. Set up the necessary configuration so that when Consul Enterprise reboots it will have the required license. This could be via the client agent configuration file or an environment variable. Visit the Enterprise License Tutorial for detailed steps on how to install the license key.
  4. Follow the Consul upgrade documentation.

Kubernetes

  1. Acquire a valid Consul Enterprise license. If you are an existing HashiCorp enterprise customer you may contact your organization’s customer success manager (CSM) or email support-softwaredelivery@hashicorp.com for information on how to get your organization’s enterprise license.
  2. Set up the necessary configuration so that when Consul Enterprise reboots it will have the required license. This could be via the client agent configuration file or an environment variable. Visit the Enterprise License Tutorial for detailed steps on how to install the license key.
  3. Proceed with the helm upgrade instructions

Q: Will Consul downgrades/rollbacks work?

When downgrading to a version of Consul before 1.10.0+ent, customers will need to follow the previous process for applying an enterprise licenses to Consul Enterprise.

Q: Are there potential pitfalls when downgrading or upgrading Consul server instances?

Verify that you meet the upgrade requirements.

Assume a scenario where there are three Consul server nodes:

  • Node A: v1.9.5
  • Node B: v1.10.0 [Leader]
  • Node C: v1.9.5

The command consul license put is issued from Node A. This will result in an error due to how Consul routes calls to the server node, Node B in this example. Because Node A is a follower when the call consul license put is issued, the call will be redirected to Node B (leader). The consul license put operation will fail due to being removed from 1.10.0. This is a scenario that could occur if a customer downgrades from 1.10.0+ and the Consul leadership has not transferred back over to a node not running 1.10.0+. This also has the potential of occurring when upgrading if scheduled license updates or autoscaling groups recoveries are in place.

Q: Any impacts to Consul Kubernetes?

If you are using a Consul Enterprise version prior to 1.10.0 and decide to upgrade the Helm chart to version 0.32.0 or newer, but not the Consul version. You will need to add the following configuration.

  1. server:
  2.   enterpriseLicense:
  3.     enableLicenseAutoload: false
  1. server:
  2.   enterpriseLicense:
  3.     enableLicenseAutoload: false