Add a little more information about PKI and replicated data sets to the PKI docs. (#15683)
* Add a little more information about PKI and replicated data sets. - Add a TOC to the PKI considerations page - Merge in the existing certificate storage into a new Replicated DataSets section - Move the existing Cluster Scalability section from the api-docs into the considerations page.
This commit is contained in:
Steven Clark
GitHub
parent
1331c2aa12
commit
69296e9edf
|
|
@ -2791,30 +2791,7 @@ $ curl \
|
||||||
|
|
||||||
## Cluster Scalability
|
## Cluster Scalability
|
||||||
|
|
||||||
Most non-introspection operations in the PKI secrets engine require a write to
|
See [PKI Cluster Scalability](/docs/secrets/pki/considerations#cluster-scalability) in the considerations page.
|
||||||
storage, and so are forwarded to the cluster's active node for execution.
|
|
||||||
This table outlines which operations can be executed on performance standbys
|
|
||||||
and thus scale horizontally.
|
|
||||||
|
|
||||||
| Path | Operations |
|
|
||||||
| --------------------------- | -------------------- |
|
|
||||||
| ca[/pem] | Read |
|
|
||||||
| cert/<em>serial-number</em> | Read |
|
|
||||||
| cert/ca_chain | Read |
|
|
||||||
| config/crl | Read |
|
|
||||||
| certs | List |
|
|
||||||
| ca_chain | Read |
|
|
||||||
| crl[/pem] | Read |
|
|
||||||
| crl/pem | Read |
|
|
||||||
| issue | Update <sup>\*</sup> |
|
|
||||||
| revoked/\* | Read, List |
|
|
||||||
| sign | Update <sup>\*</sup> |
|
|
||||||
| sign-verbatim | Update <sup>\*</sup> |
|
|
||||||
|
|
||||||
\* Only if the corresponding role has `no_store` set to true and `generate_lease`
|
|
||||||
set to false. If `generate_lease` is true the lease creation will be forwarded to
|
|
||||||
the active node; if `no_store` is false the entire request will be forwarded to
|
|
||||||
the active node.
|
|
||||||
|
|
||||||
## Managed Keys
|
## Managed Keys
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -11,6 +11,28 @@ considerations to be aware of, as well as some preparatory steps that should be
|
||||||
undertaken. You should read all of these _before_ using this secrets engine or
|
undertaken. You should read all of these _before_ using this secrets engine or
|
||||||
generating the CA to use with this secrets engine.
|
generating the CA to use with this secrets engine.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Be Careful with Root CAs](#be-careful-with-root-cas)
|
||||||
|
- [Managed Keys](#managed-keys)
|
||||||
|
- [One CA Certificate, One Secrets Engine](#one-ca-certificate-one-secrets-engine)
|
||||||
|
- [Always Configure a Default Issuer](#always-configure-a-default-issuer)
|
||||||
|
- [Key Types Matter](#key-types-matter)
|
||||||
|
- [Use a CA Hierarchy](#use-a-ca-hierarchy)
|
||||||
|
- [Keep certificate lifetimes short, for CRL's sake](#keep-certificate-lifetimes-short-for-crls-sake)
|
||||||
|
- [NotAfter Behavior on Leaf Certificates](#notafter-behavior-on-leaf-certificates)
|
||||||
|
- [Cluster Performance and Quantity of Leaf Certificates](#cluster-performance-and-quantity-of-leaf-certificates)
|
||||||
|
- [You must configure issuing/CRL/OCSP information _in advance_](#you-must-configure-issuingcrlocsp-information-_in-advance_)
|
||||||
|
- [Automate Leaf Certificate Renewal](#automate-leaf-certificate-renewal)
|
||||||
|
- [Safe Minimums](#safe-minimums)
|
||||||
|
- [Token Lifetimes and Revocation](#token-lifetimes-and-revocation)
|
||||||
|
- [Safe Usage of Roles](#safe-usage-of-roles)
|
||||||
|
- [Telemetry](#telemetry)
|
||||||
|
- [Auditing](#auditing)
|
||||||
|
- [Role-Based Access](#role-based-access)
|
||||||
|
- [Replicated DataSets](#replicated-datasets)
|
||||||
|
- [Cluster Scalability](#cluster-scalability)
|
||||||
|
|
||||||
## Be Careful with Root CAs
|
## Be Careful with Root CAs
|
||||||
|
|
||||||
Vault storage is secure, but not as secure as a piece of paper in a bank vault.
|
Vault storage is secure, but not as secure as a piece of paper in a bank vault.
|
||||||
|
|
@ -271,7 +293,7 @@ be used sparingly, if at all).
|
||||||
generally recommend to set `no_store` to `true` (defaults to `false`).
|
generally recommend to set `no_store` to `true` (defaults to `false`).
|
||||||
This prevents revocation but allows higher throughput as Vault no longer
|
This prevents revocation but allows higher throughput as Vault no longer
|
||||||
needs to store every issued certificate. This is discussed more in the
|
needs to store every issued certificate. This is discussed more in the
|
||||||
[Certificate Storage](#certificate-storage) section below.
|
[Replicated Datasets](#replicated-datasets) section below.
|
||||||
- Do not use roles with root certificates (`issuer_ref`). Root certificates
|
- Do not use roles with root certificates (`issuer_ref`). Root certificates
|
||||||
should generally only issue intermediates (see the section on [CA hierarchy
|
should generally only issue intermediates (see the section on [CA hierarchy
|
||||||
above](#use-a-ca-hierarchy)), which doesn't rely on roles.
|
above](#use-a-ca-hierarchy)), which doesn't rely on roles.
|
||||||
|
|
@ -279,18 +301,6 @@ be used sparingly, if at all).
|
||||||
for all purposes. Generally the default values are useful for client and
|
for all purposes. Generally the default values are useful for client and
|
||||||
server TLS authentication.
|
server TLS authentication.
|
||||||
|
|
||||||
## Certificate Storage
|
|
||||||
|
|
||||||
Unlike many secrets engines which replicate their state to all clusters
|
|
||||||
in multi-cluster architectures, the PKI secrets engine stores leaf certificates
|
|
||||||
issued with `no_store` set to `false` local to the cluster that issued them.
|
|
||||||
This allows for both primary and secondary clusters' nodes to issue
|
|
||||||
certificates for greater scalability. As a result, these certificates
|
|
||||||
and any revocations are visible only on the issuing cluster. This additionally
|
|
||||||
means each cluster has its own set of CRLs, distinct from other clusters. These
|
|
||||||
CRLs should either be unified into a single CRL for distribution from a single
|
|
||||||
URI, or server operators should know to fetch all CRLs from all clusters.
|
|
||||||
|
|
||||||
## Telemetry
|
## Telemetry
|
||||||
|
|
||||||
Beyond Vault's default telemetry around request processing, PKI exposes count and
|
Beyond Vault's default telemetry around request processing, PKI exposes count and
|
||||||
|
|
@ -434,6 +444,63 @@ For these personas, we suggest the following ACLs, in condensed, tabular form:
|
||||||
| `/root/rotate/+` | Write | Yes | | | | |
|
| `/root/rotate/+` | Write | Yes | | | | |
|
||||||
| `/root/replace` | Write | Yes | | | | |
|
| `/root/replace` | Write | Yes | | | | |
|
||||||
|
|
||||||
|
## Replicated DataSets
|
||||||
|
|
||||||
|
When operating with [Performance Secondary](/docs/enterprise/replication#architecture)
|
||||||
|
clusters, certain data-sets are maintained across all clusters, while others for performance
|
||||||
|
and scalability reasons are kept within a given cluster.
|
||||||
|
|
||||||
|
The following table breaks down by data type what data sets will cross the cluster boundaries.
|
||||||
|
For data-types that do not cross a cluster boundary, read requests for that data will need to be
|
||||||
|
sent to the appropriate cluster that the data was generated on.
|
||||||
|
|
||||||
|
| Data Set | Replicated Across Clusters |
|
||||||
|
|--------------------------|----------------------------|
|
||||||
|
| Issuers & Keys | Yes |
|
||||||
|
| Roles | Yes |
|
||||||
|
| CRL Config | Yes |
|
||||||
|
| URL Config | Yes |
|
||||||
|
| Issuer Config | Yes |
|
||||||
|
| Key Config | Yes |
|
||||||
|
| CRL | No |
|
||||||
|
| Revoked Certificates | No |
|
||||||
|
| Leaf/Issued Certificates | No |
|
||||||
|
|
||||||
|
The main effect is that within the PKI secrets engine leaf certificates
|
||||||
|
issued with `no_store` set to `false` are stored local to the cluster that issued them.
|
||||||
|
This allows for both primary and [Performance Secondary](/docs/enterprise/replication#architecture)
|
||||||
|
clusters' active node to issue certificates for greater scalability. As a
|
||||||
|
result, these certificates and any revocations are visible only on the issuing
|
||||||
|
cluster. This additionally means each cluster has its own set of CRLs, distinct
|
||||||
|
from other clusters. These CRLs should either be unified into a single CRL for
|
||||||
|
distribution from a single URI, or server operators should know to fetch all
|
||||||
|
CRLs from all clusters.
|
||||||
|
|
||||||
|
## Cluster Scalability
|
||||||
|
|
||||||
|
Most non-introspection operations in the PKI secrets engine require a write to
|
||||||
|
storage, and so are forwarded to the cluster's active node for execution.
|
||||||
|
This table outlines which operations can be executed on performance standby nodes
|
||||||
|
and thus scale horizontally across all nodes within a cluster.
|
||||||
|
|
||||||
|
| Path | Operations |
|
||||||
|
|-------------------------------|----------------------|
|
||||||
|
| ca[/pem] | Read |
|
||||||
|
| cert/<em>serial-number</em> | Read |
|
||||||
|
| cert/ca_chain | Read |
|
||||||
|
| config/crl | Read |
|
||||||
|
| certs | List |
|
||||||
|
| ca_chain | Read |
|
||||||
|
| crl[/pem] | Read |
|
||||||
|
| issue | Update <sup>\*</sup> |
|
||||||
|
| revoke/<em>serial-number</em> | Read |
|
||||||
|
| sign | Update <sup>\*</sup> |
|
||||||
|
| sign-verbatim | Update <sup>\*</sup> |
|
||||||
|
|
||||||
|
\* Only if the corresponding role has `no_store` set to true and `generate_lease`
|
||||||
|
set to false. If `generate_lease` is true the lease creation will be forwarded to
|
||||||
|
the active node; if `no_store` is false the entire request will be forwarded to
|
||||||
|
the active node.
|
||||||
|
|
||||||
## Tutorial
|
## Tutorial
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue