Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of Docs: change connect to SM for mTLS page into release/1.12.x #16135

Merged
merged 2 commits into from
Feb 2, 2023
Merged

Backport of Docs: change connect to SM for mTLS page into release/1.12.x #16135

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7ce7f67
backport of commit fa27ddb1d60b1f85639572027329aef3fbafc6ea
nrichu-hcp Jan 25, 2023
4625c7b
backport of commit bf5a4ed6e31455ccaaf5654548017f35a9377997
nrichu-hcp Jan 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 14 additions & 15 deletions website/content/docs/connect/connect-internals.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
layout: docs
page_title: Service Mesh - How it Works
description: >-
Consul's service mesh enforces secure service communication using mutual TLS (mTLS) encryption and explicit authorization. Learn how the service mesh certificate authorities, intentions, and agents work together in the ""Connect"" subsystem to provide Consul’s service mesh capabilities.
Consul's service mesh enforces secure service communication using mutual TLS (mTLS) encryption and explicit authorization. Learn how the service mesh certificate authorities, intentions, and agents work together to provide Consul’s service mesh capabilities.
---

# How Service Mesh Works
Expand All @@ -11,21 +11,20 @@ This topic describes how many of the core features of Consul's service mesh func
It is not a prerequisite,
but this information will help you understand how Consul service mesh behaves in more complex scenarios.

Consul Connect is the component shipped with Consul that enables service mesh functionality. The terms _Consul Connect_ and _Consul service mesh_ are used interchangeably throughout this documentation.

Consul Service Mesh is the component shipped with Consul that enables service mesh functionality.
To try service mesh locally, complete the [Getting Started with Consul service
mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
tutorial.

## Mutual Transport Layer Security (mTLS)

The core of Connect is based on [mutual TLS](https://en.wikipedia.org/wiki/Mutual_authentication).
The core of Consul service mesh is based on [mutual TLS](https://en.wikipedia.org/wiki/Mutual_authentication).

Connect provides each service with an identity encoded as a TLS certificate.
Consul Service Mesh 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](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md).
This enables Connect services to establish and accept connections with
This enables Consul Service Mesh services to establish and accept connections with
other SPIFFE-compliant systems.

The client service verifies the destination service certificate
Expand All @@ -50,24 +49,24 @@ requires no other dependencies, and
also ships with built-in support for [Vault](/docs/connect/ca/vault). The PKI system is designed to be pluggable
and can be extended to support any system by adding additional CA providers.

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

## Agent Caching and Performance

To enable fast responses on endpoints such as the [agent Connect
API](/api-docs/agent/connect), the Consul agent locally caches most Connect-related
API](/api-docs/agent/connect), the Consul agent locally caches most Consul Service Mesh-related
data and sets up background [blocking queries](/api-docs/features/blocking) 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,
Consul Service Mesh 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
Expand All @@ -79,9 +78,9 @@ 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
With Consul Service Mesh 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
related to the services registered with the agent accepting Consul Service Mesh-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.
Expand Down Expand Up @@ -116,15 +115,15 @@ be set in the secondary datacenter server's configuration.

## Certificate Authority Federation

The primary datacenter also acts as the root Certificate Authority (CA) for Connect.
The primary datacenter also acts as the root Certificate Authority (CA) for Consul Service Mesh.
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.

Secondary datacenters fetch the root CA public key and trust-domain ID from the
primary and generate their own key and Certificate Signing Request (CSR) for an
intermediate CA certificate. This CSR is signed by the root in the primary
datacenter and the certificate is returned. The secondary datacenter can now use
this intermediate to sign new Connect certificates in the secondary datacenter
this intermediate to sign new Consul Service Mesh certificates in the secondary datacenter
without WAN communication. CA keys are never replicated between datacenters.

The secondary maintains watches on the root CA certificate in the primary. If the
Expand Down