Update to tidy status and docs (#20442)

* Add missing tidy-status state values

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

* Add docs on auto-tidy reading

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

* Add missing tidy status field revocation_queue_safety_buffer

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

* Include pause_duration in tidy-status docs

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

* Add date of last auto-tidy operation to status

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

* Add changelog entry

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

---------

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

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)

builtin/logical/pki/path_tidy.go

@@ -37,6 +37,8 @@ type tidyStatus struct {
 	// Parameters used to initiate the operation
 	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 = `

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.
+```

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
+}
+```
+
+<a name="configure-automatic-tidy"></a>
+
+### 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               |