Quickly get hands-on with HCP Consul using the HCP portal quickstart deployment, experiment with the Consul UI, and try out the key-value store.

HCP Consul

HashiCorp Cloud Platform (HCP) Consul enables you to deploy a Consul managed service on AWS.

HashiCorp Cloud Platform (HCP) Consul Introduction

Get Started with HashiCorp Cloud Platform (HCP) Consul

Consul comes with support for a user-friendly and functional web UI out of the box. In this tutorial, you will explore the web UI.

Explore the Consul UI

Connect a Consul client running in a virtual machine to HashiCorp Cloud Platform (HCP) Consul.

Connect a Consul Client to HCP Consul

Create a Consul service mesh on HCP using Envoy as a sidecar proxy.

Secure Service Communication with HCP Consul Service Mesh and Envoy

Quickly get hands-on with HashiCorp Cloud Platform (HCP) Vault using the HCP portal and setup your managed Vault cluster.

HCP Vault

HashiCorp Cloud Platform (HCP) Vault enables you to deploy a Vault managed
service on AWS.

Create a Vault Cluster on HashiCorp Cloud Platform (HCP)

HashiCorp Cloud Platform (HCP) Vault leverages Vault Enterprise Namespaces.
Learn the basics of how namespaces work in Vault.

Multi-tenancy with Namespaces

Once a Vault cluster is up and running, the Vault admin needs to perform some
common tasks such as enable auth methods, secrets engines, and create
policies.

Common Vault Setup Tasks

HCP Vault is a managed Vault service; therefore, the operational tasks are
slightly different from a self-managed Vault cluster.

Vault Operation Tasks

Connect a Consul client running in Amazon ECS using EC2 Instances to HashiCorp Cloud Platform (HCP) Consul.

Connect an Amazon Elastic Container Service Cluster using EC2 Instances to HashiCorp Cloud Platform Consul


HashiCorp Cloud Platform (HCP) is a fully managed platform offering HashiCorp
Products as a Service (HPaaS) to automate infrastructure on any cloud.

This tutorial will cover the process
required to connect an EKS Cluster to HCP Consul on AWS.

## Prerequisites

The following prerequisites are required:

- An HCP Consul deployment
- [Consul 1.8+](https://www.consul.io/downloads)
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
- [eksctl](https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html)
- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
- [helm](https://docs.aws.amazon.com/eks/latest/userguide/helm.html)
- [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
- An EKS Cluster

For this tutorial, you will need to ensure your AWS CLI is logged in
with your credentials, and is targeting the region where you have created
your EKS cluster. Review the [AWS documentation](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-quickstart.html)
for instructions on how to configure the AWS CLI.

To enable communication between the Consul control plane and
the EKS cluster, you will need to complete the process outlined
in the [manual deployment tutorial](/tutorials/cloud/consul-deploy) or in the
[Terraform deployment tutorial](/tutorials/cloud/terraform-hcp-consul-provider).

## Configure development host

Kubernetes stores cluster connection information in a special file called
`kubeconfig`. You can retrieve the Kubernetes configuration settings for your EKS
cluster and merge them into your local `kubeconfig` file by issuing the
following command. **Note**, you will have to change the region name and
cluster name to match your environment.

```shell-session
$ aws eks --region <your-region> update-kubeconfig --name <your-cluster-name>
```

Now, download the Consul client configuration from the HCP portal by clicking
the "Download client config" button from within the portal.

Unzip the client config package and cd into the unzipped directory.
Confirm that there are both `client_config.json` and `ca.pem` files.

```shell-session
$ ls
```

```plaintext
ca.pem             client_config.json
```

From this same screen in the HCP UI, click the "Generate token" button and
then click "Copy" from the dialog box. An global-management root token
is now in your clipboard. Set it to the `CONSUL_HTTP_TOKEN` environment variable on your
development host so that you can reference it later in the tutorial.

```shell-session
$ export CONSUL_HTTP_TOKEN=<your-token>
```

## Configure Consul secrets

Consul Service on HCP is secure by default. This means that client
agents will need to be configured with the gossip encryption key,
the Consul CA cert, and a root ACL token. All three of these
secrets will need to be stored in the Kubernetes secrets engine so
that they can be referenced and retrieved during the helm chart
installation.

First, set an environment variable to the desired name of your
Helm installation. This tutorial will use `hcp-beta` as the name.

```shell-session
$ export INSTALLATION_NAME=hcp-beta
```

From the unzipped client config directory, create a Kubernetes secret to
store the Consul CA certificate:

```shell-session
$ kubectl create secret generic "${INSTALLATION_NAME}-consul-ca-cert" --from-file='tls.crt=./ca.pem'
```

Now, create a Kubernetes secret that stores the Consul Gossip key:

```shell-session
$ kubectl create secret generic "${INSTALLATION_NAME}-gossip-key" --from-literal="key=$(jq -r .encrypt client_config.json)"
```

Finally, create a Kubernetes secret to store the bootstrap ACL token you generated from the HCP UI:

```shell-session
$ kubectl create secret generic "${INSTALLATION_NAME}-bootstrap-token" --from-literal="token=${CONSUL_HTTP_TOKEN}"
```

## Install Consul clients on EKS

This tutorial will use the [official consul-helm chart](https://github.com/hashicorp/consul-helm)
to install the Consul clients to your EKS cluster.

If you have not done so already, add the HashiCorp Helm repository:

```shell-session
$ helm repo add hashicorp https://helm.releases.hashicorp.com
```

Now, extract the private server URL from the client config so that it can be set
in the Helm values file as the `externalServers:hosts` entry. This value will be passed
as the [retry-join](https://www.consul.io/docs/agent/options#_retry_join) option to
the Consul clients.

```shell-session
$ export RETRY_JOIN=$(jq -r --compact-output .retry_join client_config.json)
```

Next, extract the public server URL from the client config so that it can be set
the Helm values file as the `k8sAuthMethodHost` entry.

```shell-session
$ export CONSUL_HTTP_ADDR=$(kubectl config view -o jsonpath="{.clusters[?(@.name == \"$(kubectl config current-context)\")].cluster.server}")
```

Next, set `CONSUL_HTTP_SSL_VERIFY=false` so that you can interact with the
HTTP API server using the Consul binary from your local development host.

```shell-session
export CONSUL_HTTP_SSL_VERIFY=false
```

Finally, generate the Helm values file. Notice that this configuration
sets up an ingress gateway. This will be covered in more depth later.

```shell-session
$ cat > config.yaml << EOF
global:
  enabled: false
  datacenter: $(jq -r .datacenter client_config.json)
  acls:
    manageSystemACLs: true
    bootstrapToken:
      secretName: ${INSTALLATION_NAME}-bootstrap-token
      secretKey: token
  gossipEncryption:
    secretName: ${INSTALLATION_NAME}-gossip-key
    secretKey: key
  tls:
    enabled: true
    enableAutoEncrypt: true
    caCert:
      secretName: ${INSTALLATION_NAME}-consul-ca-cert
      secretKey: tls.crt
externalServers:
  enabled: true
  hosts: ${RETRY_JOIN}
  httpsPort: 443
  useSystemRoots: true
  k8sAuthMethodHost: ${CONSUL_HTTP_ADDR}
client:
  enabled: true
  join: ${RETRY_JOIN}
connectInject:
  enabled: true
ingressGateways:
  enabled: true
  defaults:
    replicas: 1
  gateways:
    - name: ingress-gateway
      service:
        type: LoadBalancer
EOF
```

Validate that the config file is populated correctly.

```shell-session
$ more config.yaml
```

Install the HashiCorp Consul Helm chart:

```shell-session
$ helm install "${INSTALLATION_NAME}" -f config.yaml hashicorp/consul --version "0.28.0"
```

Once you have issued the `helm install` command, verify the Consul pods
have been successfully deployed by issuing `kubectl get pods`.

```shell-session
$ kubectl get pods
NAME                                                      READY   STATUS    RESTARTS   AGE
hcp-beta-consul-6kdtq                                     1/1     Running   0          24s
hcp-beta-consul-connect-injector-webhook-deploymenfj8pv   1/1     Running   0          24s
hcp-beta-consul-ppc25                                     1/1     Running   0          24s
hcp-beta-consul-sjg89                                     1/1     Running   0          24s
```

## Deploy an example workload

Now that the clients have been deployed, it is time to deploy an application
workload. This tutorial will use the HashiCups demo application.
Issue the following command to clone the repository to the development
host.

```shell-session
$ git clone https://github.com/hashicorp/learn-consul-k8s-hashicups.git
```

Change directory into the example repository.

```shell-session
cd learn-consul-k8s-hashicups
```

The repository contains the necessary yaml files to deploy the application.
Issue the following command to deploy the application to your
EKS cluster.

```shell-session
$ kubectl apply -f app/
```

Example output:

```plaintext
service/frontend created
serviceaccount/frontend created
configmap/nginx-configmap created
deployment.apps/frontend created
service/product-api-service created
serviceaccount/product-api created
configmap/db-configmap created
deployment.apps/product-api created
service/postgres created
serviceaccount/postgres created
deployment.apps/postgres created
service/public-api created
serviceaccount/public-api created
deployment.apps/public-api created
```

## Register a Consul ingress gateway

In Consul, an ingress gateway is a kind of resources called a
[Config Entry](https://www.consul.io/docs/agent/config-entries).
An ingress gateway is an endpoint that allows external traffic to
reach specific resources, such as the application user interface,
that are hosted within the datacenter.

Create a file named `ingress-gateway.hcl`. You will use this to
register an ingress gateway with Consul. Notice the `Name` value
matches the `ingressGateways:gateways:name` entry in `config.yaml`.
These fields **must match**.

```shell-session
$ cat > ingress-gateway.hcl << EOF
Kind = "ingress-gateway"
Name = "ingress-gateway"

Listeners = [
 {
   Port = 8080
   Protocol = "tcp"
   Services = [
     {
       Name = "frontend"
     }
   ]
 }
]
EOF
```

Now, register the config entry with Consul.

```shell-session
$ consul config write ingress-gateway.hcl
```

## Create the necessary intentions

Since HCP Consul on AWS is secure by default, the datacenter is created with a "default deny" [intention](/tutorials/consul/get-started-service-networking#control-communication-with-intentions)
in place. This means that, by default, no services can interact with each other until
an operator explicitly allows them to do so by creating intentions for each inter-service
operations they wish to allow.

Issue the following command to create the intentions the HashiCups application
requires to run.

```shell-session
$ consul intention create ingress-gateway frontend && \
consul intention create frontend public-api && \
consul intention create public-api product-api && \
consul intention create product-api postgres
```

Example output:

```shell-session
Created: ingress-gateway => frontend (allow)
Created: frontend => public-api (allow)
Created: public-api => product-api (allow)
Created: product-api => postgres (allow)
```

### Access the HashiCups UI

With the intentions in place, all that remains is to retrieve the public URL and port
of the ingress gateway. Do this by retrieving a list of services.

```shell-session
$ kubectl get svc
```

Example output:

```plaintext
NAME                          TYPE           CLUSTER-IP    EXTERNAL-IP      PORT(S)                         AGE
consul-ingress-gateway        ClusterIP      10.0.53.153   40.36.23.19      8080/TCP                        4h43m
...TRUNCATED
```

Verify you have successfully deployed the application by visiting that ip/port combination in
a browser tab. This validates that Consul service discovery is working, because the services
are able to resolve the upstreams. This also validates that Consul service mesh is working,
because the intentions that were created are allowing services to interact with one another.

## Next steps

In this tutorial, you connected Consul clients on EKS to HCP Consul and deployed a demo application. To keep learning about Consul's features, and for step-by-step examples of how to perform common Consul tasks, complete one of the following tutorials.

- [Explore the Consul UI](/tutorials/consul/get-started-explore-the-ui)
- [Review recommend practices for Consul on Kubernetes](/tutorials/consul/kubernetes-reference-architecture)
- [Deploy a metrics pipeline with Prometheus and Grafana](/tutorials/consul/kubernetes-layer7-observability)

If you encounter any issues, please contact the HCP team at [support.hashicorp.com](https://support.hashicorp.com/).


Connect a Consul client running in EKS to HashiCorp Cloud Platform (HCP) Consul.

Connect an Elastic Kubernetes Service Cluster to HashiCorp Cloud Platform Consul


## Prerequisites

This tutorial assumes you have an [HCP Consul](/tutorials/cloud/consul-deploy) cluster
deployed in your HCP account, and that you have correctly configured an [AWS peering connection](https://docs.aws.amazon.com/vpc/latest/peering/working-with-vpc-peering.html)
between your HVN to your AWS VPC. The peering connection allows your HCP Consul
_servers_ deployed in your Consul cluster to communicate with _clients_ that you
deploy in your AWS VPC. Your _clients_ must have a valid L3 route configured that
allows them to communicate with your HCP Consul cluster's private IP. They *cannot*
use a public IP even if you have one configured.

Review the manual deployment [tutorial](/tutorials/cloud/consul-deploy) or the
automatic deployment [tutorial](/tutorials/cloud/terraform-hcp-consul-provider)
for guidance on creating the necessary network configuration. To complete this
tutorial, we expect that you have already provisioned the following resources.

- An HCP HashiCorp Virtual Network (HVN)
- An HCP Consul cluster
- An AWS VPC
- An AWS peering connection between your HVC and your VPC
- An AWS EC2 instance deployed to the peered VPC

If you do not yet have and EC2 instance provisioned in the target VPC, refer
to the official [AWS Documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html)
for guidance on how to create an EC2 instance that you can use with this tutorial.

-> **Note:** In this tutorial, you will add a Consul _client_ running on an AWS virtual machine
(EC2) instance. This instance must be deployed to the same VPC that you have peered
with your HVN.

## Retrieve client configuration

You can use the HCP Portal to retrieve the _client_ configuration information you
need to connect your _client_ agent to your HCP Consul cluster. Navigate to the Consul
resource page in the HCP portal, and then select the Consul cluster you want to
join your _client_ to. Click the _Download client config_ button to download a zip
archive that contains the necessary files to join a client to the cluster. The archive
includes a default client configuration and certificate. Both should be considered
_secrets_, and should be kept in a secure location.

-> **Note:** This archive will be downloaded to whatever machine you used to access
the HCP Portal. You will have to upload the archive to your EC2 instance for use there.

## Install Consul

If you have not done so already, you should start a terminal session on your EC2
instance. Refer to the [official AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AccessingInstances.html)
for details on how to connect to your EC2 instance.

Once you are connected to your EC2 instance, follow the official Consul
[installation instructions](/tutorials/consul/get-started-install) to install the
Consul binary.

## Upload configuration to EC2 instance

You will need to copy the configuration file you downloaded from the HCP Portal to
the EC2 instance. The following example is one way you could do that using `scp`
with an `ubuntu` based EC2 instance. You may have to adapt the command if you
chose a non-ubuntu machine image. Issue this command from the machine and directory
where you downloaded the client configuration from the HCP Portal.

```shell-session
$ scp -i /path/to/your/aws.pem client_config_bundle_consul_<YOUR_CONSUL_CLUSTER_NAME>.zip ubuntu@<YOUR_EC2_INSTANCE_PUBLIC_IP>:/home/ubuntu
```

Switch back to the `ssh` session you initiated with your EC2 instance, and change
directory to the directory where you uploaded the client configuration archive.
Issue the following command to extract the configuration files from the archive you
just uploaded.

```shell-session
$ unzip client_config_bundle_consul_<YOUR_CONSUL_CLUSTER_NAME>.zip
```

List the contents of the directory to make sure you have all the necessary files.

```shell-session
$ ls
ca.pem  client_config.json client_config_bundle_consul_<YOUR_CONSUL_CLUSTER_NAME>.zip
```

Now remove the zip archive as it contains sensitive information, and you will no
longer need it. Do this on **both** the machine where you first downloaded the
archive, and on the EC2 instance that you uploaded it to.

```shell-session
$ rm client_config_bundle_consul_<YOUR_CONSUL_CLUSTER_NAME>.zip
```

## Review configuration

The following section explains the variable security and datacenter settings
contained within the `client_config.json` file. Here is an example of the
configuration contained within that file.

```json
{
  "acl": {
    "enabled": true,
    "down_policy": "async-cache",
    "default_policy": "deny"
  },
  "ca_file": "./ca.pem",
  "verify_outgoing": true,
  "datacenter": "dc1",
  "encrypt": "<GOSSIP_ENCRYPTION_KEY>",
  "server": false,
  "log_level": "INFO",
  "ui": true,
  "retry_join": [
    "<CONSUL_CLUSTER_PRIVATE_ENDPOINT>"
  ],
  "auto_encrypt": {
    "tls": true
  }
}
```

- The `acl.enabled` setting is set to `true` which ensures that only requests with
  a valid token will be able to access resources in the datacenter. To add your
  _client_, you will need to configure an agent token. You will do that in a
  separate file later in the tutorial.
- The `auto_encrypt.tls` setting is set to `true` to ensure transport layer security
  is enforced on all traffic with and between Consul agents.
- The `ca_file` setting points to the `ca.pem` file you downloaded as part of the
  client configuration from the HCP Portal. You must make sure that the `ca.pem`
  that was part of the configuration bundle is available on any machine where you
  will run a _client_ agent and exists at the path specified in this file. You will
  edit this setting later in the tutorial to point to the `/consul/opt` path.
- The `encrypt` setting is set to your Consul cluster's gossip encryption key.
  Do not modify the encryption key that is provided for you in this file.
- The `retry_join` is configured with the private endpoint address of your HCP Consul
  cluster's API. This is the address that your _client_ will use to interact with
  the _servers_ running in the HCP Consul cluster. Do not modify the value that is
  provided for you in this file.

## Create configuration directory

For this tutorial, you will use the `/opt/consul` directory to store all of your
Consul configuration and data files. Issue the following command on your EC2 instance
to create the folder.

```shell-session
$ sudo mkdir -p /opt/consul
```

-> **Note:** Since you will be storing all configuration files in this `/opt/consul` directory,
  you should edit the `client_config.json` file now, and make sure that the `ca_file`
  setting is set to `/opt/consul/ca.pem`.

## Create an ACL token

As mentioned previously, ACLs are enabled in your HCP Consul cluster because HCP
is _secure by default_. In order for your datacenter _client_ agent to join the
HCP Consul cluster on start up, you must provide it an ACL token with the necessary
privileges. Navigate to the _Overview_ tab on your Consul cluster's details page
in the HCP Portal, and then click the _Generate token_ button. A new admin token
will be generated and displayed in a modal dialog window. Copy the token, but be
sure to store it somewhere safe, as this token will have broad privileges for your
Consul data.

-> **Note:** If you are configuring a production environment, you should create a
  client token with a minimum set of privileges. For an in depth review of how to
  configure ACLs for Consul, refer to the [Secure Consul with Access Control Lists](tutorials/consul/access-control-setup-production)
  tutorial or the [official documentation](https://www.consul.io/docs/security/acl/acl-system).

## Create an ACL configuration file

Now that you have an ACL token, you can join your client to the HCP Consul cluster. Use the
following json to generate a new configuration file on the EC2 instance named
`client_acl.json`.

```json
{
  "acl": {
    "tokens": {
      "agent": "<YOUR-ACL-TOKEN>"
    }
  }
}
```

Edit the `client_acl.json` file, and replace the `<YOUR-ACL-TOKEN>` placeholder
text with the token you generated from the HCP Portal.

## Start the client

Your current working directory should now have all the necessary configuration files
you need. List the files to make sure.

```shell-session
$ ls
ca.pem client_acl.json client_config.json
```

Review the following checklist to make sure you have all the required configuration
artifacts, and that you understand what each of them provides.

- The `ca.pem` file will be used to authenticate via mTLS.
- The `client_acl.json` file has the ACL token that will be used to authorize with
  the ACL system.
- The `client_config.json` file has the gossip encryption key, the path to where you
  are about to move the `ca.pem` file, and the `retry_join` endpoint that the agent
  needs to use to join the Consul cluster.

Issue the following command to move all the necessary Consul configuration files to
the `/opt/consul` folder on your EC2 instance.

```shell-session
$ sudo mv ca.pem client_config.json client_acl.json /opt/consul
```

List the contents of the `/opt/consul` directory to verify the files were successfully
moved.

```shell-session
$ ls /opt/consul
ca.pem client_config.json client_acl.json
```

You can now start the _client_ agent using the `consul agent` command.

```shell
sudo consul agent -config-dir=/opt/consul -data-dir=/opt/consul
```

-> **Note:** For production environments, you will not use the `consul agent`
command to start the agent. Refer to the [Consul Deployment Guide](/tutorials/consul/deployment-guide#configure-the-consul-process)
for more information on how to configure Consul as a service.

Since ACLs are enabled, you will need a token when using the Consul CLI and API. Use the token you generated in the HCP portal for this tutorial.

You can use the Consul CLI to verify that your _client_ agent on your EC2 instance
was able to successfully register with your _server_ agent in your HCP Consul cluster.
You will need to open a new `ssh` session to your EC2 instance since the Consul
process is now currently running in your original session. Since ACLs are enabled,
you will need a token when using the CLI and API. You can use the token you saved
in your `/opt/consul/client_acl.json` file.

```shell-session
$ cat /opt/consul/client_acl.json
{
  "acl": {
    "tokens": {
      "agent": "<YOUR-ACL-TOKEN>"
    }
  }
}
```
~> **Note:** An alternative to setting the `CONSUL_HTTP_TOKEN` environment variable is to use the `-token` flag after any Consul CLI command. See the [Consul CLI](https://www.consul.io/commands) reference for additional information.

Use the Consul CLI to verify that you have a Consul deployment with at least 1 server and 1 client.

Copy the ACL token, and pass it to the `consul members` command as the `-token`
option.

```shell-session
$ consul members -token <YOUR-ACL-TOKEN>
Node              Address             Status  Type    Build      Protocol  DC   Segment
ip-172-25-20-128  172.25.20.128:8301  alive   server  1.9.3+ent  2         dc1  <all>
ip-10-2-160-249   10.2.160.249:8301   alive   client  1.9.3      2         dc1  <default>
```

Congratulations! You have successfully peered a Consul _agent_ with your fully
managed HCP Consul cluster.

## Next steps

In this tutorial, you deployed a Consul _client_ and connected it with the _servers_
running in your HCP Consul _cluster_. To learn more about Consul's features, and
for step-by-step examples of how to perform common Consul tasks, complete one of
the Get Started with Consul tutorials.

- [Register a Service with Consul Service Discovery](/tutorials/consul/get-started-service-discovery)
- [Secure Applications with Service Sidecar Proxies](/tutorials/consul/service-mesh-application-secure-networking)
- [Explore the Consul UI](/tutorials/consul/get-started-explore-the-ui)
- [Create a Consul service mesh on HCP using Envoy as a sidecar proxy](/tutorials/consul-service-mesh-with-envoy)

If you encounter any issues, please contact the HCP team at [support.hashicorp.com](https://support.hashicorp.com/).

[gpg-key]: https://apt.releases.hashicorp.com/gpg
[img-hcp-portal]: /img/cloud/consul-cluster-overview.png



HashiCorp Cloud Platform (HCP) Consul is a fully managed Service Mesh as a Service
(SMaaS) version of Consul that allows you to quickly deploy Consul servers in AWS.
As a fully managed service, HCP allows you to leverage Consul for _service discovery_
and _service mesh_ across a mix of VM, on-premises, hybrid, or Kubernetes environments,
while offloading the operational burden of maintaining the Consul _servers_ to the
Site Reliability Engineering (SRE) experts at HashiCorp.

In this tutorial, you will:

- Create a HashiCorp Virtual Network (HVN)
- Deploy HCP Consul
- Peer your HVN and AWS VPC
- Configure L3 routing and security

To learn how to automate this manual process using Terraform, check out the [Deploy HashiCorp Cloud Platform (HCP) Consul using Terraform](/tutorials/cloud/terraform-hcp-consul-provider)
tutorial.

## Prerequisites

To get started, you will need an [HCP account](https://portal.cloud.hashicorp.com).
You should also have familiarity with the following tools, technologies, and concepts.

- Consul
- AWS VPC
- AWS Peering Connections
- AWS Security Groups
- AWS Routes
- AWS Ingress & Egress

## Create a HashiCorp Virtual Network (HVN)

Before you can deploy HCP Consul, you must deploy an 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 click the _Create network_ button at the top right of the page to configure
and deploy your HVN.

Once the HVN configuration screen loads, you will have the ability to name your
HVN, select a region, and specify the CIDR block value for the network. The default
CIDR block value is `172.25.16.0/20`.

-> **Note:** You must set 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 overview tab.

## 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 HCP Consul cluster, select a Consul version,
and enable a public IP. Enabling a public IP will allow you to quickly access your
HCP Consul cluster 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.

-> **Note:** You cannot connect Consul clients to the HCP Consul deployment using
  the public IP.

For this tutorial, you can leave all the defaults, including the private IP option
and the latest version of Consul. Scroll to the bottom of the page and click the
_Create cluster_ button to create your Consul cluster. This process may take a few
minutes.

Once the process completes, your HCP Consul cluster _servers_ are fully deployed.
You will still need to deploy Consul _clients_ to a peered VPC to make use of Consul's
features. The _clients_ will need an L3 route configured in AWS that allows them
to access the HCP Consul cluster's private endpoint.

## Peer your HVN and VPC

To peer the networks, you must know your AWS account ID and have a VPC to peer with.
You can either create a new VPC, or use an existing one. This VPC must be peered
with the HVN that you provisioned through the HCP Portal.

On your HVN's overview page, select the _Peering connections_ tab, and then click
the _Create peering connection_ link to create a peering relationship with your
AWS VPC. Provide the following information, and then click the _Create connection_
button to begin the peering process.

- AWS account ID
- VPC ID
- VPC region
- VPC CIDR block

Once you start the peering process you will be directed to screen that shows the
peering status as _Creating_. You will need to accept the connection from the AWS
console.

Navigate to the _Peering Connections_ area of your AWS Console. You should
have an entry in the list with a status of _Pending Acceptance_. Confirm acceptance
in the AWS console by clicking Actions -> Accept Request. The status should change
to active on the AWS console.

You can return to this screen at any time to delete the peering relationship.
However, deleting this peering relationship means you will no longer be able to
communicate with your HVN.

## Configure L3 routing and security

Creating a peering connection is just the first step in establishing network connectivity
between your HVN and your VPC. AWS is _secure by default_. This means that, by
default, no routes have been specified and all ports are blocked. You will need to:

  - Create a security group
  - Create a route
  - Define ingress and egress rules

### Create a security group

You must create a security group associated with your AWS VPC. For instructions
on how to create a security group from the AWS console, refer to the [official documentation](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_SecurityGroups.html).
Alternatively, you can use the AWS CLI. You will need your AWS VPC ID to create
a security group associated with your AWS VPC.

Issue the following command to create a security group associated with your VPC.

```shell-session
$ aws ec2 create-security-group --group-name hcp-group --description "HCP security group" --vpc-id <VPC_ID>
{
    "GroupId": "<SECURITY_GROUP_ID>"
}
```

Make note of the security group ID in the output. You will use it in subsequent
steps of the tutorial.

### Create a route

You must create a route from your HVN to the peered AWS VPC. For instructions
on how to configure the route from the AWS console, refer the [official documentation](https://docs.aws.amazon.com/vpc/latest/userguide/VPC_Route_Tables.html).

Alternatively, you can use the AWS CLI. To create a route between your HVN and
your AWS VPC, you will need:

- The VPC peering connection ID (available from the _Peering connections_ tab in
  the HCP Portal's HVC page)
- The route table ID for the route table associated with your VPC (available from
  the AWS console)
- The CIDR block of the HVN you created in the HCP Portal

Issue the following command to create a route for your VPC peering connection.

```shell-session
$ aws ec2 create-route --route-table-id <ROUTE_TABLE_ID> --destination-cidr-block <HVN_CIDR> --vpc-peering-connection-id <VPC_PEERING_CONNECTION_ID>
{
    "Return": true
}
```

### Authorize ingress and egress

Now that you have a security group and a route, you must authorize ingress and
egress traffic. To authorize security group ingress and egress, you will need:

- Your security group ID
- The HVN CIDR
- The VPC region

The table below documents the ingress configuration that must be applied to
the security group.

#### 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 |


You can use the following command to apply the configuration listed above to your
security group.

```shell-session
aws ec2 --region <TARGET_VPC_REGION> authorize-security-group-ingress --group-id <SECURITY_GROUP_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=<SECURITY_GROUP_ID>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<SECURITY_GROUP_ID>}]'
```

#### Outbound (Egress):

The table below documents the egress configuration that must be applied to
the security group.

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

You can use the following command to apply the configuration listed above to your
security group.

```shell-session
aws ec2 --region <TARGET_VPC_REGION> authorize-security-group-egress --group-id <SECURITY_GROUP_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=<SECURITY_GROUP_ID>}]' \
IpProtocol=udp,FromPort=8301,ToPort=8301,UserIdGroupPairs='[{GroupId=<SECURITY_GROUP_ID>}]'
```

If you encounter any issues, review the [AWS documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/working-with-security-groups.html#updating-security-group-rules)
on how to update security groups.

## Next steps

In this tutorial, you manually configured and deployed HCP Consul. You also peered
your HVN with an AWS VPC so that you would be able to connect Consul _clients_.
With the steps complete, the route should be listed as _active_ in the AWS console.
This does not mean packets are actually flowing. It just means that the route is
stored in the route table. HCP has no way to detect if routing is configured
correctly in your VPC. You will need to confirm that these steps were performed
correctly by connecting Consul _clients_ located in your VPC to the _servers_
running in the Consul cluster on HCP.

To validate your manual setup and get hands-on experience with Consul's service
discovery and service mesh features, you can review the following tutorials to
learn how to deploy connect Consul clients on:

- [AWS Elastic Computing (EC2)](/tutorials/cloud/consul-client-virtual-machines),
- [Amazon EKS - Managed Kubernetes Service](/tutorials/cloud/consul-client-eks),
- [Amazon ECS - Container Orchestration Service](/tutorials/cloud/consul-client-ecs-ec2).

To learn how to automate the manual process you just completed using Terraform
check out the [Deploy HashiCorp Cloud Platform (HCP) Consul using Terraform](/tutorials/cloud/terraform-hcp-consul-provider)
tutorial.

If you encounter any issues, please contact the HCP team at [support.hashicorp.com](https://support.hashicorp.com/).


HashiCorp Cloud Platform (HCP) enables you to deploy a Consul managed service on AWS.

Deploy HashiCorp Cloud Platform (HCP) Consul


In [Deploy HashiCorp Cloud Platform (HCP) Consul](/tutorials/cloud/consul-deploy),
you learned the basics of HCP Consul and learned how to
manually deploy a cluster and peer the HashiCorp Virtual Network (HVN) with your
AWS Virtual Private Cloud (VPC). 

Once you learned the basic components and steps required to deploy a Consul
cluster, the recommended approach is to automate your deployment using HashiCorp
Terraform. 

For this reason we provide a Terraform provider for 
HCP Consul that exposes resources used to interact with HCP and 
create a new Consul datacenter using Terraform. 

This enables you to accomplish a number of tasks, including, but not limited to:

- Create a new HashiCorp Virtual Network (HVN) to deploy your datacenter
- Deploy your Consul datacenter
- Create an AWS VPC and peer it with your HashiCorp Virtual Network (HVN)
- Peer your HVN with an already existing AWS VPC

## Prerequisites

To complete the steps listed in this tutorial you will need:

- Terraform 0.14.+ installed on your local machine. 
You can follow the [Install Terraform](/tutorials/terraform/install-cli) tutorial in case you do not have it yet.

- A [HashiCorp Cloud Platform (HCP)](https://portal.cloud.hashicorp.com) 
account.

- An [AWS account](https://aws.amazon.com/free/). The tutorial will
also provide you instructions to automatically deploy an AWS VPC and peer it 
with your HashiCorp Virtual Network (HVN). To do so you will need valid 
credentials for AWS.

- Your AWS credentials configured locally.

You can configure the AWS credentials using environment variables.

```shell-session
export AWS_ACCESS_KEY_ID=<your AWS access key ID>
export AWS_SECRET_ACCESS_KEY=<your AWS secret access key>
export AWS_SESSION_TOKEN=<your AWS session token>
```

-> **Note:** This tutorial will provision resources that qualify under the 
[AWS free-tier](https://aws.amazon.com/free/). If your account doesn't qualify 
under the AWS free-tier, HashiCorp is not responsible for any charges that you may incur.

## Create service principal and key

To leverage the Terraform integration and be able to deploy your HCP Consul using
Terraform, you have to create a Service Principal and a key associated to it.

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 on
the page click on the create link.

Use the name you prefer to create the Service Principal (we used `learn-hcp` for
this tutorial) but remember to use `Contributor` as the role.

![Create Service Principal](/img/cloud/hcp-service-principal-create.png)

Once the Service Principal is created, click on the service principal name on the page to view its details. From the detail page, click on the
*create service principal key* link. A popup like the following will 
appear:

![Create Service Principal Key](/img/cloud/hcp-service-principal-key-create.png)

~> **Note:** Remember to copy the Client ID and secret, won't be able to 
retrieve the secret later and you'll have to use in the next step.

### Set environment variables

Once the key for the service principal has been created you can use the client 
ID and the secret in Terraform to authenticate with HCP.

We suggest you pass the values to terraform using environment variables.

```shell-session
export HCP_CLIENT_ID=<your client id>
export HCP_CLIENT_SECRET=<the key generated>
```
## Clone the code repository

The tutorial provides you with a git repository that contains two examples that 
show how to deploy a Consul cluster in HCP. They are divided into the following 
folders:

- `hcp_consul_base`: a basic example that deploys an HVN and Consul cluster on 
HCP. This example only creates the HVN and deploys a Consul cluster in it. You 
will still have to create an AWS VPC manually and peer it with your HVN.
- `hcp_consul_vpc`: a more complete example that creates an AWS VPC and peers it
automatically with your HVN. This scenario requires that you have a valid AWS account.

Clone the repository to get the example files locally:

```shell-session
$ git clone git@github.com:hashicorp/learn-hcp-consul.git
```

Move into the `hcp_consul_vpc` folder.

```shell-session
$ cd learn-hcp-consul/hcp_consul_vpc
```

Ensure that you are in the correct directory by listing the contents.

```shell-session
$ ls -1

 consul.tf
 variables.tf
 vpc_peering.tf
```

The folders contains the following files

- `consul.tf`: describes the HPC Consul cluster you are going to create.
- `vpc_peering.tf`: describes the AWS VPC and the peering with the HVN.
- `variables.tf`: sets the variables for your deployment.

-> **Note:** The examples in the repository provide you with the minimum set of 
attributes to test the platform. Check the [resource documentation](https://registry.terraform.io/providers/hashicorp/hcp/latest/docs/resources/consul_cluster) to find all 
the available attributes.

### Define your HVN

Before you can deploy an HCP Consul cluster, you will first need to configure a
HashiCorp Virtual Network (HVN). HVNs enable you to deploy HashiCorp Cloud 
products without having to manage the networking details. 

You can define an HVN using the `hcp_hvn` resource.

```hcl
## consul.tf
resource "hcp_hvn" "example_hvn" {
  hvn_id         = var.hvn_id
  cloud_provider = var.cloud_provider
  region         = var.region
}
```

Using the `variables.tf` file you can tune the attributes for the HVN. 

### Define your HCP Consul cluster

HCP Consul enables you to quickly deploy Consul servers in AWS while offloading 
the operations burden to the SRE experts at HashiCorp.

You can define an HCP Consul cluster using the `hcp_consul_cluster` resource.

```hcl
## consul.tf
resource "hcp_consul_cluster" "example_hcp" {
  hvn_id          = hcp_hvn.example_hvn.hvn_id
  cluster_id      = var.cluster_id
  tier            = "development"
# public_endpoint = true
}
```

Using the `variables.tf` file, you can tune the attributes for the Consul cluster. 

For this tutorial you are going to deploy a development environment that only
deploys one Consul server. 

~> **Note:** By setting the `public_endpoint` parameter to `true` your 
datacenter will have a public URL accessible from the internet. This can be 
useful in a test environment where you want to be able to access Consul UI from
outside your VPC and test functionality but in a production environment we
recommend you to leave the cluster private and accessible only from inside your
VPC.

### Define VPC peering

Creating peering connections from your HVN will allow you to connect and launch 
AWS resources from your HCP account.

The Amazon VPC can be managed with the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs).

```hcl
## vpc_peering.tf

# AWS resources
provider "aws" {
  region = var.region
}

resource "aws_vpc" "peer" {
  cidr_block = "172.31.0.0/16"
}

data "aws_arn" "peer" {
  arn = aws_vpc.peer.arn
}

# HCP resources
resource "hcp_aws_network_peering" "peer" {
  hvn_id              = hcp_hvn.example_hvn.hvn_id
  peer_vpc_id         = aws_vpc.peer.id
  peer_account_id     = aws_vpc.peer.owner_id
  peer_vpc_region     = data.aws_arn.peer.region
  peer_vpc_cidr_block = aws_vpc.peer.cidr_block
}

resource "aws_vpc_peering_connection_accepter" "peer" {
  vpc_peering_connection_id = hcp_aws_network_peering.peer.provider_peering_id
  auto_accept               = true
}
```

Once the VPC is peered with the HVN the resources you deploy inside the VPC will 
be able to reach the Consul servers.

## Deploy your infrastructure

Once you have cloned the repository and defined the environment variables for HCP and AWS,
you are now ready to deploy you infrastructure.

First, initialize terraform. This will download the necessary providers and
initialize the backend.

```shell-session
$ terraform init

Initializing the backend...

Initializing provider plugins...
...

Terraform has been successfully initialized!
...
```

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

```shell-session
$ terraform plan

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
  + create
 <= read (data resources)

Terraform will perform the following actions:

  # data.aws_arn.peer will be read during apply
  # (config refers to values not yet known)
 <= data "aws_arn" "peer"  {
      ...
    }

  # aws_vpc.peer will be created
  + resource "aws_vpc" "peer" {
      ...
    }

  # aws_vpc_peering_connection_accepter.peer will be created
  + resource "aws_vpc_peering_connection_accepter" "peer" {
      ...
    }

  # hcp_aws_network_peering.peer will be created
  + resource "hcp_aws_network_peering" "peer" {
      ...
    }

  # hcp_consul_cluster.example_hcp will be created
  + resource "hcp_consul_cluster" "example_hcp" {
      ...
    }

  # hcp_hvn.example_hvn will be created
  + resource "hcp_hvn" "example_hvn" {
      ...
    }

Plan: 5 to add, 0 to change, 0 to destroy.
```

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

```shell-session
$ 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. If the deploy
was successful you should get the following output.

```plaintext
Apply complete! Resources: 5 added, 0 changed, 0 destroyed.
```

## Access Consul

Once the deploy is complete, you can verify that the resources have been created in  
the HCP portal. Open the [https://portal.cloud.hashicorp.com](https://portal.cloud.hashicorp.com) page in your browser.

-> **Note:** The deploy could take up to 10 minutes to complete, you can grab a
coffee while waiting for the cluster to complete initialization.

You should be able to confirm the HVN is created in the HashiCorp Virtual 
Network page.

![HashiCorp Virtual Network](/img/cloud/hcp-hvn.png)

As the screenshot confirms, you will have a HVN created with:

- A peering connection to a VPC
- A Consul cluster showed in the associated resources

On the Consul page, you'll find the details for your newly deployed Consul 
cluster.

![HCP Consul Cluster](/img/cloud/hcp-consul-cluster.png)

From here you can use the *Generate Token* button to generate an ACL token for
your Consul datacenter or click the *Download client config* to retrieve the 
configuration files and CA certificate needed to connect clients to your 
datacenter.

~> **Note:** By default, the datacenter is not accessible from the internet. If
you want to access the Consul UI you will have to do it from a machine running 
inside your AWS VPC (recommended) or you need to configure your HCP Consul cluster to 
be publicly accessible.

## Destroy resources

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

```shell-session
$ 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. If the 
command was successful you should get the following output.

```plaintext
Destroy complete! Resources: 5 destroyed.
```

## Next steps

In this tutorial you learned how to automate the deployment of an HCP Consul 
cluster using Terraform. You used the newly released Terraform HCP provider to
achieve that, and you learned the what resources are made available by the provider.

You can find the full documentation for the HashiCorp Cloud Platform Consul 
Terraform provider in the [Terraform registry documentation](https://registry.terraform.io/providers/hashicorp/hcp/latest/docs)

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](/tutorials/cloud/consul-client-virtual-machines) 
or on [Elastic Kubernetes Service (EKS)](/tutorials/cloud/consul-client-eks).

If you encounter any issues, please contact the HCP team at 
[support.hashicorp.com](https://support.hashicorp.com/).


Automate the deployment of a Consul managed service on AWS using the Terraform HCP Consul provider.

Get Started with HCP Vault

Get Started with HCP Consul

New Tutorials for HCP Consul

Deploy HashiCorp Cloud Platform (HCP) Consul

Deploy HashiCorp Cloud Platform (HCP) Consul with Terraform

Connect a Consul Client to HCP Consul

Connect an Elastic Kubernetes Service Cluster to HashiCorp Cloud Platform Consul

Connect an Amazon Elastic Container Service Cluster using EC2 Instances to HashiCorp Cloud Platform Consul

Infrastructure

Security

Networking

Applications

Get Started with HCP Vault

Get Started with HCP Consul

New Tutorials for HCP Consul

Deploy HashiCorp Cloud Platform (HCP) Consul

Deploy HashiCorp Cloud Platform (HCP) Consul with Terraform

Connect a Consul Client to HCP Consul

Connect an Elastic Kubernetes Service Cluster to HashiCorp Cloud Platform Consul

Connect an Amazon Elastic Container Service Cluster using EC2 Instances to HashiCorp Cloud Platform Consul