This article demonstrates and explains how to migrate Vault Community Edition (hereon, CE) to Enterprise (hereon, ENT) with the help of the 'yum' package manager.
The article was tested considering that integrated storage (hereon, RAFT) was used as a storage backend to Vault from the very first moment when the CE version was deployed through yum.
Pre-requisites
The article was tested on "amazon/RHEL-9.4.0_HVM-20240605-x86_64" considering the following:
- The latest available version of Vault CE i.e., v1.17.5, at that time, is installed through yum. Here is the published document for reference on how to install Vault CE.
- A 1-node cluster was set up to demonstrate this approach with Shamir as the only unseal mechanism.
CE Setup
- The CE installation comes with the following files at these default locations:
-
/usr/lib/systemd/system/vault.service
-
/etc/vault.d/vault.env
-
/etc/vault.d/vault.hcl
-
/usr/bin/vault
-
/opt/vault/data
-
/opt/vault/tls
-
-
Please update the vault.hcl file to include the RAFT stanza, enable the Vault unit file using 'systemd', start the Vault services, initialize Vault, unseal it, and Vault CE is up and running fine.
- The user created by the yum package manager, that'll be used by the Vault service is named "vault", and its details can be found through the following command (values may be different for every individual installation):
# lslogins vault
Username: vault
UID: 995
Gecos field:
Home directory: /home/vault
Shell: /bin/false
No login: no
Password is locked: yes
Password not required (empty): yes
Login by password disabled: no
Primary group: vault
GID: 992
Last terminal:
Last hostname:
Hushed: no
Password changed: Aug30/00:00
Running processes: 1
Migration to ENT
First & quick Approach:
- First, we need to stop the running Vault CE service.
- run "sudo yum swap vault-enterprise vault" to replace the current CE binary with the ENT binary. This command will completely remove the CE yum package and install the ENT package.
- Restart the Vault service and unseal as needed for the ENT binary to take the charge.
Second Approach:
- First, we need to stop the running Vault CE service.
-
Rename the existing files except the files & folders inside /opt/vault/ because the /opt/vault/data contains the data created for Vault when CE was running. Following are the reference commands:
-
sudo mv /usr/lib/systemd/system/vault.service /usr/lib/systemd/system/vault-oss.service
-
sudo mv /etc/vault.d/vault.env /etc/vault.d/vault-oss.env ENT binary
-
sudo mv /etc/vault.d/vault.hcl /etc/vault.d/vault-oss.hcl
-
sudo mv /usr/bin/vault /usr/bin/vault-oss
-
-
Remove the Vault CE package by running "sudo yum remove vault".
-
Install the Vault ENT package by running "sudo yum -y install vault-enterprise".
-
Update the config file (/etc/vault.d/vault.hcl) that came with the installation of the Vault ENT package with at least the following details:
-
License (make sure the license file is created and a key is supplied (predetermined path can be referred from the file /etc/vault.d/vault.hcl)).
-
The storage stanza, as similar to that of the CE config file (/etc/vault.d/vault-oss.hcl).
-
Disable Mlock (disable_mlock = true)
-
Disable Seal Wrapping (disable_sealwrap = true)
-
-
Start the Vault ENT services, because the unit file with the name "vault.services" is already enabled, and the user named "vault" already exists, and unseal it.
- Once the Vault ENT services are back up and running, enable the seal wrapping back again.
Important
- If in case you encounter a permission denied error, please make use of "chmod" and "chown" to update the appropriate permissions and access for the user "vault" on all the paths containing the relevant files.
- Once migrated to ENT from the CE Vault version, it is not recommended to switch back to the CE version. Henceforth, you can delete the files having "-oss" as the text in them if you want.
- For an 'n-node' cluster (3-node let's say), the migration process remains the same for individual nodes but the services will back up only after at minimum 2 nodes are up and running with the ENT binary.