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.

HashiCorp Cloud Platform

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

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

Add and manage data in the Consul key value store, using the Consul command-line interface.

Store Data in Consul KV


~> **Beta Feature:** Currently, HashiCorp Cloud Platform (HCP) and HCP Consul on AWS
are in **BETA** and not suitable for production deployments.

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 [deployment tutorial](/tutorials/cloud/consul-deploy).

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

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/products-api-service created
serviceaccount/products-api created
configmap/db-configmap created
deployment.apps/products-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](/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 products-api && \
consul intention create products-api postgres
```

Example output:

```shell-session
Created: ingress-gateway => frontend (allow)
Created: frontend => public-api (allow)
Created: public-api => products-api (allow)
Created: products-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 hcp-consul-beta@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


~> **Beta Feature:** Currently, HashiCorp Cloud Platform (HCP) Consul is **BETA** and not suitable for deployment in production.

## Prerequistes

To get started, you will need [HCP Consul](/tutorials/cloud/consul-deploy) deployed in your HCP account. You will also need to peer your HVN and an AWS VPC. The peered networks will allow your HCP Consul deployed in your HVN to communicate with clients that you deploy in your AWS VPC. The clients will need to L3 route to the HCP Consul's private IP, they *cannot* use the public IP. 

Review the deployment [tutorial](/tutorials/cloud/consul-deploy) for guidance on peering networks.

We also recommend that you have familiarity with the following
tools and technologies.

- Previous Consul exprience
- An AWS account
- An AWS VPC

In this tutorial, you will add a Consul client running in an AWS virtual machine (EC2) instance. That instance should be deployed to the same VPC created for the peered network, and you will need to add the [security groups](/tutorials/cloud/consul-deploy). You should also download the Consul binary to the instance and place it within the PATH.

## Retrieve the client configuration

To get started, you will need to retrieve the client configuration and generate a token. In the HCP portal, navigate to the Consul resource page and then select the Consul Cluster you want to join clients to.

The Client Configuration download includes a basic client configuration and certificate, both contain sensitive information that should be kept in a secure location.

The `client_config.json` contains the minimal client configuration for a secure Consul deployment.

```json
{
  "acl": {
    "enabled": true,
    "down_policy": "async-cache",
    "default_policy": "deny"
  },
  "ca_file": "./ca.pem",
  "verify_outgoing": true,
  "datacenter": "dc1",
  "encrypt": "PpuASdc2Yfox6FJv0rxo7A==",
  "server": false,
  "log_level": "INFO",
  "ui": true,
  "retry_join": [
    "consul-cluster.private.consul.11eafe8a-e214-f6c6-bc0b-0242ac110012.aws.hashicorp.cloud"
  ],
  "auto_encrypt": {
    "tls": true
  }
}
```

The following are important security and datacenter settings.

- ACLs are enabled to secure access to the datacenter. To successfully add the client, you will also need to add an agent token.
- TLS encryption is enabled to secure communication with and between Consul agents. You will also need to add the `ca.pem` to the client that was part of the configuration bundle.
- Gossip encryption is enabled to secure gossip communication between agents.
- Retry join is configured so that the client can connect to the servers.

Finally, save a token in a new configuration file on the client named `client-acl.json`.

```json
{
  "acl": {
    "tokens": {
      "agent": "4411f091-a4c9-48e6-0884-1fcb092da1c8"
    }
  }
}
```

In production, you should create an agent token with a minimum set of privileges.

## Configure and start the client

You can now start the client, for testing, you can use the `consul agent` command to start the agent. Ensure that the `client_config.json` and `acl_config.json` are in the configuration directory. You should also ensure that the certificate, `ca.pem` is located in the directory specified in the configuration file.

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

For production environments, do not use the `consul agent` command to start the agent.

## Verify the client has joined

Use the Consul CLI to verify that you have a Consul deployment with 3 servers and 1 client. Note, since ACLs are enabled, you will need a token when using the CLI and API. You can download a token with root privileges in the HCP portal, but we recommend creating a token with the minimum necessary privileges.

```shell-session
$ export CONSUL_HTTP_TOKEN=4411f091-a4c9-48e6-0884-1fcb092da1c8
```

```shell-session
$ consul members
```

## Next steps

In this tutorial, you deployed Consul clients and connected them with your HCP Consul servers. To keep learning 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)

If you encounter any issues, please contact the HCP team at hcp-consul-beta@hashicorp.com.


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

Connect a Consul Client to Consul on HashiCorp Cloud Platform (HCP)


~> **Beta Feature:** Currently, HashiCorp Cloud Platform (HCP) and the managed Consul service are in **BETA** and not suitable for deployment in production.

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.

## Prerequistes

To get started, you will need an [HCP account](https://portal.cloud.hashicorp.com). 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 and specify the CIDR block value. 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 HVN 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 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. 

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,

```plaintext
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 unrestriced privilages. You should use this initial token to create more [fine-grained policies and tokens](/tutorials/consul/access-control-setup-production) 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 selet the route table listed in the details pane. Follow the steps below to add route rules.

1. Select the Routes tab and then click Edit Routes
1. Select Add Route
1. Enter your HVN’s CIDR as a destination and the peering connection you created earlier as the destination.
1. 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.

```shell-session
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>}]'
```

```shell-session
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](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 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](/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 hcp-consul-beta@hashicorp.com.


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

Get Started

New Tutorials for HCP Consul

Deploy HashiCorp Cloud Platform (HCP) Consul

Connect an Elastic Kubernetes Service Cluster to HashiCorp Cloud Platform Consul

Connect a Consul Client to Consul on HashiCorp Cloud Platform (HCP)

Infrastructure

Security

Networking

Applications

Get Started

New Tutorials for HCP Consul

Deploy HashiCorp Cloud Platform (HCP) Consul

Connect an Elastic Kubernetes Service Cluster to HashiCorp Cloud Platform Consul

Connect a Consul Client to Consul on HashiCorp Cloud Platform (HCP)