How Connect Works

To try Connect locally, complete the Getting Started with Consul service mesh tutorial.

The core of Connect is based on .

Connect provides each service with an identity encoded as a TLS certificate. This certificate is used to establish and accept connections to and from other services. The identity is encoded in the TLS certificate in compliance with the SPIFFE X.509 Identity Document. This enables Connect services to establish and accept connections with other SPIFFE-compliant systems.

The client service verifies the destination service certificate against the . This is very similar to a typical HTTPS web browser connection. In addition to this, the client provides its own client certificate to show its identity to the destination service. If the connection handshake succeeds, the connection is encrypted and authorized.

The destination service verifies the client certificate against the public CA bundle. After verifying the certificate, the next step depends upon the configured application protocol of the destination service. TCP (L4) services must authorize incoming connections against the configured set of Consul , whereas HTTP (L7) services must authorize incoming requests against those same intentions. If the intention check responds successfully, the connection/request is established. Otherwise the connection/request is rejected.

All APIs required for Connect typically respond in microseconds and impose minimal overhead to existing services. To ensure this, Connect-related API calls are all made to the local Consul agent over a loopback interface, and all agent Connect endpoints implement local caching, background updating, and support blocking queries. Most API calls operate on purely local in-memory data.

To enable fast responses on endpoints such as the , the Consul agent locally caches most Connect-related data and sets up background blocking queries against the server to update the cache in the background. This allows most API calls such as retrieving certificates or authorizing connections to use in-memory data and respond very quickly.

All data cached locally by the agent is populated on demand. Therefore, if Connect is not used at all, the cache does not store any data. On first request, the data is loaded from the server and cached. The set of data cached is: public CA root certificates, leaf certificates, intentions, and service discovery results for upstreams. For leaf certificates and intentions, only data related to the service requested is cached, not the full set of data.

Further, the cache is partitioned by ACL token and datacenters. This is done to minimize the complexity of the cache and prevent bugs where an ACL token may see data it shouldn’t from the cache. This results in higher memory usage for cached data since it is duplicated per ACL token, but with the benefit of simplicity and security.

With Connect enabled, you’ll likely see increased memory usage by the local Consul agent. The total memory is dependent on the number of intentions related to the services registered with the agent accepting Connect-based connections. The other data (leaf certificates and public CA certificates) is a relatively fixed size per service. In most cases, the overhead per service should be relatively small: single digit kilobytes at most.

A sidecar proxy’s may specify an alternative datacenter or a prepared query that can address services in multiple datacenters (such as the geo failover pattern).

verify connections between services by source and destination name seamlessly across datacenters.

Connections can be made via gateways to enable communicating across network topologies, allowing connections between services in each datacenter without externally routable IPs at the service level.

Intention replication happens automatically but requires the primary_datacenter configuration to be set to specify a datacenter that is authoritative for intentions. In production setups with ACLs enabled, the must also be set in the secondary datacenter server’s configuration.

The primary datacenter also acts as the root Certificate Authority (CA) for Connect. The primary datacenter generates a trust-domain UUID and obtains a root certificate from the configured CA provider which defaults to the built-in one.

The secondary maintains watches on the root CA certificate in the primary. If the CA root changes for any reason such as rotation or migration to a new CA, the secondary automatically generates new keys and has them signed by the primary datacenter’s new root before initiating an automatic rotation of all issued certificates in use throughout the secondary datacenter. This makes CA root key rotation fully automatic and with zero downtime across multiple datacenters.