»Create Clusters

This topic describes how to create Consul clusters using the HashiCorp Cloud Platform (HCP) interface. A cluster is a group of one or three Consul server agents hosted on HCP.

»Prerequisites

We recommend creating the following compontents prior to creating Consul clusters:

• A HashiCorp virtual network (HVN)
• A peering connection or transit gateway attachment
• Routes for directing network traffic between the HVN and a target connection

The procedure for creating and configuring these components is specific to the infrastructure environment. Refer to the following sections for instructions for your environment:

• AWS

»Demo Cluster Prerequisites

This topic includes instructions for using the HCP interface to generate sample Terraform code that creates a cluster and launches a demo application (see Create a Demo Cluster with Terraform (AWS)). Familiarity with the following components and concepts will help you effectively use quick start feature:

• Virtual private clouds (VPC), private and public subnets, availability zones, and routing tables in AWS
• Service principals in HCP
• Terraform configuration language and commands

»Create a Consul Cluster

1. If you have not already done so, log into the HashiCorp Cloud Platform and click Consul under the Services sidebar menu.

2. Click Create cluster and specify a name for the cluster in the Cluster ID field. The cluster ID is a unique identifier and cannot be used for other active HCP Consul clusters.

3. Choose the HVN where you want to deploy your clusters. The HVN should be configured for the same environment where your Consul agent clients are deployed.

   If an appropriate HVN for your environment does not exist, you can click +Create new network to create a new HVN in this step.

4. If you want to be able to access the Consul cluster UI from an external network, enable the Allow public connections from outside your selected network option. Enabling public access is less secure. We do not recommend enabling this option for production servers.

5. Choose a cluster tier. Each tier enables a different set of Consul server and client features. Different tiers and features are available for different infrastructure environments. Refer to Features Overview for additional information.

6. Choose a size for the cluster. Clusters are measureed in number of virtual CPUs and amount of RAM per service instance. A small cluster, for example, supports up to 500 service instances. Refer to HCP Consul Pricing for additional information about cluster sizes.

7. Choose the Consul version for your server agents. We recommend choosing the latest release of Consul (default) if you do not require a specific version.

8. Click Create cluster.

HCP will begin creating your cluster. The operation completes in approximately 10 minutes. See Next Steps for information about connecting clusters and deploying agents.

»Create a Demo Cluster with Terraform (AWS)

HCP includes an interface for generating Terraform code that you can run locally to create a Consul cluster in AWS. The Terraform code also deploys Consul clients to either a new VPC or to an existing VPC. It also deploys a sample application that you can interact with and observe in the HCP Consul UI. Refer to Demo Cluster Prerequisites for additional information.

Video: Watch the Automated HCP Consul Deployments with Terraform video presentation.

1. If you have not already done so, log into the HashiCorp Cloud Platform and click Consul under the Services sidebar menu.
2. Choose Quick start a development cluster from the More menu and click either the Use existing VPC or Create new VPC.
3. Choose a runtime. See Specifications for additional information about the supported runtimes.
4. Choose a region from the HCP region menu. This is where the Consul server cluster is created. If you are connecting to an existing VPC, we recommend creating the cluster in the same region as your VPC to reduce latency.
5. Choose a region from the VPC region menu. This is the region where either the new VPC is created or where your existing VPC is located. Skip the next step if you are creating a new VPC.
6. Specify the networking information for the existing VPC. Refer to the AWS documentation or contact your AWS administrator if you do not know which values to specify.
7. If you have not already done so, generate a service principal and export the client ID and client secret associated with the service principal as variables on your command line path. This enables Terraform to interact with HCP. Refer to Service Principals for details on getting these values.
8. If you have not already done so, download and install Terraform on your machine.
9. Create a local directory to store Terraform files and save a copy of the Terraform code generated by HCP in the directory, e.g., main.tf.
10. Initialize the directory:

    $ terraform init
    

    $ terraform init

    Copy
11. Preview the Terraform plan:

    $ terraform plan
    

    $ terraform plan

    Copy
12. If no adjustments are necessary, apply the configuration to begin building the infrastructure:

    $ terraform apply -auto-approve
    

    $ terraform apply -auto-approve

    Copy
    The process will take approximately 10 minutes to complete.

When the Terraform plan begins creating the cluster, the Go to cluster button will become active. Click the button to open the HCP Consul screen, which provides information about the resources associated with the cluster. Cluster creation may still be in progress. When the cluster and other components have been deployed, refer to View the Demo Cluster and Application for next steps.

Note the value of the hashicups_url output when the process finishes. You can use this URL to view the demo application.

»Edit a Cluster

You can change the Consul version and cluster tier after creating the cluster as new versions of Consul become available or as your networking needs evolve. Note that HashiCorp automatically updates your Consul clusters to fix common vulnerabilities and exposures (CVE). You cannot modify the cluster name, tier, or HVN after creating a cluster. You cannot delete clusters that are part of a federated network.

Refer to Upgrades for instructions on how to upgrade the Consul version and cluster tier.

»Delete a Cluster

You can delete clusters by choosing Delete from the ellipses menu on the Consul clusters screen.

When you delete a HCP Consul cluster, the snapshots associated with the cluster are also removed and can not be recovered. You can take a snapshot prior to deleting the cluster if you intend to restore a new cluster from this snapshot (refer to Snapshots). Note that the new cluster’s name must match the name of the deleted cluster in order to restore from this snapshot.

»Cluster Configuration Reference

The following table describes the cluster configuration options:

»Next Steps

The next steps depend on the state of your Consul deployment.

If you have not already done so, connect the HVN to your infrastructure environment and configure the routes. Refer to the instructions for your infrastructure environment:

• AWS

If you have already connected the HVN to your infrastructure environment and configured the routes (see Prerequisites), then you can generate an agent configuration file from HCP and use it to deploy Consul client agents in your environment. Refer to Deploy Clients for instructions.

»View the Demo Cluster and Application

If you followed the quick start instructions, you can use the HCP interface to view the demo cluster services and application. The quick start feature creates a cluster with public address, which we do not recommend for production.

1. Open the Access Consul menu and click Public.

2. Copy the address and open it in a browser.

   

3. You will need a token to log into the Consul cluster. Return to HCP and click Generate admin token in the Access Consul menu.

4. Copy the token string when prompted and return to the Consul UI browser window.

5. Click Login and paste the token into the password field.

The Consul UI will show the services deployed to the cluster.

Refer to the Consul documentation for additional information about navigating the Consul UI and using Consul features.

When Terraform finishes creating the artifacts, it will print the URL for HashiCups, the demo application, to the console.

Outputs:

consul_root_token = <sensitive>
consul_url = "https://consul-quickstart-1650389086588.consul.98a0dcc3-5473-4e4d-a28e-6c343c498530.aws.hashicorp.cloud"
hashicups_url = "http://a9142b8a018644f3c89a198bc1d64a21-531195438.us-west-2.elb.amazonaws.com"
kubeconfig_filename = "/Users/hashicorp/hcp-docs-verify/kubeconfig_consul-quickstart-1650389086588-eks"
next_steps = "Hashicups Application will be ready in ~2 minutes. Use 'terraform output consul_root_token' to retrieve the root token."

Outputs:
consul_root_token = <sensitive>consul_url = "https://consul-quickstart-1650389086588.consul.98a0dcc3-5473-4e4d-a28e-6c343c498530.aws.hashicorp.cloud"hashicups_url = "http://a9142b8a018644f3c89a198bc1d64a21-531195438.us-west-2.elb.amazonaws.com"kubeconfig_filename = "/Users/hashicorp/hcp-docs-verify/kubeconfig_consul-quickstart-1650389086588-eks"next_steps = "Hashicups Application will be ready in ~2 minutes. Use 'terraform output consul_root_token' to retrieve the root token."

Copy the URL to a browser window to explore the application.