HashiCorp Cloud Platform (HCP) Consul enables you to quickly deploy Consul servers in AWS. As a fully managed service, it allows you to leverage Consul for service discovery or service mesh across a mix of VM, hybrid/on-premises, and Kubernetes environments while offloading the operational burden to the Site Reliability Engineering (SRE) experts at HashiCorp.
In this tutorial, you will complete all the necessary steps to deploy HCP Consul including creating a HashiCorp Virtual Network (HVN). This tutorial also provides step-by-step guidance on how to peer your HVN with an AWS VPC. This will enable you to setup Consul clients to connect to your HCP Consul.
»Prerequisites
To get started, you will need an HCP account. You should also have familiarity with the following tools and technologies.
- Previous experience with Consul
- AWS VPC
- AWS Security Groups
»Create a HashiCorp Virtual Network (HVN)
Before you can deploy HCP Consul, you will need to set up a HVN. HCP Consul must be deployed into an HVN.
In the HCP portal, in the left navigation, select HashiCorp Virtual Network to be directed to the HVN resource overview page. Then select Create Network at the top right of the page to configure and deploy your HVN.
You will have the option to name your HVN, select a region, and specify the CIDR block value. The default CIDR block value is 172.25.16.0/20
.
Note, you must select a CIDR range that does not overlap with the AWS VPC that you will be peering with later.
Once the HVN is deployed, the status will update to stable on the HashiCorp Virtual Network resource page.
»Deploy HCP Consul
Now that you have created an HVN, you are ready to deploy HCP Consul. The HCP Consul servers deployed with HCP are fully managed by HashiCorp.
Navigate to the Consul resource page in the HCP portal. Select Create Cluster at the top right of the page to configure your deployment. On the configuration page, you will have the ability to name your Consul deployment, select a Consul version, and enable a public IP. Enabling a public IP will allow you to quickly access your Consul deployment by making the Consul UI and API available over a public IP address, however, it is not recommended for production because it is a less secure configuration. Additionally, you cannot connect Consul clients to the HCP Consul deployment with the public IP.
For this tutorial, you can leave all the defaults, including the private IP option and the latest version of Consul.
At this point, HCP Consul is fully deployed, but you will still need to deploy Consul clients inside of a peered VPC to fully access your Consul features. The clients will need to L3 route to the HCP Consul's private IP.
»Discover HCP Consul configuration
To connect clients to your HCP Consul deployment, you will first need to download the client configuration zip file containing the CA certificate and a basic Consul client configuration from the Consul Cluster overview page.
»Verify connectivity
The private URI for your HCP Consul should resolve to an IP address from within the CIDR block you used to create the HVN above.
You can find the private URI for your HCP Consul inside of the client_config.json
file in the retry_join
configuration option. The domain name will be .aws.hashicorp.cloud
. For example,
11eaa1fb-83ba-d4bd-898d-0242ac110011.private.consul.aws.hashicorp.cloud
»Consul access management
You will need to generate a token to access your HCP Consul deployment and complete any operation, since HCP Consul is secure by default. You will also need a token to connect the clients and access the Consul UI.
Select the Generate Token button to create a token. This process will generate a token with unrestricted privileges. You should use this initial token to create more fine-grained policies and tokens to access your HCP Consul deployment.
There are no limits to the number of tokens you can generate in the HCP portal. To delete tokens, you must use the Consul API or CLI.
»Peer your HVN and VPC
To peer the networks, you will need to know your AWS account ID and have a VPC to peer with. Either use the AWS console to create a new VPC, or use an existing one. In the operations below, this VPC will be peered to the HVN which is maintained by HashiCorp.
On your HVN's overview page, select the Peering Connections tab to create a peering relationship with your AWS VPC. Add the following information, and then select the Create Connection button.
- AWS account ID
- VPC ID
- VPC region
- VPC CIDR block
Next you will need to accept the connection in the AWS console. Find your VPC and go to the Peering Connections submenu. There, you will be prompted to accept the peering relationship in the AWS console. Confirm acceptance in the AWS console by clicking Actions -> Accept Request. The status should change to active on the AWS console.
At any time you can return to this screen to delete the peering relationship. However, deleting this peering relationship means you will no longer be able to communicate with your HVN.
Note that you do not have network connectivity and you do not have a valid security group. AWS is “secure by default” which means that by default you have no routes and all ports are blocked. You will need to explicitly create your routes and create a security group that allows you to communicate with the Consul cluster we are going to create.
»Configure your AWS security group
Finally, you will need to create a valid route from your HVN to the peered AWS VPC. Navigate to your VPC in the AWS console and select the route table listed in the details pane. Follow the steps below to add route rules.
- Select the Routes tab and then click Edit Routes
- Select Add Route
- Enter your HVN’s CIDR as a destination and the peering connection you created earlier as the destination.
- Select Save Routes
Note that the route will be listed as ACTIVE. This does not mean packets are actually flowing. It just means that the route is stored in the route table. HCP also has no way to detect if routing is configured correctly in your VPC so you will need to manually confirm that these steps were performed correctly.
Alternatively, you can use the AWS CLI.
aws ec2 --region <TARGET_VPC_REGION> authorize-security-group-ingress --group-id <USERS_SG_ID> --ip-permissions \
IpProtocol=tcp,FromPort=8301,ToPort=8301,IpRanges='[{CidrIp=<HVN_CIDR>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,IpRanges='[{CidrIp=<HVN_CIDR>}]' \
IpProtocol=tcp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<USERS_SG_ID>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<USERS_SG_ID>}]'
aws ec2 --region <TARGET_VPC_REGION> authorize-security-group-egress --group-id <USERS_SG_ID> --ip-permissions \
IpProtocol=tcp,FromPort=8300,ToPort=8301,IpRanges='[{CidrIp=<HVN_CIDR>}]' \
IpProtocol=tcp,FromPort=8301,ToPort=8301,IpRanges='[{CidrIp=<HVN_CIDR>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,IpRanges='[{CidrIp=<HVN_CIDR>}]' \
IpProtocol=tcp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<USERS_SG_ID>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<USERS_SG_ID>}]'
Where USERS_SG_ID is an ID of a security group that needs to be updated.
»Security group route tables
At a minimum, you will need the following rules added to your route table.
»Inbound (Ingress)
Protocol | From Port | To Port | Source | Description |
---|---|---|---|---|
TCP | 8301 | 8301 | HVN_CIDR | Used to handle gossip from server |
UDP | 8301 | 8301 | HVN_CIDR | Used to handle gossip from server |
TCP | 8301 | 8301 | Security group ID itself | Used to handle gossip between client agents |
UDP | 8301 | 8301 | Security group ID itself | Used to handle gossip between client agents |
»Outbound (Egress):
Protocol | From Port | To Port | Source | Description |
---|---|---|---|---|
TCP | 8300 | 8300 | HVN_CIDR | Used by clients to talk to server |
TCP | 8301 | 8301 | HVN_CIDR | Used to gossip with server |
UDP | 8301 | 8301 | HVN_CIDR | Used to gossip with server |
TCP | 8301 | 8301 | Security group ID itself | Used to handle gossip between client agents |
UDP | 8301 | 8301 | Security group ID itself | Used to handle gossip between client agents |
TCP | 443 | 443 | HVN_CIDR | TLS encryption |
If you encounter any issues, review the AWS documentation on how to update security groups.
»Next steps
In this tutorial, you configured and deployed HCP Consul. You also peered your HVN with an AWS VPC so that you could connect Consul clients. To get hands-on experience with Consul's service discovery and service mesh features, you will need to connect a Consul client deployed in a virtual machine or on Elastic Kubernetes Service (EKS).
If you encounter any issues, please contact the HCP team at support.hashicorp.com.