From dbf094940f8cd52322ffa9ac4deb006454562cd8 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Fri, 1 Sep 2023 12:42:46 -0700 Subject: [PATCH] Add more docs for update-primary (#22677) * add more docs for update-primary * Update website/content/api-docs/system/replication/replication-dr.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/system/replication/replication-dr.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/system/replication/replication-dr.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/system/replication/replication-performance.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * Update website/content/api-docs/system/replication/replication-performance.mdx Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> * PR feedback * Apply suggestions from code review Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --------- Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com> --- .../system/replication/replication-dr.mdx | 45 ++++++++++++++++--- .../replication/replication-performance.mdx | 37 +++++++++++++-- 2 files changed, 73 insertions(+), 9 deletions(-) diff --git a/website/content/api-docs/system/replication/replication-dr.mdx b/website/content/api-docs/system/replication/replication-dr.mdx index d75686a4b3..94b9d1ba5c 100644 --- a/website/content/api-docs/system/replication/replication-dr.mdx +++ b/website/content/api-docs/system/replication/replication-dr.mdx @@ -423,7 +423,7 @@ underlying storage. ```json { - "dr_operation_token": "...", + "dr_operation_token": "..." } ``` @@ -438,13 +438,30 @@ $ curl \ ## Update DR secondary's primary -This endpoint changes a DR secondary cluster's assigned primary cluster using a -secondary activation token. This does not wipe all data in the cluster. +The update endpoint changes the primary cluster assigned to a DR +secondary cluster. Changing the primary cluster assignment does not + wipe data in the secondary cluster. This endpoint requires a DR Operation Token to be provided as means of authorization. See the [DR Operation Token API docs](#generate-disaster-recovery-operation-token) for more information. +There are two ways to update the primary assignment: + +1. **Use a secondary activation token with the `token` parameter**. An + activation token is required after a DR failover when updating a newly + demoted DR secondary cluster. + +1. **Use primary cluster addresses with the `update_primary_addrs` parameter**. + During the update, cluster addresses are pinged one at a time via gRPC. + The first cluster to respond successfully is assigned as the new primary + address. Updating with cluster addresses is not allowed after a DR + failover when updating a newly demoted DR secondary cluster. + +The two update methods are mutually exclusive. You may use one or the +other, but not both. A good rule of thumb is to use `token` on DR secondary +clusters and `update_primary_addrs` on performance secondary clusters. + | Method | Path | | :----- | :--------------------------------------------- | | `POST` | `/sys/replication/dr/secondary/update-primary` | @@ -475,8 +492,7 @@ docs](#generate-disaster-recovery-operation-token) for more information. primary clusters. These addresses will be pinged in sequence, and if any of them respond successfully, these will be recorded as the new primary addresses. This is a lighter weight version of specifying a token and should result in less disruption - of replication. Note that it's invalid to specify this and `token` in the same API call. - They are mutually exclusive. + of replication. ### Sample payload @@ -497,6 +513,25 @@ $ curl \ http://127.0.0.1:8200/v1/sys/replication/dr/secondary/update-primary ``` +### Sample payload + +```json +{ + "dr_operation_token": "...", + "update_primary_addrs": ["10.0.0.2:8201"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/replication/dr/secondary/update-primary +``` + ## Generate disaster recovery operation token The `/sys/replication/dr/secondary/generate-operation-token` endpoint is used to create a new Disaster diff --git a/website/content/api-docs/system/replication/replication-performance.mdx b/website/content/api-docs/system/replication/replication-performance.mdx index 2f09ec9409..57074d7a5b 100644 --- a/website/content/api-docs/system/replication/replication-performance.mdx +++ b/website/content/api-docs/system/replication/replication-performance.mdx @@ -540,8 +540,20 @@ $ curl \ ## Update performance secondary's primary -This endpoint changes a performance secondary cluster's assigned primary cluster using a -secondary activation token. This does not wipe all data in the cluster. +The update endpoint changes the primary cluster assigned to a +performance secondary cluster. Changing the primary cluster assignment +does not wipe data in the secondary cluster. + +There are two ways to update the primary assignment: + +1. **Use a secondary activation token with the `token` parameter**. +1. **Use primary cluster addresses with the `update_primary_addrs` parameter**. + During the update, cluster addresses are pinged one at a time via gRPC. The + first cluster to respond successfully is assigned as the new primary address. + +The two update methods are mutually exclusive. You may use one or the other, +but not both. A good rule of thumb is to use `token` on DR secondary +clusters and `update_primary_addrs` on performance secondary clusters. | Method | Path | | :----- | :------------------------------------------------------ | @@ -571,8 +583,7 @@ secondary activation token. This does not wipe all data in the cluster. primary clusters. These addresses will be pinged in sequence, and if any of them respond successfully, these will be recorded as the new primary addresses. This is a lighter weight version of specifying a token and should result in less disruption - of replication. Note that it's invalid to specify this and `token` in the same API call. - They are mutually exclusive. + of replication. ### Sample payload @@ -591,3 +602,21 @@ $ curl \ --data @payload.json \ http://127.0.0.1:8200/v1/sys/replication/performance/secondary/update-primary ``` + +### Sample payload + +```json +{ + "update_primary_addrs": ["10.0.0.2:8201"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/sys/replication/performance/secondary/update-primary +```