Consul OSS to ENT Process

Avatar
Frances Liu
  • Updated

Note: When upgrading multiple HashiCorp products from OSS to ENT upgrade them in this order: Consul, Vault, Nomad, Terraform.

 

Pre-work before upgrading

1) Back up your data!

Before performing any upgrades or changes, back up your data using the consul snapshot feature.You can utilize our Learn guide tutorial for step by step instructions on how to perform a backup or reference our consul snapshot command doc.

2) Obtain consul enterprise binaries

You should have received an email from HashiCorp that contains an onboarding doc. This onboarding doc contains information and credentials to retrieve your enterprise binaries. If you cannot locate your onboarding doc or are unable to access the binaries, please reach out to your CSM.

3) Learn more about enterprise licenses and how they work. Warning: you only have a short window of time to apply your enterprise license, please do not delay licensing your enterprise upgrade.

Upgrading

Step 1: Planning your upgrade path

When planning your upgrade path, it is important to answer the following questions with your team and CSM:

  • Do I simply need to upgrade from OSS --> ENT and keep the same consul version?
  • What version of consul am I currently running and is it supported? Generally, only the most recent versions of consul are supported. Please review your HashiCorp agreement. Exceptions to this rule require a conversation with your CSM.
  • Am I okay with not being on the latest version of consul? The newest version of consul offers the most compatibility, features, (operational and security) bug fixes, and stability.
  • Please read and review all of the breaking changes to plan your upgrade paths. All breaking changes are tracked here.

Step level upgrade

Step-level upgrade is the safest way to upgrade and also only way to upgrade from older consul versions. All customers operating a consul version older than 1.4.x are required to use the step-level upgrade process due to the new ACL system.

Please follow the upgrade path listed here for your versions 

 

What is the legacy ACL system? Only used for 1.3.0 and earlier

How do you migrate legacy ACLs?

Step 2: Upgrade Process

  1. Place consul binaries in each consul server
  2. Unzip and install consul using the upgrade guide: https://www.consul.io/docs/upgrading#standard-upgrades
  3. Perform a rolling restart
    • Example: server A (follower), server B (follower), and server C (leader)
      • All servers have the new binaries installed. Running consul version still returns old consul version.
      • consul leave a follower server, server A
      • systemctl stop consul Note: This will cause the cluster to go offline, do not panic. Continue with the rolling upgrade process. Error and warn messages during this period is ok.
      • systemctl start consul
      • Move on to server B. Run systemctl stop consul and systemctl start consul. Note: The cluster will still be offline and throw out error and warn messages.
      • Perform the last restart on server C the consul leader with systemctl stop consul and systemctl start consul 
      • The logs should state that it’s able to elect a leader and running consul operator raft list-peers should show a NEW consul leader.
      • Make sure that you’ve successfully upgraded using consul version on all three servers

Licensing

Consul license will auto replicate across the servers if they’re healthy and have elected a leader. Do not wait to apply the consul license otherwise it will timeout and you’ll need to do the whole process again. Learn more about licensing here.

Example of a valid consul license:

License is valid
License ID: a763ad9f-ecfa-948c-7355-5a502aeac721
Customer ID: 7e6ac3e0-f44b-23c3-c486-3264eabc4326
Expires At: 2018-06-30 06:59:59.999 +0000 UTC
Datacenter: *
Package: cHJlbWl1bQ==
Licensed Features:
    Automated Backups
    Automated Upgrades
    Enhanced Read Scalability
    Network Segments
    Redundancy Zone
    Advanced Network Federation

Note: If you feel that the expiration date is incorrect, please reach out to your CSM.

Steps

Follow the learn guide or reference the consul license command doc 

Who to reach out to if you need help

License issues - CSM

  • License validity dates
  • Unable to find enterprise binaries
  • Unable to login to enterprise binary location
  • Cannot find onboarding doc

Upgrade issues - Support

  • Review upgrade process between consul versions
  • Documentation for consul snapshot and any consul snapshot issues
  • Assistance migrating ACLs
  • Missing tokens
  • Consul loses quorum after all consul servers have been upgraded to the same version
  • Consul server cannot read license file using consul license get command
  • And more...

Articles in this section

See more

Related articles