open-consul/website/source/docs/guides/connect-production.md

layout	page_title	sidebar_current	description
docs	Connect in Production	docs-guides-connect-production	This guide describes best practices for running Consul Connect in production.

Running Connect in Production

Consul Connect can secure all inter-service communication with mutual TLS. It's designed to work with minimal configuration out of the box, however, completing the security checklist and understanding the Consul security model are prerequisites for production deployments.

After completing this guide, you will be able to configure Connect to secure services. First, you will secure your Consul cluster with ACLs and TLS encryption. Next, you will configure Connect on the servers and host. Finally, you will configure your services to use Connect.

~> Note: To complete this guide you should already have a Consul cluster with an appropriate number of servers and clients deployed according to the other reference material including the deployment and performance guides.

The steps we need to get to a secure Connect cluster are:

1. Configure ACLs
2. Configure Agent Transport Encryption
3. Bootstrap Connect's Certificate Authority
4. Setup Host Firewall
5. Configure Service Instances

For existing Consul deployments, it may be necessary to incrementally adopt Connect service-by-service. In this case, step one and two should already be complete. However, we recommend reviewing all steps since the final deployment goal is to be compliant with all the security recommendations in this guide.

Configure ACLs

Consul Connect's security is based on service identity. In practice, the identity of the service is only enforcible with sufficiently restrictive ACLs.

This section will not replace reading the full ACL guide but will highlight the specific requirements Connect relies on to ensure it's security properties.

A service's identity, in the form of an x.509 certificate, will only be issued to an API client that has service:write permission for that service. In other words, any client that has permission to register an instance of a service will be able to identify as that service and access all of the resources that that service is allowed to access.

A secure ACL setup must meet the following criteria.

1. ACL default policy must be deny. If for any reason you cannot use the default policy of deny, you must add an explicit ACL denying anonymous service:write. Note, in this case the Connect intention graph will also default to allow and explicit deny intentions will be needed to restrict service access. Also note that explicit rules to limit who can manage intentions are necessary in this case. It is assumed for the remainder of this guide that ACL policy defaults to deny.
2. Each service must have a unique ACL token that is restricted to service:write only for the named service. You can review the Securing Consul with ACLs guide for a service token example. Note, it is best practices for each instance to get a unique token as described below.

~> Individual Service Tokens: It is best practice to create a unique ACL token per service instance because it limits the blast radius of a compromise. However, since Connect intentions manage access based only on service identity, it is possible to create only one ACL token per service and share it between instances.

In practice, managing per-instance tokens requires automated ACL provisioning, for example using HashiCorp's Vault.

Configure Agent Transport Encryption

Consul's gossip (UDP) and RPC (TCP) communications need to be encrypted otherwise attackers may be able to see ACL tokens while in flight between the server and client agents (RPC) or between client agent and application (HTTP). Certificate private keys never leave the host they are used on but are delivered to the application or proxy over local HTTP so local agent traffic should be encrypted where potentially untrusted parties might be able to observe localhost agent API traffic.

Follow the encryption guide to ensure both gossip encryption and RPC/HTTP TLS are configured securely.

Bootstrap Connect's Certificate Authority

Consul Connect comes with a built-in Certificate Authority (CA) that will bootstrap by default when you first enable Connect on your servers.

To use the built-in CA, enable it in the server's configuration.

connect {
  enabled = true
}

This configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability in an existing cluster.

As soon as a server that has Connect enabled becomes the leader, it will bootstrap a new CA and generate it's own private key which is written to the Raft state.

Alternatively, an external private key can be provided via the CA configuration.

~> External CAs: Connect has been designed with a pluggable CA component so external CAs can be integrated. For production workloads we recommend using Vault or another external CA once available such that the root key is not stored within Consul state at all.

Setup Host Firewall

In order to enable inbound connections to connect proxies, you may need to configure host or network firewalls to allow incoming connections to proxy ports.

In addition to Consul agent's communication ports any proxies will need to have ports open to accept incoming connections.

If using sidecar service registration Consul will by default assign ports from a configurable range the default range is 21000 - 21255. If this feature is used, the agent assumes all ports in that range are both free to use (no other processes listening on them) and are exposed in the firewall to accept connections from other service hosts.

It is possible to prevent automated port selection by configuring sidecar_min_port and sidecar_max_port to both be 0, forcing any sidecar service registrations to need an explicit port configured.

It then becomes the same problem as opening ports necessary for any other application and might be managed by configuration management or a scheduler.

Configure Service Instances

With necessary ACL tokens in place, all service registrations need to have an appropriate ACL token present.

For on-disk configuration the token parameter of the service definition must be set.

{ 
  "service": { 
    "name": "cassandra_db", 
    "port": 9002, 
    "token: "<your_token_here>"
    } 
 }

For registration via the API the token is passed in the request header, X-Consul-Token, or by using the Go client configuration.

To avoid the overhead of a proxy, applications may natively integrate with connect.

~> Protect Application Listener: If using any kind of proxy for connect, the application must ensure no untrusted connections can be made to it's unprotected listening port. This is typically done by binding to localhost and only allowing loopback traffic, but may also be achieved using firewall rules or network namespacing.

For examples of proxy service definitions see the proxy documentation.

Summary

After securing your Consul cluster with ACLs and TLS encryption, you can use Connect to secure service-to-service communication. If you encounter any issues while setting up Consul Connect, there are many community resources where you can find help.