Create a HCP Consul Dedicated cluster for an existing EKS run time
In a previous tutorial you learned how to deploy a new HCP Consul Dedicated cluster and to deploy your workload in a EKS run time created in the same operation with Terraform.
In this tutorial you will learn how to create Terraform code that will help you deploy the same scenario starting from an existing EKS run time.
Prerequisites
To complete this tutorial you will need the following.
Basic command line access
Terraform v1.0.0+ CLI installed
Git installed
Admin access to the HashiCorp Cloud Platform (HCP) Consul portal
Note
HCP
Admin
access is necessary to create the Service Principal credentials used by Terraform to interact with HCP. If you already have a Service Principal key and client id provided by your admin, you only requireContributor
access. If you are anAdmin
and would like to create a Service Principal, check Deploy HCP Consul Dedicated with Terraform tutorial for instructions on how to create a Service Principal.An AWS account and AWS Access Credentials configured locally.
You can configure the AWS credentials using environment variables.
An existing EKS cluster. You can use the Provision an EKS Cluster (AWS) tutorial to deploy an EKS cluster with Terraform or refer to AWS documentation.
Get the Terraform file
You can retrieve the Terraform file either from the HCP UI or from a GitHub repository.
From the overview page click on Deploy with Terraform.
Make sure you select Use existing VPC.
Authenticate Terraform to HCP
To authenticate Terraform to HCP you need a Service Principal with Contributor
permissions. If you are logged with an Admin
account you can create one during
this step.
In the Authenticate Terraform to HCP section click on the Generate Service Principal and Key.
HCP will generate a new set of credentials for you and you can copy them using the Copy code button and export them in your terminal.
Note
If you are not an Admin
on HCP you should contact your
administrator and obtain valid Service Principal credentials before proceeding
with the tutorial.
Download Terraform code
For this tutorial you can skip filling the fields in the UI since you are going to enter the values manually in the code. Go to the Terraform configuration section.
Click on Copy code to copy it to your clipboard and save it in a file named main.tf
.
Review the file
Once you have created the file, open the file with your favorite editor.
You are now going to edit the file to configure Terraform to locate and manage your existing EKS runtime.
Fill the locals
The main.tf
file contains some variables that are used during the resources
creation and need to be filled in for the deployment.
AWS related fields
vpc_region
- This is the region where you deployed your VPC. For this tutorial we usedeu-west-2
.vpc_id
- Amazon Virtual Private Cloud (Amazon VPC) enables you to launch AWS resources into a virtual network that you've defined.route_table_id
- A route table contains a set of rules, called routes, that are used to determine where network traffic from your subnet or gateway is directed.subnet1
andsubnet2
- A subnet is a range of IP addresses in your VPC. You can launch AWS resources into a specific subnet.
HCP related fields
hvn_region
- The HashiCorp Virtual Network (HVN) region.Note
Not all regions are available for HCP to deploy. Pick one among:
us-west-2
,us-east-1
,eu-west-1
,eu-west-2
,eu-central-1
,ap-southeast-1
,ap-southeast-2
.cluster_id
- The HCP Consul Dedicated cluster ID. Use a unique name to identify your HCP Consul Dedicated cluster. For this tutorial the default value isconsul-quickstart-existing-eks
.
Remove the eks
module
The template is made to use an existing VPC do deploy an EKS cluster and then deploy an application on it. Since you already have an EKS cluster deployed you want to identify all parts of the Terraform code responsible for the EKS cluster creation and either comment them out or replace them with pointers to the existing cluster.
The module used for the EKS cluster creation is the AWS EKS Terraform module
and in the code is configured by the module "eks"
block.
Because you do not need to create the EKS cluster, comment out the whole module block.
Replace module dependencies
Once you have commented out the module "eks"
block, a few parts of the Terraform code
will need to be changed to provide the information that was previously being
retrieved from the module execution.
The idea is to replace all elements that refer to module.eks
with static values
retrieved from your EKS instance.
Element module.eks.cluster_id
You can comment out the occurrences of module.eks.cluster_id
and replace them
with a new local variable local.eks_cluster_id
.
Element module.eks.cluster_primary_security_group_id
Module aws_hcp_consul
requires the EKS cluster's primary security group ID.
Element module.eks.cluster_endpoint
Module eks_consul_client
requires the EKS cluster endpoint to be available to connect to it and deploy services. The eks_consul_client
module requires module.eks
to complete before attempting to conduct actions in the EKS cluster.
Element module.eks.kubeconfig_filename
Because the module eks
is not used, a kubeconfig file will not be generated
at the end of the Terraform execution. You can remove the output stanza.
Add new locals
In the previous sections, you replaced some of the values generated at
runtime with local variables. Add them in the locals
block.
eks_cluster_id
- The EKS cluster ID.eks_cluster_endpoint
- The EKS cluster endpoint to deploy the services.eks_primary_security_group_id
- The Cluster Security Group is a unified security group that is used to control communications between the Kubernetes control plane and compute resources on the cluster.Note: from this same view you can also verify you picked the correct Subnets for your configuration. If not, make sure to correct it before running Terraform.
Review modified Terraform file
Once completed all the changes give one final review to the main.tf
file to
make sure everything is configured properly.
Run terraform
With the updated Terraform manifest files and your custom credentials file, 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.
Once Terraform has been initialized, you can verify the resources that will
be created using the plan
command.
Finally, you can deploy the resources using the apply
command.
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.
Examine Terraform output
At the end of the execution Terraform will output the following lines:
As you can notice the consul_root_token
is not showed since is a sensitive value.
You can retrieve the Consul token using the command below:
Verify created resources
Consul UI
Visit the Consul UI using the consul_url
link in the output values.
Login to Consul using the token retrieved in the previous step and verify the services are all present in your Consul datacenter UI
Consul CLI configuration
Using the Terraform output values, you can setup your Consul CLI to connect to the datacenter you created.
Setup environment variables:
Verify Consul can connect to the datacenter:
Example output:
HashiCups application
The Terraform code deployed an application that exposes a web UI accessible
using the hashicups_url
URL.
Cleanup environment
Use the terraform destroy
command to clean up the resources you created.
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.
Note
The cleanup process do not take into account the existing resources that you used to deploy the EKS cluster. Remember to de-provision your EKS cluster if you do not need it anymore after this tutorial.
Next steps
In this tutorial you learned how to modify the Terraform template generated from the HCP UI to create an HCP Consul Dedicated cluster, connect it to an existing EKS runtime, and deploy a demo application.
This is the first step toward customizing the Terraform code to deploy your scenario.
To learn more about the Terraform resources used in this collection and the functionalities they provide check the next tutorial.
If you encounter any issues, please contact the HCP team at support.hashicorp.com.