Introduction
This article is intended to be a suggested series of checks and balances as a reference for before replacing the Vault license on Vault Enterprise nodes and clusters. This article is not intended to be a troubleshooting guide.
Prerequisites
Vault 1.11.0+ent or higher (auto loaded license)
Determine how the current license is loaded.
There are currently three different methods in which a Vault license can be loaded on a Vault server. These different methods also involve an order of precedence.
- Environment variable VAULT_LICENSE -- takes precedence over -->
- Environment variable VAULT_LICENSE_PATH -- takes precedence over -->
- license_path parameter in Vault configuration file
Considering that there are these different methods, with order of precedence, it's important to determine which of these methods is being used on the Vault servers. It is recommended that one checks for any Vault related environment variables, and the Vault configuration file for the presence of the license_path parameter.
Example command to check for environment variables on the Vault process:
sudo cat /proc/$(pgrep vault)/environ | tr '\0' '\n' | grep VAULT
If it is found that the Vault license is implemented via environment variable, the next step would be to determine where that variable is being set. Possible places to check is the Vault systemd unit file, the use of a Vault environment variables file, etc. It may also be prudent to conduct this check on every Vault node to ensure that the license is implemented in a consistent manner.
Please be aware of a caveat that exists in a Kubernetes environment in that the Vault Enterprise license may be loaded as a Kubernetes secret. Please refer to this documentation : Vault enterprise license management with Kubernetes.
Determine license features & details of the currently loaded license.
Utilise the License Status endpoint to get a detailed "report" of the license currently loaded on the server. Example command:
vault read sys/license/status -format=json
You may want to go a step further and pipe the command result to file so that you have a historical reference to the previous license that was loaded.
vault read sys/license/status -format=json > current-license.json
Sample output:
{
"request_id": "90d2b465-b618-2201-ef3c-3972xxxxx",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": {
"autoloaded": {
"expiration_time": "2025-07-03T00:00:00Z",
"features": [
"HSM",
"Performance Replication",
"DR Replication",
"MFA",
"Sentinel",
"Seal Wrapping",
"Control Groups",
"Performance Standby",
"Namespaces",
"KMIP",
"Entropy Augmentation",
"Transform Secrets Engine",
"Lease Count Quotas",
"Key Management Secrets Engine",
"Automated Snapshots",
"Key Management Transparent Data Encryption",
"Secrets Sync"
],
"license_id": "93f50218-c706-eeb7-6eed-2135xxxxx",
"performance_standby_count": 9999,
"start_time": "2023-07-03T00:00:00Z",
"termination_time": "2035-07-03T00:00:00Z"
}
......clipped
Determine the validity of the newly issued license.
Typically customers are sent an automated email containing the details of the newly issued license. It is vital that the license key be inspected and validated PRIOR to implementation. Create a Vault license file on the Vault server and copy/paste the license key into the file. Be aware that things like line breaks, the use of a word processor in the copy/paste process, word wrap, etc. all of these things can render the license key contained in the license file invalid. Hence the stressing of validating the license before continuing. To validate that the license file contains a valid license key, utilise the License Inspect utility.
Example command:
vault license inspect vault.hclic
If the file specified is valid, the output will resemble this:
Source: license_vault.txt
Product: vault
License ID: 93f50218-c706-eeb7-6eed-2135e1xxxxx
Customer ID: 547b8788-569d-cf7e-cad9-ebc5cxxxxx
Installation ID: *
Issue Time: 2023-07-03 10:19:29.365032795 +0000 UTC
Start Time: 2023-07-03 00:00:00 +0000 UTC
Expiration Time: 2025-07-03 00:00:00 +0000 UTC
Termination Time: 2035-07-03 00:00:00 +0000 UTC
{"license_id":"93f50218-c706-eeb7-6eed-2135e1xxxxx","customer_id":"547b8788-569d-cf7e-cad9-ebc5cxxxxx","installation_id":"*","issue_time":"2023-07-03T10:19:29.365032795Z","start_time":"2023-07-03T00:00:00Z","expiration_time":"2025-07-03T00:00:00Z","termination_time":"2035-07-03T00:00:00Z","flags":{"modules":["multi-dc-scale","governance-policy","advanced-data-protection","advanced-data-protection-key-management"]},"features":["HSM","Performance Replication","DR Replication","MFA","Sentinel","Seal Wrapping","Control Groups","Performance Standby","Namespaces","KMIP","Entropy Augmentation","Transform Secrets Engine","Lease Count Quotas","Key Management Secrets Engine","Automated Snapshots","Key Management Transparent Data Encryption","Secrets Sync"],"performance_standby_count":9999}
License is valid
Cross reference features between the current and new license.
Compare the features from the existing license against the features in the new license. If there are any discrepancies such as a feature is present in the currently loaded license, but is absent from the new license stop the implementation of the new license with immediate effect. Implementing a new license that is missing features that are present in the currently loaded license may have dire consequences in the Vault environment, for example an immediate halt of Performance Replication. Please reach out to your HashiCorp Accounts team for further assistance should there be a discrepancy of the features between the old and new license.
Next steps.
Once the above has been ascertained, checked and all is in order, proceed with implementing the new license on each node in the Vault cluster.
Additional Resources.
- Vault KB Article: Updating DR Secondary Licenses on Vault 1.8.x & later
- Vault Documentation: License Status
- Vault Documentation: License Inspect
- Vault Documentation: VAULT_LICENSE environment variable
- Vault Documentation: VAULT_LICENSE_PATH environment variable
- Vault Documentation: license_path in Vault configuration file
- Vault Documentation: Vault enterprise license management (Kubernetes)
- Vault Tutorial: Install a HashiCorp Enterprise license