Deploy Consul clients

You can deploy Consul clients in your infrastructure environment and connect them to the Consul servers managed in HashiCorp Cloud Platform (HCP).

As of Consul v1.14.0, Kubernetes deployments use Consul dataplanes instead of client agents. If you use Kubernetes with HCP Consul Dedicated, refer to Deploy Consul dataplanes. For more information about what a Consul dataplane is and how it works, refer to Simplified service mesh with Consul Dataplane in the Consul documentation.

Prerequisites

Before you deploy Consul clients, you need to create:

A HashiCorp virtual network (HVN)
- Create and Manage an HVN on AWS
- Create and Manage an HVN on Azure
A peering connection or transit gateway attachment
Routes for directing network traffic between the HVN and a target connection
- Routes on AWS
- Routes on Azure
A Consul server cluster

Network latency

Before deploying clients, ensure that there is sufficient latency between the HashiCord-managed servers and the user-manged environment. Consul uses the gossip protocol to share information across agents. To function properly, you cannot exceed the protocol’s maximum latency threshold.

The latency threshold is calculated according to the total round trip time (RTT) for communication between servers and clients.

For data sent from a Consul client to an HCP Consul Dedicated server:

Average RTT for all traffic cannot exceed 50ms.
RTT for 99 percent of traffic cannot exceed 100ms.

We recommend deploying Consul clients to the same region as your HCP Consul Dedicated cluster's HVN to avoid potential cross-region network interruptions.

The following websites can help you determine latency between your HVN and workload regions where Consul client agents are deployed:

AWS Latency Monitoring website. Contains for real-time information about AWS region latency.
Azure network round-trip latency statistics. Contains updated information about Azure region latency.

Download configuration files

After you create a HCP Consul Dedicated cluster, you can download a .zip file that contains the credentials required to deploy clients and register services with the Consul servers. This file contains the following credentials:

client_config.json contains a pre-configured client agent configuration to register services
ca.pem contains the data necessary to authorize TLS connections with Consul's certificate authority.

To protect your cluster from unwanted connections, you should keep both the configuration file and the certificate in a secure location.

To download the configuration files, complete the following steps:

Sign in to the HCP Portal.
Select the organization or project where you created the cluster you want to delete.
Click Consul.
From the Consul Overview, click the cluster ID you want to deploy clients with.
Click Access Consul and then Download Consul configuration files.

Client configuration file

HCP Consul Dedicated automatically generates a client configuration file with the parameters and values necessary to deploy clients to your HCP Consul Dedicated cluster. Values unique to your cluster include the following:

The cluster ID functions as the name of the datacenter
An unecrypted gossip key for servers and clients to securely communicate with each other
The cluster's private address
The path to the CA file

The following codeblock contains an example of a client configuration file generated by HCP Consul Dedicated, including the placement of values specific to an individual cluster:

{
    "acl": {
        "enabled": true,
        "down_policy": "async-cache",
        "default_policy": "deny"
    },
    "datacenter": "<cluster-ID>",
    "encrypt": "<gossip-key>",
    "encrypt_verify_incoming": true,
    "encrypt_verify_outgoing": true,
    "server": false,
    "log_level": "INFO",
    "ui": true,
    "retry_join": [
        "<private-access-address>"
    ],
    "auto_encrypt": {
        "tls": true
    },
    "tls": {
        "defaults": {
            "ca_file": "<./ca.pem>",
            "verify_outgoing": true
        }
    }
}

Register services

To register services with a HCP Consul Dedicated cluster, add service definitions to the client_config.json configuration file and then register the service with the HTTP API.

Refer to the following topics in the Consul documentation for more information about defining a service:

Services configuration reference contains complete specification information for a service definition.
Agents overview describes the agent requirements and usage. It also includes an example configuration file that defines both a client agent and a service in a single file.

To register the service, send a PUT request with the name of the service definition file to the /agent/service/register endpoint. The following example request registers the service defined in a file named service.json:

$ curl --request PUT --data @service.json http://localhost:8500/v1/agent/service/register

Refer to Service - Agent HTTP API in the API documentation for more information about this endpoint.

Create service intentions

After registering your services with the HCP Consul Dedicated servers, you must create intentions to authorize communication between the services. Refer to create and manage intentions in the Consul documentation for more information.

For additional guidance, complete the Manage Service Access Permission with Intentions tutorial in the Get Started with HCP Consul Dedicated collection.

Additional resources

You can automate the process to deploy clients and register services using Terraform. The steps vary depending on your cloud provider. The following tutorials contain step-by-step guidance for deploying clients on virtual machines:

You can also deploy clients using the AWS Elastic Container Service (ECS). Refer to the Serverless Consul service mesh with ECS and HCP tutorial for more information.