* Updating guide to prepare for Learn migration. * Update website/source/docs/guides/connect-production.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/connect-production.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/connect-production.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com> * Update website/source/docs/guides/connect-production.md Co-Authored-By: kaitlincarter-hc <43049322+kaitlincarter-hc@users.noreply.github.com>
8.5 KiB
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:
- Configure ACLs
- Configure Agent Transport Encryption
- Bootstrap Connect's Certificate Authority
- Setup Host Firewall
- 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.
- ACL default
policy
must be
deny
. If for any reason you cannot use the default policy ofdeny
, you must add an explicit ACL denying anonymousservice:write
. Note, in this case the Connect intention graph will also default toallow
and explicitdeny
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 todeny
. - 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.