[DOC-3386] Add docs for rotating a CMEK key (cockroachdb#14453)

* [DOC-3386] Add docs for rotating a CMEK key

Co-authored-by: Ryan Kuo <[email protected]>
Co-authored-by: Abhinav Garg <[email protected]>
Co-authored-by: Michael Trestman <[email protected]>

_includes/cockroachcloud/cmek-rotation-types.md

@@ -0,0 +1,11 @@
+You can rotate a CMEK key for a {{ site.data.products.dedicated }} cluster either by creating a new version of the existing CMEK key or by creating a new CMEK key. At a high level:
+
+**To begin using a new version of an existing CMEK key**:
+
+1. In your KMS platform, you can either configure automatic rotation for the CMEK key, or you can perform a manual rotation.
+1. {{ site.data.products.db }} does not automatically re-encrypt the store key using the new CMEK key version. For each region you want to update, you must also perform a rotation using the {{ site.data.products.db }} API without modifying the CMEK key URI. {{ site.data.products.db }} re-encrypts the store key using the new CMEK key version.
+
+**To begin using an entirely new CMEK key**:
+
+1. Within your KMS platform, you create a new CMEK key.
+1. Next, you perform a rotation using the {{ site.data.products.db }} API and provide the new CMEK key URI.

cockroachcloud/cloud-sso.md

@@ -47,26 +47,26 @@ After Enterprise Authentication is enabled, your Cockroach Labs team or the supp
 
 ## {{ site.data.products.db }} SSO Frequently Asked Questions (FAQ)
 
-### Will it work if I try to sign in with SSO without explicitly setting it up for my account, if I already use an email from an SSO Provider (e.g., [email protected])?
+### Will it work if I try to sign in with SSO without explicitly setting it up for my account, if I already use an email from an SSO Provider such as Gmail?
 
-No, that won't work until you set up SSO for your account with that specific identity provider. Using an email associated with an SSO provider (Google, GitHub, or Microsoft) does not automatically enable SSO.
+Yes, as long as the email address associated with your SSO provider is exactly the same as the one associated with your existing {{ site.data.products.db }} account. After successfully signing in, you will be prompted to approve the updated authentication method for your account.
 
-To change your SSO method to use that provider, visit **My Account** in the [{{ site.data.products.db }} Console](https://cockroachlabs.cloud).
+To view your current authentication method, visit **My Account** in the [{{ site.data.products.db }} Console](https://cockroachlabs.cloud).
 
 ### Once I change my active login method to a new SSO provider, can I still sign in using my email/password combination or my GitHub identity?
 
-No. Only one authentication method can be active for each {{ site.data.products.db }} Console user at a time. Visit **My Account** in the [{{ site.data.products.db }} Console](https://cockroachlabs.cloud) to configure which authentication method is active.
+No. Only one authentication method can be active for each {{ site.data.products.db }} Console user. Visit **My Account** in the [{{ site.data.products.db }} Console](https://cockroachlabs.cloud) to view or update your active authentication method.
 
 ### Does this change how administrators invite users?
 
-At the moment, no. The [workflow for inviting team members](console-access-management.html#invite-team-members-to-cockroachdb-cloud) to {{ site.data.products.db }} remains the same.
+The [workflow for inviting team members](console-access-management.html#invite-team-members-to-cockroachdb-cloud) to {{ site.data.products.db }} remains the same. If Enterprise Authentication is enabled for your {{ site.data.products.db }} organization, then you don't need to invite SSO users.
 
 ### As an admin, how do I deprovision a user's access to {{ site.data.products.db }} Console if they leave the relevant project?
 
-If a user is using SSO, deleting the user's identity at the level of the SSO provider (e.g., deleting their Google account), will remove their access to the {{ site.data.products.db }} organization.
+If a user is using SSO, deleting the user's identity at the level of the SSO provider (for example, by deleting a user's GCP account) also removes their access to the {{ site.data.products.db }} organization.
 
-To remove a user's access to {{ site.data.products.db }} without deleting their SSO identity, you can [remove their {{ site.data.products.db }} user identity from your org](console-access-management.html#delete-a-team-member) in the console.
+To remove a user's access to {{ site.data.products.db }} without deleting their SSO identity, you can [remove their {{ site.data.products.db }} user identity from your {{ site.data.products.db}} organization](console-access-management.html#delete-a-team-member).
 
 ### Can admins require a particular login method for their {{ site.data.products.db }} organization?
 
-Currently, no.
+Yes, as long as Enterprise Authentication is enabled for your {{ site.data.products.db }} organization.

cockroachcloud/cmek-faq.md

@@ -19,7 +19,9 @@ Yes, the data encryption key is rotated automatically once every month. It’s n
 
 ## Can we rotate the CMEK for a cluster after a certain time or at some periodic interval?
 
-Not yet. The ability to rotate CMEK would be available at a later time. Once that’s ready, you could do it ad-hoc, or at a periodic interval using your own managed scheduling mechanism.
+{% include cockroachcloud/cmek-rotation-types.md %}
+
+To learn more about rotating a CMEK key using the {{ site.data.products.db }} API, visit [Rotate a CMEK key](managing-cmek.html#rotate-a-cmek-key).
 
 ## If we enable CMEK for a cluster that has been in use for some time, is the existing data encrypted at that time?
 

cockroachcloud/cmek.md

@@ -40,7 +40,7 @@ This section describes some of the ways that CMEK can help you protect your data
 - **Enforcement of encryption requirements**: With CMEK, you have control the CMEK key's encryption strength. The CMEK key's size is determined by what your KMS provider supports.
 
     You can use your KMS platform's controls to configure the regions where the CMEK key is available, enable automatic rotation schedules for CMEK keys, and view audit logs that show each time the CMEK key is used by {{ site.data.products.db }}. {{ site.data.products.db }} does not need any visibility into these details.
-- **Infrastructure flexibility**: If your clusters are deployed on a different IAAS platform provider from where you manage your keys, or if your CMEK keys are stored in multiple KMS systems or tenants, you can use Hashicorp Vault Key Management Secrets Engine to give your clusters access to your CMEK keys, as long as the keys are stored in AWS KMS or GCP KMS.
+- **Infrastructure flexibility**: If your CMEK keys are stored in multiple KMS systems or tenants, you can use Hashicorp Vault Key Management Secrets Engine to give your cluster access to your CMEK keys, as long as the cluster and keys are stored in the same deployment environment (GCP or AWS).
 
 The following example shows some of the ways that CMEK can help you meet business and regulatory requirements.
 
@@ -50,7 +50,7 @@ CMEK helps you to enforce such business rules on {{ site.data.products.db }} clu
 
 ## How CMEK works
 
-When you create a {{ site.data.products.dedicated }} cluster, its data at rest is not encrypted by default. Instead, the data is stored on disks attached to the cluster, which are always encrypted by the Information-As-A-Service (IAAS) provider you select when you create the cluster.
+When you create a {{ site.data.products.dedicated }} cluster, its data at rest on cluster disks is not encrypted by default. However, the disks themselves are automatically encrypted by cryptographic keys owned and managed by the cloud providers themselves.
 
 When you enable CMEK on a {{ site.data.products.dedicated }} cluster, {{ site.data.products.db }} creates two encryption keys and begins to use them to protect newly-written data at rest. {{ site.data.products.db }} manages these encryption keys and propagates them to cluster nodes.
 
@@ -84,6 +84,12 @@ Going forward:
 If the CMEK key is destroyed, the cluster's data can't be recovered or restored from a managed backup in {{ site.data.products.db }} or from a manual backup to the same cluster. It may be possible to restore a manual backup to a new cluster. 
 {{site.data.alerts.end}}
 
+## Rotation of a CMEK key
+
+{% include cockroachcloud/cmek-rotation-types.md %}
+
+To learn more about rotating a CMEK key using the {{ site.data.products.db }} API, visit [Rotate a CMEK key](managing-cmek.html#rotate-a-cmek-key).
+
 ## Backup and restore operations on a cluster with CMEK
 
 This section describes how enabling CMEK changes backup and restore operations on a cluster.
@@ -105,8 +111,7 @@ The CMEK feature has the following limitations:
 
 - CMEK can be enabled only on clusters created after April 1, 2022 (AWS) or June 9, 2022 (GCP).
 - To enable or revoke CMEK on a cluster, you must use the [Cloud API](/docs/cockroachcloud/cloud-api.html). It's not possible to enable CMEK using the {{ site.data.products.db }} Console.
-- If you add a new region to a cluster with CMEK enabled, the new region will not be protected by the CMEK key.
-- Rotating a CMEK key in {{ site.data.products.db }} is not supported. However, if your KMS supports key rotation without changing the key's URI, it will work as expected for a CMEK key.
+- If you add a new region to a cluster with CMEK enabled, the new region will not be automatically protected by the CMEK key.
 
 ## See also