Create a HashiCorp-managed cluster

This page describes how to create HashiCorp-managed clusters, which are one or more Consul server agents that are installed, configured, and managed for you by HashiCorp. To use clusters that you create and host in your own environment, refer to link self-managed clusters to HCP Consul. For more information about the differences between the two types of clusters, refer to cluster management.

Prerequisites

Before you create a Consul cluster, configure the following HCP components:

A HashiCorp virtual network (HVN)
- Create and Manage an HVN on AWS
- Create and Manage an HVN on Azure
A peering connection or transit gateway attachment
Routes for directing network traffic between the HVN and a target connection
- Routes on AWS
- Routes on Azure

Create a Consul cluster

Sign in to the HCP Portal.
Select the organization or project where you want to create the cluster. Because resources such as HVNs are associated with an individual project, you must create the cluster in the same project as the HVN peering that supports it.
Click Consul.
From the Consul Overview, click Deploy Consul.
Select HashiCorp-managed Consul and then click Get Started.
Select the cloud provider where you host your services and then click Next.
Select HCP UI Workflow and then click Next.
Choose the HVN where you want to deploy your clusters. You should configure the HVN for the same environment where your Consul agents are deployed. If an appropriate HVN for your environment does not exist, click Create new network and then create a new HVN.
Enter a name for the cluster in the Cluster ID field. The cluster ID is a unique identifier that cannot be used for other active HCP Consul clusters.
Select a cluster tier. Each tier enables a different set of Consul server features. Refer to cluster tiers for more information.
Select a cluster size. Cluster size is measured by the expected number of service instances the cluster supports. For example, a small cluster supports up to 500 service instances. For pricing information for each cluster size, refer to HCP Consul Pricing.
Choose whether the cluster should be private or public. If you want to be able to access the Consul cluster UI from an external network, select Public. For production environments, we recommend using private Consul clusters.
- Public access is less secure. We do not recommend enabling this option for production servers.
- For additional security, enable Allow select IPs only. This option lets you whitelist up to three IPV4 address ranges in CIDR notation.
Choose the Consul version for your server agents. If you do not require a specific version, we recommend choosing the default option, which is the latest release of Consul.
Click Create cluster.

HCP then begins cluster creation. It takes about 10 minutes for the operation to finish. Wait until your cluster is created before connecting clusters and deploying agents.

HCP includes an option to generate Terraform code that you can run to create a Consul cluster in AWS. The Terraform code deploys Consul to either a new VPC or an existing VPC. It also deploys a demo application that you can interact with and observe in the HCP Consul UI.

Sign in to the HCP Portal.
Select the organization or project where you want to create the cluster. Because resources such as HVNs are associated with an individual project, you must create the cluster in the same project as the HVN peering that supports it.
Click Consul.
From the Consul Overview, click Deploy Consul.
Select HashiCorp-managed Consul and then click Get Started.
Select Amazon Web Services and then click Next.
Select Terraform automation and then click Next.
If you need to create a new VPC for your cluster, click Create new VPC. Otherwise, continue with the configuration for Use an existing VPC.
Select a runtime for your cluster. HCP Consul supports EKS, EC2, and ECS runtimes for HashiCorp-managed clusters.
Choose a region from the HCP Region menu. This region is where you want to create the Consul server. If you are connecting to an existing VPC, we recommend creating the cluster in the same region as your VPC in order to reduce latency.
Under VPC Region, select a region. This region is where your existing VPC is located or where you want to create your new VPC.
Specify the networking information for the existing VPC. Specify the VPC ID, Private route table ID, Private subnet 1, and Private subnet 2, if applicable.
If you have not already generated them, click Generate service principal and key. Copy the provided code and run it in your CLI to export credentials. This step authenticates Terraform for interactions with HCP. For more information, refer to Service Principals.
Copy the Terraform configuration file generated on HCP. Save this code as main.tf in your Terraform directory.
Initialize the directory:
```
$ terraform init
```
Preview the Terraform plan:
```
$ terraform plan
```
If no adjustments are necessary, apply the configuration to build the infrastructure:
```
$ terraform apply -auto-approve
```

The building process takes about 10 minutes to complete.

After Terraform starts, the cluster appears in the list of Consul clusters in HCP. You can click the name of your cluster to view details, connect a VPC to your cluster, and access the Consul cluster’s UI.

Wait until cluster creation is complete before you proceed.

HCP includes an option to generate Terraform code that you can run to create a Consul cluster in Azure. The Terraform code deploys Consul to either a new VNet or an existing VNet. It also deploys a demo application that you can interact with and observe in the HCP Consul UI.

Sign in to the HCP Portal.
Select the organization or project where you want to create the cluster. Because resources such as HVNs are associated with an individual project, you must create the cluster in the same project as the HVN peering that supports it.
Click Consul.
From the Consul Overview, click Deploy Consul.
Select HashiCorp-managed Consul and then click Get Started.
Select Microsoft Azure and then click Next.
Select Terraform automation and then click Next.
If you need to create a new VNet for your cluster, click Create new VNet. Otherwise, continue with the configuration for Use an existing VNet.
Select a runtime for your cluster. HCP Consul supports AKS and Azure VM runtimes for HashiCorp-managed clusters.
Choose a region from the HCP Region menu. This region is where you want to create the Consul server. If you are connecting to an existing VPC, we recommend creating the cluster in the same region as your VPC in order to reduce latency.
Specify the networking information for the existing VNet. Specify the VNet name, Resource group name, Azure subscription ID, Subnet 1, and Subnet 2, if applicable.
If you have not already generated them, click Generate service principal and key. Copy the provided code and run it in your CLI to export credentials. This step authenticates Terraform for interactions with HCP. For more information, refer to Service Principals.
Copy the Terraform configuration file generated on HCP. Save this code as main.tf in your Terraform directory.
Initialize the directory:
```
$ terraform init
```
Preview the Terraform plan:
```
$ terraform plan
```
If no adjustments are necessary, apply the configuration to build the infrastructure:
```
$ terraform apply -auto-approve
```

HCP begins to create the cluster. It takes about 10 minutes for the operation to finish. Wait until your cluster is created before connecting clusters and deploying agents.

Tutorial: For step-by-step guidance on deploying HCP Consul on Azure using Terraform automation, refer to the Deploy HCP Consul with VM using Terraform tutorial.

Troubleshooting

You may encounter the following error when attempting to deploy a cluster in EKS using the code that HCP Consul provides:

Error: "exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1"

This error occurs when using outdated versions of the AWS CLI and IAM authenticator. Upgrade both to the latest version, and then run the code provided by HCP to complete the process.

Edit a cluster after creation

After you create the cluster, you can change the cluster size, edit the select IPs that can access the cluster, and update the Consul version. However, you cannot modify the cluster name, tier, or HVN after creating a cluster.

To edit an existing cluster, complete the following steps:

Sign in to the HCP Portal.
Select the organization or project where created the cluster you want to edit.
Click Consul.
From the Consul Overview, next to the cluster you want to edit, click the and then Edit cluster.

HashiCorp automatically updates your Consul clusters to fix common vulnerabilities and exposures (CVE). To learn more about upgradeing your Consul version, refer to Upgrade your network.