• Terraform Cloud
    • HCP Vault
    • HCP Consul
    • HCP Packer
  • Pricing
  • Documentation
  • Tutorials
  • Community
Sign InTry cloud for free
    • What is HCP?
      • AWS
      • Overview
        • Create and Manage HVN
        • Peering Connections
        • Transit Gateway Attachements
        • Routes
        • Security Groups
        • Overview
        • Users
        • Service Principals
        • Organizations
        • Single Sign-On
        • Multi-Factor Authentication
        • Overview
        • Payment
        • Flex Billing
      • Support
    • What is HCP Consul?
    • Specifications
      • Overview
      • Clusters
      • Clients
      • Federation
      • Upgrades
      • Audit Logs
      • Snapshots
      • Tutorials
      • Consul Documentation
      • Forums
    • Overview
    • Security Overview
    • Get Started
    • Login MFA
    • High Availability and Disaster Recovery
    • Performance Replication
    • Version Management
    • RBAC Permissions
    • Administrative Capabilities
    • Audit Log Management
      • Overview
      • FAQ
    • Metrics
    • Constraints and Known Issues
    • Migrate to HCP Vault
    • What is HCP Packer?
    • Get Started
      • Template Configuration
      • Image Metadata
      • Image Buckets
      • Image Channels and Revocation
      • Terraform Cloud Run Tasks
    • Reference Image Metadata
    • Manage Registry
    • API Reference
    • Packer Documentation
  • Glossary
  • Changelog
Type '/' to Search

»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
  11. Preview the Terraform plan:
    $ terraform plan
    
    $ terraform plan
  12. If no adjustments are necessary, apply the configuration to begin building the infrastructure:
    $ terraform apply -auto-approve
    
    $ terraform apply -auto-approve
    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:

AttributeDescriptionDefault
Cluster IDA unique identifier for your cluster, e.g. hcp-consul-cluster. This value cannot be the same as any other active HCP Consul clusters.consul-cluster
NetworkSpecifies the HVN that the containing the cluster.Defaults to first HVN on the Networks screen.
Network accessibilityEnables the Consul UI to be accessible via a public endpoint. We recommended disabling public accessibility for production use cases.Disabled
Cluster tierChoose one of the following tiers:
  • Development: Lowest tier designed for testing purposes.
  • Standard: Mid tier designed for production workloads located in a single region.
  • Plus: Highest tier designed for production workloads spanning multiple regions.
Refer to Pricing for details.
Development
Cluster sizeSpecifies the vCPU and GiB RAM configurations. Each size corresponds to a number of service instances, e.g., a small cluster supports up to 500 service instances. Extra small is only available on the development tier.Small
Consul versionSpecifies the Consul version deployed to the cluster. We recommend using the default version if your environment does not require a specific version.Latest GA version

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

    Get the cluster's public address

  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.

View the cluster in the Consul UI

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.

View HashiCups

  • Learn about HCP

    • Blog
    • Press Release
  • Resources

    • Tutorials
    • Documentation
  • Help

    • Community
    • Support
    • Contact Us
  • Terms of Service
  • SLA
  • Shared Responsibility Model
  • Privacy
  • Security
  • Press Kit
©2021 HashiCorp, Inc. All rights reserved