Upgrading Consul: OSS to Enterprise

Avatar
Frances Liu
  • Updated

The information contained in this article has been verified as up-to-date on the date of the original publication of the article.  HashiCorp endeavors to keep this information up-to-date and correct, but it makes no representations or warranties of any kind, express or implied, about the ongoing completeness, accuracy, reliability, or suitability of the information provided.

All information contained in this article is for general information purposes only.  Any reliance you place on such information as it applies to your use of your HashiCorp product is therefore strictly at your own risk.

Introduction

Upgrading Consul OSS to Enterprise is a straightforward process that can be completed in a few simple steps. Before upgrading, it is important to back up your data and obtain consul enterprise binaries. Once you have completed these steps, you can follow the instructions in the article to upgrade your Consul deployment.

This article provides a step-by-step guide to upgrading Consul OSS to Enterprise. It covers all of the important aspects of the upgrade process, including how to back up your data, obtain consul enterprise binaries, and apply your enterprise license.

If you are considering upgrading Consul OSS to Enterprise, this article is a great resource. It provides instructions that will help you get the job done quickly and easily.

Expected Outcome

After completing this guide, you should be able to successfully upgrade your Consul OSS deployment to Consul Enterprise. This means:

  • You will have a fully functional Consul Enterprise cluster.
  • You will have applied your Consul Enterprise license.
  • Your services will continue to operate without interruption.
  • You will be able to leverage the advanced features and capabilities of Consul Enterprise listed here.

Prerequisites

This section outlines essential steps to complete before upgrading Consul OSS to Enterprise.

1. Back Up Your Data (Critical)

Before making any changes, create a full backup of your existing Consul data using the consul snapshot feature. This ensures you can restore your deployment if any issues arise during the upgrade process.

2. Obtain Consul Enterprise Binaries

You should have received an onboarding email from HashiCorp with instructions and credentials to download the Consul Enterprise binaries.

  • Can't find the email or access the binaries? Contact your Hashicorp Account Manager for assistance.

3. Understand Consul Enterprise Licensing

Familiarize yourself with Consul Enterprise licensing to ensure a smooth transition. Important: You have a limited time to apply your license after installation. Please prioritize this step to avoid any service disruptions.

 

Procedure

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

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

This method is required for Consul versions older than 1.4.x due to significant changes in the Access Control List (ACL) system introduced in version 1.4. It is also generally considered the safest upgrade method for all versions.

 

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

  • Refer to the Legacy ACL Mode section on the Upgrading Specific Versions page.

How do you migrate legacy ACLs?

Step 2: Upgrade Process

  1. Place consul binaries in each consul server
  2. Unzip and install consul following the Standard Upgrades instructions
  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 the 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

Applying Your Consul Enterprise License

Once your Consul Enterprise cluster is running, apply your license promptly. The license will automatically replicate across all healthy servers in the cluster once a leader is elected.

Important: You have a limited time to apply your license after starting Consul Enterprise. Failure to do so within the timeframe will cause the license to expire, requiring you to restart the entire upgrade process.

To learn more about Consul Enterprise licensing, refer to the Consul License Guide knowledge article.

  • 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 Apply Enterprise license section of the Deployment Guide or reference the Consul License documents. 

 

Who do I reach out to if I need help?

License issues - Account Manager

  • License validity dates
  • Unable to find enterprise binaries
  • Unable to log in to enterprise binary location
  • Cannot find the onboarding documents

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...

Additional Information

 

Articles in this section

Related articles