From 9eac957e08ccbf3e25ece5cb8d56e97c72b6d97e Mon Sep 17 00:00:00 2001 From: Rachel Elledge Date: Wed, 22 May 2024 11:09:35 -0500 Subject: [PATCH] DOC-3798 RS: Combine cluster certificate REST API request references --- .../requests/cluster/certificates/_index.md | 52 +++++++++++++++ .../rest-api/requests/cluster/update-cert.md | 63 ------------------- .../certificates/updating-certificates.md | 2 +- 3 files changed, 53 insertions(+), 64 deletions(-) delete mode 100644 content/operate/rs/references/rest-api/requests/cluster/update-cert.md diff --git a/content/operate/rs/references/rest-api/requests/cluster/certificates/_index.md b/content/operate/rs/references/rest-api/requests/cluster/certificates/_index.md index 8c6603914..91be16e45 100644 --- a/content/operate/rs/references/rest-api/requests/cluster/certificates/_index.md +++ b/content/operate/rs/references/rest-api/requests/cluster/certificates/_index.md @@ -10,11 +10,14 @@ headerRange: '[1-2]' hideListLinks: true linkTitle: certificates weight: $weight +aliases: + - /operate/rs/references/rest-api/requests/cluster/update-cert --- | Method | Path | Description | |--------|------|-------------| | [GET](#get-cluster-certificates) | `/v1/cluster/certificates` | Get cluster certificates | +| [PUT](#put-cluster-update_cert) | `/v1/cluster/update_cert` | Update a cluster certificate | | [DELETE](#delete-cluster-certificate) | `/v1/cluster/certificates/{certificate_name}` | Delete cluster certificate | ## Get cluster certificates {#get-cluster-certificates} @@ -63,6 +66,55 @@ Returns a JSON object that contains the cluster's certificates and keys. |------|-------------| | [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | + +## Update cluster certificate {#put-cluster-update_cert} + +```sh +PUT /v1/cluster/update_cert +``` + +Replaces an existing certificate on all nodes within the cluster with a new certificate. The new certificate must pass validation before it can replace the old certificate. + +See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. + +### Request {#put-request} + +#### Example HTTP request + +```sh +PUT /cluster/update_cert +``` + +#### Example JSON body + +```json +{ + "name": "certificate1", + "key": "-----BEGIN RSA PRIVATE KEY-----\n[key_content]\n-----END RSA PRIVATE KEY-----", + "certificate": "-----BEGIN CERTIFICATE-----\n[cert_content]\n-----END CERTIFICATE-----", +} +``` + +Replace `[key_content]` with the content of the private key and `[cert_content]` with the content of the certificate. + +### Response {#put-response} + +Responds with the `200 OK` status code if the certificate replacement succeeds across the entire cluster. + +Otherwise, retry the certificate update in case the failure was due to a temporary issue in the cluster. + +### Status codes {#put-status-codes} + +| Code | Description | +|------|-------------| +| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | +| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Failed, invalid certificate. | +| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Failed, unknown certificate. | +| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Failed, invalid certificate. | +| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Failed, expired certificate. | +| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Failed, not all nodes have been updated. | + + ## Delete cluster certificate {#delete-cluster-certificate} DELETE /v1/cluster/certificates/{string: certificate_name} diff --git a/content/operate/rs/references/rest-api/requests/cluster/update-cert.md b/content/operate/rs/references/rest-api/requests/cluster/update-cert.md deleted file mode 100644 index f0d35b24c..000000000 --- a/content/operate/rs/references/rest-api/requests/cluster/update-cert.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -Title: Update cluster certificate requests -alwaysopen: false -categories: -- docs -- operate -- rs -description: Update cluster certificate requests -headerRange: '[1-2]' -linkTitle: update_cert -weight: $weight ---- - -| Method | Path | Description | -|--------|------|-------------| -| [PUT](#put-cluster-update_cert) | `/v1/cluster/update_cert` | Update a cluster certificate | - -## Update cluster certificate {#put-cluster-update_cert} - -```sh -PUT /v1/cluster/update_cert -``` - -Replaces an existing certificate on all nodes within the cluster with a new certificate. The new certificate must pass validation before it can replace the old certificate. - -See the [certificates table]({{< relref "/operate/rs/security/certificates" >}}) for the list of cluster certificates and their descriptions. - -### Request {#put-request} - -#### Example HTTP request - -```sh -PUT /cluster/update_cert -``` - -#### Example JSON body - -```json -{ - "name": "certificate1", - "key": "-----BEGIN RSA PRIVATE KEY-----\n[key_content]\n-----END RSA PRIVATE KEY-----", - "certificate": "-----BEGIN CERTIFICATE-----\n[cert_content]\n-----END CERTIFICATE-----", -} -``` - -Replace `[key_content]` with the content of the private key and `[cert_content]` with the content of the certificate. - -### Response {#put-response} - -Responds with the `200 OK` status code if the certificate replacement succeeds across the entire cluster. - -Otherwise, retry the certificate update in case the failure was due to a temporary issue in the cluster. - -### Status codes {#put-status-codes} - -| Code | Description | -|------|-------------| -| [200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1) | No error | -| [400 Bad Request](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1) | Failed, invalid certificate. | -| [403 Forbidden](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.4) | Failed, unknown certificate. | -| [404 Not Found](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.5) | Failed, invalid certificate. | -| [406 Not Acceptable](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.7) | Failed, expired certificate. | -| [409 Conflict](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.10) | Failed, not all nodes have been updated. | diff --git a/content/operate/rs/security/certificates/updating-certificates.md b/content/operate/rs/security/certificates/updating-certificates.md index dc6e43c13..f198b6c0b 100644 --- a/content/operate/rs/security/certificates/updating-certificates.md +++ b/content/operate/rs/security/certificates/updating-certificates.md @@ -70,7 +70,7 @@ rladmin cluster certificate set cm certificate_file cluster.pem key_file key.pem ### Use the REST API -To replace a certificate using the REST API, use [`PUT /v1/cluster/update_cert`]({{< relref "/operate/rs/references/rest-api/requests/cluster/update-cert#put-cluster-update_cert" >}}): +To replace a certificate using the REST API, use [`PUT /v1/cluster/update_cert`]({{< relref "/operate/rs/references/rest-api/requests/cluster/certificates#put-cluster-update_cert" >}}): ```sh PUT https://[host][:port]/v1/cluster/update_cert