From 32a7f8250a4f5cd68a39b7552315ad265a2e4e16 Mon Sep 17 00:00:00 2001 From: Alexander Scheel Date: Mon, 1 May 2023 10:26:29 -0400 Subject: [PATCH] Update to tidy status and docs (#20442) * Add missing tidy-status state values Signed-off-by: Alexander Scheel * Add docs on auto-tidy reading Signed-off-by: Alexander Scheel * Add missing tidy status field revocation_queue_safety_buffer Signed-off-by: Alexander Scheel * Include pause_duration in tidy-status docs Signed-off-by: Alexander Scheel * Add date of last auto-tidy operation to status Signed-off-by: Alexander Scheel * Add changelog entry Signed-off-by: Alexander Scheel --------- Signed-off-by: Alexander Scheel --- builtin/logical/pki/backend_test.go | 3 ++ builtin/logical/pki/path_tidy.go | 30 ++++++++++++- changelog/20442.txt | 3 ++ website/content/api-docs/secret/pki.mdx | 60 +++++++++++++++++++++++-- 4 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 changelog/20442.txt diff --git a/builtin/logical/pki/backend_test.go b/builtin/logical/pki/backend_test.go index 484386753..d275a2e2d 100644 --- a/builtin/logical/pki/backend_test.go +++ b/builtin/logical/pki/backend_test.go @@ -4007,6 +4007,7 @@ func TestBackend_RevokePlusTidy_Intermediate(t *testing.T) { expectedData := map[string]interface{}{ "safety_buffer": json.Number("1"), "issuer_safety_buffer": json.Number("31536000"), + "revocation_queue_safety_buffer": json.Number("172800"), "tidy_cert_store": true, "tidy_revoked_certs": true, "tidy_revoked_cert_issuer_associations": false, @@ -4019,6 +4020,7 @@ func TestBackend_RevokePlusTidy_Intermediate(t *testing.T) { "error": nil, "time_started": nil, "time_finished": nil, + "last_auto_tidy_finished": nil, "message": nil, "cert_store_deleted_count": json.Number("1"), "revoked_cert_deleted_count": json.Number("1"), @@ -4040,6 +4042,7 @@ func TestBackend_RevokePlusTidy_Intermediate(t *testing.T) { t.Fatal("Expected tidy status response to include a value for time_finished") } expectedData["time_finished"] = timeFinished + expectedData["last_auto_tidy_finished"] = tidyStatus.Data["last_auto_tidy_finished"] if diff := deep.Equal(expectedData, tidyStatus.Data); diff != nil { t.Fatal(diff) diff --git a/builtin/logical/pki/path_tidy.go b/builtin/logical/pki/path_tidy.go index 8748ccca0..0b35b4b3d 100644 --- a/builtin/logical/pki/path_tidy.go +++ b/builtin/logical/pki/path_tidy.go @@ -35,8 +35,10 @@ const ( type tidyStatus struct { // Parameters used to initiate the operation - safetyBuffer int - issuerSafetyBuffer int + safetyBuffer int + issuerSafetyBuffer int + revQueueSafetyBuffer int + tidyCertStore bool tidyRevokedCerts bool tidyRevokedAssocs bool @@ -152,6 +154,11 @@ func pathTidyCancel(b *backend) *framework.Path { Description: `Issuer safety buffer`, Required: false, }, + "revocation_queue_safety_buffer": { + Type: framework.TypeInt, + Description: `Revocation queue safety buffer`, + Required: true, + }, "tidy_cert_store": { Type: framework.TypeBool, Description: `Tidy certificate store`, @@ -197,6 +204,11 @@ func pathTidyCancel(b *backend) *framework.Path { Description: `Time the operation finished`, Required: false, }, + "last_auto_tidy_finished": { + Type: framework.TypeString, + Description: `Time the last auto-tidy operation finished`, + Required: true, + }, "message": { Type: framework.TypeString, Description: `Message of the operation`, @@ -288,6 +300,11 @@ func pathTidyStatus(b *backend) *framework.Path { Description: `Issuer safety buffer`, Required: true, }, + "revocation_queue_safety_buffer": { + Type: framework.TypeInt, + Description: `Revocation queue safety buffer`, + Required: true, + }, "tidy_cert_store": { Type: framework.TypeBool, Description: `Tidy certificate store`, @@ -336,6 +353,11 @@ func pathTidyStatus(b *backend) *framework.Path { "time_finished": { Type: framework.TypeString, Description: `Time the operation finished`, + Required: false, + }, + "last_auto_tidy_finished": { + Type: framework.TypeString, + Description: `Time the last auto-tidy operation finished`, Required: true, }, "message": { @@ -1449,6 +1471,8 @@ func (b *backend) pathTidyStatusRead(_ context.Context, _ *logical.Request, _ *f resp.Data["missing_issuer_cert_count"] = b.tidyStatus.missingIssuerCertCount resp.Data["revocation_queue_deleted_count"] = b.tidyStatus.revQueueDeletedCount resp.Data["cross_revoked_cert_deleted_count"] = b.tidyStatus.crossRevokedDeletedCount + resp.Data["revocation_queue_safety_buffer"] = b.tidyStatus.revQueueSafetyBuffer + resp.Data["last_auto_tidy_finished"] = b.lastTidy switch b.tidyStatus.state { case tidyStatusStarted: @@ -1624,6 +1648,7 @@ func (b *backend) tidyStatusStart(config *tidyConfig) { b.tidyStatus = &tidyStatus{ safetyBuffer: int(config.SafetyBuffer / time.Second), issuerSafetyBuffer: int(config.IssuerSafetyBuffer / time.Second), + revQueueSafetyBuffer: int(config.QueueSafetyBuffer / time.Second), tidyCertStore: config.CertStore, tidyRevokedCerts: config.RevokedCerts, tidyRevokedAssocs: config.IssuerAssocs, @@ -1780,6 +1805,7 @@ The result includes the following fields: * '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 +* 'revocation_queue_safety_buffer': the value of this parameter when initiating the tidy operation ` const pathConfigAutoTidySyn = ` diff --git a/changelog/20442.txt b/changelog/20442.txt new file mode 100644 index 000000000..09636b69b --- /dev/null +++ b/changelog/20442.txt @@ -0,0 +1,3 @@ +```release-note:improvement +secrets/pki: Add missing fields to tidy-status, include new last_auto_tidy_finished field. +``` diff --git a/website/content/api-docs/secret/pki.mdx b/website/content/api-docs/secret/pki.mdx index 129ef5541..e7292744e 100644 --- a/website/content/api-docs/secret/pki.mdx +++ b/website/content/api-docs/secret/pki.mdx @@ -76,7 +76,8 @@ update your API calls accordingly. - [Combining CRLs from the Same Issuer](#combine-crls-from-the-same-issuer) - [Sign Revocation List](#sign-revocation-list) - [Tidy](#tidy) - - [Configure Automatic Tidy](#configure-automatic-tidy) + - [Read Automatic Tidy Configuration](#read-automatic-tidy-configuration) + - [Set Automatic Tidy Configuration](#set-automatic-tidy-configuration) - [Tidy Status](#tidy-status) - [Cancel Tidy](#cancel-tidy) - [Cluster Scalability](#cluster-scalability) @@ -3889,7 +3890,57 @@ $ curl \ http://127.0.0.1:8200/v1/pki/tidy ``` -### Configure Automatic Tidy +### Read Automatic Tidy Configuration + +This endpoint fetches the current automatic tidy configuration. + +This is the combination of the periodic invocation parameters described +[in the below write handler](#set-automatic-tidy-configuration) and +the tidy parameters [described above in the tidy endpoint](#tidy). + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/pki/config/auto-tidy` | + +#### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/auto-tidy +``` + +#### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "enabled": false, + "interval_duration": 43200, + "issuer_safety_buffer": 31536000, + "maintain_stored_certificate_counts": false, + "pause_duration": "0s", + "publish_stored_certificate_count_metrics": false, + "revocation_queue_safety_buffer": 172800, + "safety_buffer": 259200, + "tidy_cert_store": false, + "tidy_cross_cluster_revoked_certs": false, + "tidy_expired_issuers": false, + "tidy_move_legacy_ca_bundle": false, + "tidy_revocation_queue": false, + "tidy_revoked_cert_issuer_associations": false, + "tidy_revoked_certs": false + }, + "auth": null +} +``` + + + +### Set Automatic Tidy Configuration This endpoint allows configuring periodic tidy operations, using the tidy mechanism described above. Status is from automatically run tidies are still reported at the @@ -3941,7 +3992,7 @@ 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 -* `state`: one of *Inactive*, *Running*, *Finished*, *Error* +* `state`: one of *Inactive*, *Running*, *Finished*, *Error*, *Cancelling*, or *Cancelled* * `error`: the error message, if the operation ran into an error * `time_started`: the time the operation started * `time_finished`: the time the operation finished @@ -3957,6 +4008,9 @@ The result includes the following fields: * `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 +* `revocation_queue_safety_buffer`: the value of this parameter when initiating the tidy operation +* `pause_duration`: the value of this parameter when initiating the tidy operation +* `last_auto_tidy_finished`: the time when the last auto-tidy operation finished; may be different than `time_finished` especially if the last operation was a manually executed tidy operation. Set to current time at mount time to delay the initial auto-tidy operation; not persisted. | Method | Path |