diff --git a/docs/service-mesh/README.md b/docs/service-mesh/README.md index 7bc16f7f77..470fd28f29 100644 --- a/docs/service-mesh/README.md +++ b/docs/service-mesh/README.md @@ -3,7 +3,7 @@ - call out: envoy/proxy is the data plane, Consul is the control plane - [xDS Server] - a gRPC service that implements [xDS] and handles requests from an [envoy proxy]. - [agent/proxycfg] -- CA Manager - certificate authority +- [Certificate Authority](./ca) for issuing TLS certs for services and client agents - command/connect/envoy - bootstrapping and running envoy - command/connect/proxy - built-in proxy that is dev-only and not supported for production. diff --git a/docs/service-mesh/ca/README.md b/docs/service-mesh/ca/README.md new file mode 100644 index 0000000000..7a12921772 --- /dev/null +++ b/docs/service-mesh/ca/README.md @@ -0,0 +1,40 @@ +# Certificate Authority (Connect CA) + +The Certificate Authority subsystem manages a CA trust chain for issuing certificates to +services and client agents (via auto-encrypt and auto-config). + +## Architecture + +### High level overview + +- we can start with the mind map +- high level explaination of what are the features that are involved in CA (mesh/connect, auto encrypt) +- add all the func that are involved in the CA operations +- relationship between the different certs + + +### CA and Certificate relationship + +This diagram shows the relationship between the CA certificates in Consul primary and +secondary. + +![CA relationship](./cert-relationship.svg) + +[source](./cert-relationship.mmd) + +TODO: describe the relationship + +* what does it mean for the external root CA to be optional + * it always exists , unless the Consul CA provider is used AND it has generated the CA + root. +* relationship between Primary Root CA and Signing CA in the primary + * sometimes its the same thing (Consul, and AWS providers) + * sometimes it is different (Vault provider) +* client agent cert is used by auto-encrypt for Agent HTTP TLS (and client side of RPC + TLS) +* leaf cert service is the cert used by a service in the mesh + +### detailed call flow +- sequence diagram for leader election +- sequence diagram for leaf signing +- sequence diagram for CA cert rotation diff --git a/docs/service-mesh/ca/cert-relationship.mmd b/docs/service-mesh/ca/cert-relationship.mmd new file mode 100644 index 0000000000..85ae848dcb --- /dev/null +++ b/docs/service-mesh/ca/cert-relationship.mmd @@ -0,0 +1,31 @@ +graph TD + + ExternalRootCA["External RootCA (optional)"] + + subgraph "Consul Primary" + PrimaryRootCA["Primary Root CA"] + PrimarySigningCA["Primary Signing CA (conditional)"] + end + + subgraph "Consul Secondary" + SeconarySigningCA["Seconary Signing CA"] + end + + LeafCertAgentPrimary[Leaf Cert Client Agent] + LeafCertServicePrimary[Leaf Cert Service] + + LeafCertAgentSecondary[Leaf Cert Client Agent] + LeafCertServiceSecondary[Leaf Cert Service] + + + ExternalRootCA -.-> PrimaryRootCA + PrimaryRootCA -.-> PrimarySigningCA + + PrimaryRootCA --> SeconarySigningCA + + PrimarySigningCA --> LeafCertAgentPrimary + PrimarySigningCA --> LeafCertServicePrimary + + SeconarySigningCA --> LeafCertAgentSecondary + SeconarySigningCA --> LeafCertServiceSecondary + diff --git a/docs/service-mesh/ca/cert-relationship.svg b/docs/service-mesh/ca/cert-relationship.svg new file mode 100644 index 0000000000..a32f838d19 --- /dev/null +++ b/docs/service-mesh/ca/cert-relationship.svg @@ -0,0 +1 @@ +
Consul Secondary
Consul Primary
Seconary Signing CA
Primary Root CA
Primary Signing CA (conditional)
External RootCA (optional)
Leaf Cert Client Agent
Leaf Cert Service
Leaf Cert Client Agent
Leaf Cert Service
\ No newline at end of file