Get started with end-to-end deployment configuration

13min
|
HCP
Terraform
Consul
Video

HashiCorp Cloud Platform (HCP) Consul is a fully managed Service Mesh as a Service (SMaaS) version of Consul. While you can deploy a HCP Consul Dedicated server and connect the Consul clients in your cloud environments manually, using Terraform significantly reduces deployment time.

The HCP Portal has a quickstart template that uses Terraform modules to deploy an end-to-end development environment so you can quickly use HCP Consul Dedicated. With this configuration, you can create a development environment and launch HashiCups, an example application consisting of five different microservices, in less than 30 min.

You do not need to be an expert with Terraform to run these end-to-end deployments.

This video provides an overview of the tutorials in this collection.

Prerequisites

To complete tutorials in this collection you will need the following:

The Terraform v1.0.0+ installed
Git installed
An HCP account configured for use with Terraform

Additionally, for HCP Consul Dedicated AWS tutorials, you will need:

an AWS account with AWS Credentials configured for use with Terraform

HCP Consul Dedicated deployment steps

This section shows the logical steps required to create a new HCP Consul Dedicated cluster and to deploy services in the service mesh.

Tip

Some steps have extra resources, including Terraform resources and tutorials, that explain the step in more detail.

This architectural diagram shows a standard HCP Consul Dedicated cluster peered to a virtual network (for example, an AWS VPC or an Azure VNet). The virtual network has Consul clients and services on the service mesh.

HCP Cloud deployment
workflow

Step 1: Create an HVN and an HCP Consul Dedicated cluster

The HashiCorp Virtual Network (HVN) is a fundamental abstraction that makes HCP networking possible. An HVN allows you to delegate an IPv4 CIDR range to HCP, which HashiCorp then uses to automatically create resources in your cloud network. When you create an HCP Consul cluster, you must specify an HVN to deploy it to.

HCP Cloud deployment
workflow

The HCP Terraform provider lets you create and manage HVNs.

This provider lets you:

create a new HVN resource with the hcp_hvn resource
use an existing HVN resource with the hcp_hvn data source
create a new HCP Consul Dedicated cluster resource with the hcp_consul_cluster resource
use an existing HCP Consul Dedicated cluster resource with the hcp_consul_cluster data source

Step 2: Create a virtual network

After you create an HVN and an HCP Consul Dedicated cluster, you must create a virtual network (for example, AWS VPC or Azure VNet) that will host your workloads. You need to create a virtual network, either with Terraform or manually, before deploying your Consul clients and services to it.

HCP Cloud deployment
workflow

The vpc Terraform module lets you create and manage a VPC, subnets, security group ID, and route tables. Alternatively, you can use the aws provider's data sources to reference existing resources. For example, the aws_vpc data source lets you retrieve an existing VPC's information.

Visit the following collections to learn how to use Terraform to create and manage AWS resources.

The Get started with Terraform (AWS) collection will guide you through building, changing, and destroying AWS infrastructure using Terraform.
The Manage AWS Services collection contains tutorials that guide you through creating and managing common AWS resources. This includes configuring IAM policy documents, deploying serverless functions with Lambda, using application load balancers to schedule near-zero downtime releases, managing RDS and more.

Visit the following collections to learn how to use Terraform to create and manage Azure resources.

The Get started with Terraform (Azure) collection will guide you through building, changing, and destroying Azure infrastructure using Terraform.
The Manage Azure Services collection contains tutorials that guide you through creating and managing common Azure resources. This includes provisioning AKS clusters, managing Azure Active Directory (AD) users and groups, and more.

Step 3: Connect HVN and virtual network

After you create an HVN and a virtual network, you must set up a peering connection between the two networks and update the corresponding route tables. This allows traffic to travel between your HCP Consul Dedicated cluster (HVN) and Consul clients (hosted on your virtual network).

HCP Cloud deployment
workflow

The aws-hcp-consul Terraform module helps you peer your HVN with your VPC.

Step 4: Deploy Consul clients

After you set up the peering connection, you are ready to deploy Consul clients onto your peered virtual network. You can deploy the Consul clients on multiple workloads – including compute instances (AWS EC2 or Azure VMs), Kubernetes clusters (AWS EKS or Azure AKS), or container platforms (AWS ECS). Your HCP Consul cluster has files that contain your Consul client configuration. This lets the Consul clients successfully connect and retrieve information from your HCP Consul Dedicated cluster.

HCP Cloud deployment
workflow

Note

These modules are only intended for demonstration purposes. While the Consul clients will be deployed secure-by-default, the limited configuration options presented by the module are to aid a user in quickly getting started.

The aws-hcp-consul Terraform module contains submodules that lets you deploy a Consul client onto your peered virtual network. This includes:

the hcp-ec2-client submodule that deploys an EC2 instance running a Consul client and Nomad instance. The hcp-ec2-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on EC2.
the hcp-eks-client submodule that installs the Consul Helm chart onto a Kubernetes cluster. The hcp-eks-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to an AWS EKS cluster.
the hcp-ecs-client submodule that runs Consul clients in ECS tasks. The hcp-ecs-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on ECS.

The azure-hcp-consul Terraform module contains submodules that lets you deploy a Consul client onto your peered virtual network. This includes:

the hcp-vm-client submodule that deploys a VM instance running a Consul client and Nomad instance. The hcp-vm-demo contains an example Terraform configuration that creates all the Azure and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on VM.

Step 5: Deploy and run applications

Now that you have set up an HCP Consul Dedicated cluster and deployed Consul clients onto your peered virtual network, you can deploy your applications and services and leverage HCP Consul Dedicated's full capabilities.

HCP Cloud deployment
workflow

Note

The aws-hcp-consul Terraform module contains submodules that lets you deploy a Consul client onto your peered virtual network. This includes:

the hcp-ec2-client submodule that deploys an EC2 instance running a Consul client and Nomad instance. The hcp-ec2-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on EC2.
the hcp-eks-client submodule that installs the Consul Helm chart onto a Kubernetes cluster. The hcp-eks-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to an AWS EKS cluster.
the hcp-ecs-client submodule that runs Consul clients in ECS tasks. The hcp-ecs-demo contains an example Terraform configuration that creates all the AWS and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on ECS.

The azure-hcp-consul Terraform module contains submodules that lets you deploy a Consul client onto your peered virtual network. This includes:

the hcp-vm-client submodule that deploys a VM instance running a Consul client and Nomad instance. The hcp-vm-demo contains an example Terraform configuration that creates all the Azure and HCP resources necessary for connecting a HCP Consul Dedicated cluster to a Consul client running on VM.

End-to-end scenarios

You can automate all the steps with Terraform. The HCP Portal has a quickstart template that deploys an end-to-end development environment so you can quickly observe HCP Consul Dedicated in action. This Terraform configuration:

Creates a new HashiCorp virtual network (VNet) and single-node Consul development server
Connects the HVN with your Azure virtual network (VNet)
Provisions an Azure virtual machine (VM) instance and installs a Consul client
Deploys HashiCups, a demo application that uses Consul service mesh

You can generate this quickstart Terraform configuration when you create a new HCP Consul Dedicated cluster. After you select your cloud provider, select the Terraform Automation creation method.

HCP UI Consul - Deploy with
Terraform

AWS end-to-end scenarios

HCP Consul Dedicated on AWS supports three end-to-end scenarios.

The Deploy HCP Consul Dedicated with EKS using Terraform tutorial will show you how to deploy a HCP Consul Dedicated cluster and HashiCups, a sample application, on an EKS cluster.
The Deploy HCP Consul Dedicated with EC2 using Terraform tutorial will show you how to deploy a HCP Consul Dedicated cluster and HashiCups, a sample application, on an EC2 instance.
The Deploy HCP Consul Dedicated with ECS using Terraform tutorial will show you how to deploy a HCP Consul Dedicated cluster and HashiCups, a sample application, on an ECS cluster.

Azure end-to-end scenarios

HCP Consul Dedicated on Azure supports one end-to-end scenario.

The Deploy HCP Consul Dedicated with AKS using Terraform tutorial will show you how to deploy a HCP Consul Dedicated cluster and HashiCups, a sample application, on an Azure AKS cluster.
The Deploy HCP Consul Dedicated with Azure VM using Terraform tutorial will show you how to deploy a HCP Consul Dedicated cluster and HashiCups, a sample application, on an Azure VM instance.

HCP Consul Dedicated environments with existing resources

The end-to-end scenarios are an ideal subset of use-cases where you deploy HCP Consul and your workloads simultaneously with Terraform.

However, when you start to adopt HCP Consul Dedicated, you may want to manage and deploy the various components separately.

HVN and HCP Consul Dedicated
Consul clients
- AWS: EKS, EC2, ECS
- Azure: AKS, VM
Your applications and services

Visit the following tutorials to learn how to configure Consul clients to connect and interact with your existing HCP Consul Dedicated cluster. This will make it easier and faster for you to leverage HCP Consul Dedicated's full feature set.

Alternatively, visit the following tutorials to learn how to deploy HCP Consul Dedicated for your existing workloads.

Deep dive into available modules

The examples in this tutorial collection provide users a way to quickly deploy services in HCP Consul Dedicated and evaluate the platform. These modules are not intended for production use. However, you can use the modules as a foundation and adapt it to your organization and specific use case.

Visit the Terraform Registry page for more information about the modules.

The aws-hcp-consul Terraform module helps you peer your HVN with your VPC. In addition, it includes submodules that lets you deploy a Consul client (EKS, EC2, ECS) onto your peered virtual network.
The azurerm-hcp-consul Terraform module helps you peer your HVN with your VNet. In addition, it includes submodules that lets you deploy a Consul client (AKS, VM) onto your peered virtual network.

Next steps

In this tutorial, you learned the steps required to deploy HCP Consul Dedicated and connect it to your workload. In addition, the tutorial introduced you to Terraform resources that help you interact with HCP and deploy a Consul datacenter on different resources on AWS or Azure.

Complete the following tutorials to create your own end-to-end HCP Consul Dedicated development environment with Terraform.

If you encounter any issues, please contact the HCP team at support.hashicorp.com.

Collection Overview

Consul Dedicated Automation

Deploy HCP with EKS