upstream/vault
1
0
Fork 0
mirror of https://github.com/hashicorp/vault.git synced 2026-05-28 04:10:44 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Add docs on cross cluster tidy operations (#18979)

Browse source 
* List tidy parameters in one place

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add new tidy status outputs

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

* Add docs on new tidy parameters

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>

---------

Signed-off-by: Alexander Scheel <alex.scheel@hashicorp.com>
This commit is contained in:
Alexander Scheel 2023-02-03 14:27:18 -05:00 committed by GitHub
parent 092486b3e3
commit 399baabd61
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 27 additions and 56 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
website/content/api-docs/secret/pki.mdx
View file

@ -3641,6 +3641,20 @@ expiration time.
if present). Migration will only occur after `issuer_safety_buffer` has
passed since the last successful migration.
- `tidy_revocation_queue` `(bool: false)` - Set to true to remove stale
revocation request entries that haven't been confirmed by any active
node of a performance replication (PR) cluster. Only runs on the active
node of the primary cluster.
~> Note: this tidy is only applicable on Vault Enterprise.
- `tidy_cross_cluster_revoked_certs` `(bool: false)` - Set to true to remove
expired, cross-cluster revocation entries. This is the cross-cluster
equivalent of `tidy_revoked_certs`. Only runs on the active node of the
primary cluster.
~> Note: this tidy is only applicable on Vault Enterprise.
- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format)
used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep
certificates from being removed from the CRL that, due to clock skew, might
@ -3697,68 +3711,15 @@ status endpoint described below.
#### Parameters
The below parameters are in addition to the regular parameters accepted by the
[`/pki/tidy` endpoint](#tidy) documented above.
- `enabled` `(bool: false)` - Specifies whether automatic tidy is enabled or not.
- `interval_duration` `(string: "")` - Specifies the duration between automatic tidy
operations; note that this is from the end of one operation to the start of
the next so the time of the operation itself does not need to be considered.
- `tidy_cert_store` `(bool: false)` - Specifies whether to tidy up the certificate
store.
- `tidy_revoked_certs` `(bool: false)` - Set to true to remove all invalid and
expired certificates from storage. A revoked storage entry is considered
invalid if the entry is empty, or the value within the entry is empty. If a
certificate is removed due to expiry, the entry will also be removed from the
CRL, and the CRL will be rotated.
- `tidy_revoked_cert_issuer_associations` `(bool: false)` - Set to true to associate
revoked certificates with their corresponding issuers; this improves the
performance of OCSP and CRL building, by shifting work to a tidy operation
instead.
- `tidy_expired_issuers` `(bool: false)` - Set to true to automatically remove
expired issuers after the `issuer_safety_buffer` duration has elapsed. We
log the issuer certificate on removal to allow recovery; no keys are removed
during this process.
~> Note: The default issuer will not be removed even if it has expired and is
past the `issuer_safety_buffer` specified.
- `tidy_move_legacy_ca_bundle` `(bool: false)` - Set to true to backup any
legacy CA/issuers bundle (from Vault versions earlier than 1.11) to
`config/ca_bundle.bak`. This can be restored with `sys/raw` back to
`config/ca_bundle` if necessary, but won't impact mount startup (as
mounts will attempt to read the latter and do a migration of CA issuers
if present). Migration will only occur after `issuer_safety_buffer` has
passed since the last successful migration.
- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format)
used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep
certificates from being removed from the CRL that, due to clock skew, might
still be considered valid on other hosts. For a certificate to be expunged,
the time must be after the expiration time of the certificate (according to
the local clock) plus the duration of `safety_buffer`. Defaults to `72h`.
- `issuer_safety_buffer` `(string: "")` - Specifies a duration that issuers
should be kept for, past their `NotAfter` validity period. Defaults to
365 days as hours (`8760h`).
- `pause_duration` `(string: "0s")` - Specifies the duration to pause
between tidying individual certificates. This releases the revocation
lock and allows other operations to continue while tidy is running.
This allows an operator to control tidy's resource utilization within
a timespan: the LIST operation will remain in memory, but the space
between reading, parsing, and updates on-disk cert entries will be
increased, decreasing resource utilization.
Does not affect `tidy_expired_issuers`.
~> Note: Using too long of a `pause_duration` can result in tidy operations
not concluding during this lifetime! Using too short of a pause duration
(but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy)
to stop a running operation after the sleep period is over.
#### Sample Payload
```json
@ -3785,6 +3746,7 @@ This is a read only endpoint that returns information about the current tidy
operation, or the most recent if none are currently running.
The result includes the following fields:
* `safety_buffer`: the value of this parameter when initiating the tidy operation
* `tidy_cert_store`: the value of this parameter when initiating the tidy operation
* `tidy_revoked_certs`: the value of this parameter when initiating the tidy operation
@ -3796,6 +3758,15 @@ The result includes the following fields:
*Tidying revoked certificates: checking certificate N of TOTAL*
* `cert_store_deleted_count`: The number of certificate storage entries deleted
* `revoked_cert_deleted_count`: The number of revoked certificate entries deleted
* `missing_issuer_cert_count`: The number of revoked certificates which were missing a valid issuer reference
* `tidy_expired_issuers`: the value of this parameter when initiating the tidy operation
* `issuer_safety_buffer`: the value of this parameter when initiating the tidy operation
* `tidy_move_legacy_ca_bundle`: the value of this parameter when initiating the tidy operation
* `tidy_revocation_queue`: the value of this parameter when initiating the tidy operation
* `revocation_queue_deleted_count`: the number of revocation queue entries deleted
* `tidy_cross_cluster_revoked_certs`: the value of this parameter when initiating the tidy operation
* `cross_revoked_cert_deleted_count`: the number of cross-cluster revoked certificate entries deleted
| Method | Path |
| :----- | :----------------- |