Vault
Install a HashiCorp Enterprise license
Note
This guidance for enabling an enterprise license applies to both production and development environments.
To use a HashiCorp Enterprise product, you need a valid HashiCorp license. This tutorial will guide you on the steps to enable your enterprise license to start the server. By the end of this tutorial, you will have a server instance with enterprise features enabled. If you don't have a license, see the request a license section.
Tip
This tutorial is applicable to the following HashiCorp enterprise product versions or greater. Nomad v1.1.0, Consul v1.10.0, Vault v1.8.0, and Boundary v0.13.0.
Prerequisites
Each server needs to register the enterprise license as described below. In earlier 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.
The tutorial below describes the most basic steps needed to register a license. You may need to design other steps to integrate this process into your build pipelines (such as building private disk images with Packer or using a configuration management system to distribute and install the enterprise binary and license file to your compute instances).
Install the enterprise binary
Install the enterprise binary before continuing with the tutorial. All HashiCorp binaries are in releases.hashicorp.com,
look for a binary that has +ent in the suffix of the filename.
Review the installation tutorials for each HashiCorp product:
Request a trial license
Your customer support contact can generate a trial license for any HashiCorp enterprise product. If you are an existing HashiCorp enterprise customer, you may contact your organization's customer success manager (CSM) for information on how to get your organization's enterprise license.
Enable the license
You have three options for enabling an enterprise license.
- Provide the enterprise license as a string in an environment variable.
- Save the license string to a file and reference the path with an environment variable.
- Save the license string in a file and specify the path to the file in the server's configuration file.
Add an environment variable (optional)
You can set the enterprise license for Consul by using an environment variable.
Use the enterprise license you received in the previous step and set the environment variable CONSUL_LICENSE to the license key value.
$ export CONSUL_LICENSE=02MV4UU43BK5....
Read from a file (optional)
The enterprise license can be read from a file. If you add the enterprise license to a file, you have two options for how to point the server instance to the file location. The two options are an environment variable or a server instance configuration file.
Use the enterprise license key you received in the previous step and create a file that will hold the enterprise license.
You can use the echo command to copy the content from your system's clipboard into a file.
$ echo "02MV4UU43BK5..." >> license.hclic
Verify the content copied correctly to the specified file before you move onto the next step.
$ cat license.hclic
02MV4UU43BK5...
Note
You must provide an absolute path. You can use shell variables like $HOME, but not relative paths like ~/.
The environment variable name is CONSUL_LICENSE_PATH.
Use the license file you created earlier and set the environment variable CONSUL_LICENSE_PATH to the license key path.
$ export CONSUL_LICENSE_PATH=/etc/consul.d/license.hclic
Validate the license
Run the following command to validate the contents of the license file on disk.
$ consul license inspect /etc/consul.d/license.hclic
Source: /etc/consul.d/license.hclic
Product: consul
License ID: 00000000-0000-0000-0000-000000000000
Customer ID: 00000000-0000-0000-0000-000000000000
Installation ID: *
Issue Time: 2021-04-27 10:17:21.653194654 +0000 UTC
Start Time: 2021-04-27 00:00:00 +0000 UTC
Expiration Time: 2022-04-27 00:00:00 +0000 UTC
Termination Time: 2023-04-27 00:00:00 +0000 UTC
Modules:
Global Visibility, Routing and Scale
Governance and Policy
Features:
Automated Backups
Automated Upgrades
Enhanced Read Scalability
Network Segments
Redundancy Zone
Advanced Network Federation
Namespaces
SSO
Audit Logging
Admin Partitions
License is valid
Validating the server
Start the Consul server instance.
$ consul agent -dev
==> Starting Consul agent...
Version: '1.10.0+ent'
Node ID: '93a230f3-888e-7fd7-81ea-04f6d43ab199'
Node name: 'defaultNode'
Datacenter: 'dc1' (Segment: '<all>')
Server: true (Bootstrap: false)
Client Addr: [127.0.0.1] (HTTP: 8500, HTTPS: -1, gRPC: 8502, DNS: 8600)
Cluster Addr: 127.0.0.1 (LAN: 8301, WAN: 8302)
Encrypt: Gossip: false, TLS-Outgoing: false, TLS-Incoming: false, Auto-Encrypt-TLS: false
==> Log data will now stream in as it occurs:
If the server instance started successfully, then you will receive a message stating the Consul agent started.
Look for the lines Server: true and Version: 1.10.0+ent to verify that an enterprise server is running.
Error message
The server instance will notify you if the enterprise license key is not found. If you encounter the error message below or similar, please revisit the steps above.
$ consul agent -dev
...
2021-06-03T07:29:30.220-0700 [ERROR] agent: Error starting agent: error="server agents require a license to be loaded via the configuration"
2021-06-03T07:29:30.220-0700 [INFO] agent: Exit code: code=1
Next steps
In this tutorial, you deployed a server instance for an enterprise HashiCorp product using a valid enterprise license key. You may now continue exploring other enterprise tutorials for Consul, Nomad, or Vault.