Federate multiple HCP Consul Dedicated clusters

Create service principal and key

Create a Service Principal and key to enable HCP Consul Dedicated deployment with Terraform.

From the left menu select Access Control (IAM) in the Settings section.

In the Access Control (IAM) page, click on the Service Principals tab and click on the Create a service principal link.

Specify a name for the service principal (learn-hcp in this tutorial). Choose the Contributor role from the drop-down menu.

Once created, click on the service principal's name to view its details.

From the detail page, click on the create service principal key link. A popup resembling the following will appear:

Create Terraform configuration file

Create a Terraform script for building a complete HashiCorp Cloud Platform (HCP) Consul federated environment in HCP.

Your script will create two HCP Consul Dedicated clusters and two HashiCorp Virtual Network (HVN) resources. By setting auto_hvn_to_hvn_peering = true on the secondary cluster, a peering connection is automatically created to link the two HVNs.

Create a file named hcpfed.tf in your working directory and copy the following configuration into the file.

// Pin the version
terraform {
  required_providers {
    hcp = {
      source = "hashicorp/hcp"
      version = "~> 0.9.0"
    }
  }
}

provider "hcp" {
  client_id = "YOUR_CLIENT_ID"
  client_secret = "YOUR_SECRET"
}

resource "hcp_hvn" "hvn-us-west" {
  hvn_id = "hvn-us-west"
  cloud_provider = "aws"
  region = "us-west-2"
  cidr_block = "172.25.16.0/20"
}

resource "hcp_hvn" "hvn-us-east" {
  hvn_id = "hvn-us-east"
  cloud_provider = "aws"
  region = "us-east-1"
  cidr_block = "172.26.16.0/20"
}

resource "hcp_consul_cluster" "primary" {
  cluster_id = "primary"
  hvn_id = hcp_hvn.hvn-us-east.hvn_id
  tier = "development"
  min_consul_version = "1.10.1"
  public_endpoint = true
}

resource "hcp_consul_cluster" "secondary" {
  cluster_id = "secondary"
  hvn_id = hcp_hvn.hvn-us-west.hvn_id
  tier = "development"
  min_consul_version = "1.10.1"
  public_endpoint = true
  primary_link = hcp_consul_cluster.primary.self_link
  auto_hvn_to_hvn_peering = true
}

Replace the client_id and client_secret placeholders with the values you created in the previous step and save the file.

To learn more about each of the attributes in the script, see the resource documentation.

Deploy your infrastructure

With your customized Terraform script, you are now ready to deploy your infrastructure.

Issue the terraform init command from your working directory to download the necessary providers and initialize the backend.

$ terraform init

Initializing the backend...

Initializing provider plugins...
...

Terraform has been successfully initialized!
...

Once Terraform has been initialized, you can verify the resources that will be created using the plan command.

$ terraform plan

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:
...

Finally, you can deploy the resources using the apply command.

$ terraform apply

...
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

Remember to confirm the run by entering yes.

Once you confirm, it will take a few minutes to complete the deploy. Terraform will print the following output if the deployment is successful.

Apply complete! Resources: 4 added, 0 changed, 0 destroyed.

Explore the HCP Portal UI

Once deployed, you can verify that the resources have been created in the HCP portal. Open https://portal.cloud.hashicorp.com in your browser.

Click the HashiCorp Virtual Network item on the left navigation pane to see your HVNs.

As the screenshot confirms, you will have two HVNs created in two distinct regions.

Click the Consul item on the left navigation pane to see the overview for your newly deployed Consul clusters. By the time of the launch, the UI will have more information regarding the federation.

Notice how the two clusters are located in different HVNs.

Select the primary cluster to review your primary cluster details.

Click the Generate Token button to generate an ACL token for your Consul datacenter and copy it to a local text file.

Access the Consul UI

Once HCP Consul Dedicated is deployed, you can access the Consul UI by clicking Public from the list of Cluster URLs on the HCP Consul Dedicated cluster overview page.

This will copy the public IP address to your clipboard. You can now paste this IP address into your browser to access the Consul UI.

HCP Consul Dedicated is secure by default, so you will need an ACL token to view any data in the UI. Select the login option in the top right corner of the Consul UI, then paste the ACL token you generated in the previous step. This will authorize you to interact with the Consul UI.

Open the drop-down menu labeled primary in the top left of the screen and select secondary. Use the drop-down menu to switch between your federated Consul datacenters.

You now have two HCP Consul Dedicated datacenters federated across two distinct regions. In a production environment, you can begin configuring your clients for each of your Consul datacenters. Visit the Connect a Consul Client to HCP Consul Dedicated tutorial to learn more how to configure clients to your Consul datacenters.

Destroy resources

Use the terraform destroy command to clean up the resources you created.

$ terraform destroy

...
Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value:

Remember to confirm by entering yes.

Once you confirm, it will take a few minutes to complete the removal. Terraform will print the following output if the command is successful.

Destroy complete! Resources: 4 destroyed.

Create HashiCorp Virtual Networks (HVN)

Create two unique HVNs that do not have overlapping network CIDRs. The two HVNs should be in two different regions, such as us-east-1 and us-west-2.

Navigate to the HCP Virtual Network view page and click on the "Create Network" button. If you have previously created HVNs, you will find them on this page.

Complete the required fields: network name, region, and network CIDR.

Repeat the steps above to create another HVN in a different region. Verify that the network CIDR does not overlap with other HVN resources. The following example shows two HVN configurations in different regions and non-overlapping CIDRs.

name: hvn-east
region: us-east-1
cidr: 172.25.16.0/20

name: hvn-west
region: us-west-2
cidr: 172.26.16.0/20

Each HVN must either be peered with an AWS VPC or attached to an AWS Transit Gateway. Refer to the following tutorials for instructions on how to configure each option. Ensure that each HVN has connectivity with your AWS environment before moving to the next step.

• Peering an AWS VPC with HashiCorp Cloud Platform (HCP)

• Connect an Amazon Transit Gateway to your HashiCorp Virtual Network

Create primary Consul cluster

Click on the Consul link in the left-side navigation bar. The link will take you to the Consul cluster view. Click on the "Create cluster" button.

Complete the tier, network, network accessiblity, and Consul version fields highlighted in the image below. You may choose a different tier, but for demonstration purposes, select the Development tier. Make sure you allow for public connections, otherwise you will not be able to visit the Consul UI from your workstation.

The cluster creation process will take a few minutes to complete.

With the creation of the first Consul cluster complete, you can move onto the creation of the secondary Consul cluster.

Create secondary Consul cluster

Open the Consul cluster page view and click on the cluster you recently created. The Consul cluster link will take you to that respective cluster's detail view page. From the Consul cluster details page, you will create a secondary cluster. Click on the Federation link on the left-side navigation menu to get started.

The Federation page displays a list of all the clusters that are part of the federation group. Click on the Create secondary button. The button will take you to the cluster creation page. Assign a name, select an HVN, and enable public connectivity for this cluster. Make sure you select an HVN in a different region compared to the primary cluster. In this example, us-west-2 is in a different region when compared to the primary cluster.

Verify federation

From the Consul cluster list view, verify that there is a primary cluster and a secondary cluster.

From the Consul cluster list view, verify that there is a primary cluster and a secondary cluster. Next, click on one of the HVNs in use. The link will take you to the selected HVN's detail page. Ensure your Consul cluster is under the Associated resources list section.

Lastly, visit the Consul UI through the public URL provided in the HCP Consul Dedicated Cluster's detail view page. You will need the ACL token to log into the Consul UI.

In the Consul UI, you can see other federated clusters when you click on the name of the current data center. You may also select the other federated cluster if you want to interact with its resources.

Destroy resources

Start by removing the secondary cluster. Navigate to the secondary cluster view and choose Delete from the Manage drop-down menu.

Type DELETE into the input box and click the Delete button to trigger the delete process.

Next, remove the primary cluster following the same process.

After you have removed the primary cluster, you may remove the HVN resources.

1. Click on the HashiCorp Virtual Network link in the left-side navigation menu to open the HVN list view.

2. Click on one of the two HVN that you created earlier. This action will take you to the selected HVN's detailed view.

3. Choose Delete from the Manage drop-down menu.

4. Type DELETE into the input box and click the Delete button to trigger the delete process.

5. Repeat the process for the other HVN you created.