Add Customer Managed Keys Docs

content/docs/pulumi-cloud/admin/_index.md

@@ -9,9 +9,10 @@ menu:
         identifier: pulumi-cloud-admin
 ---
 
-Pulumi Cloud helps you manage infrastructure and operations at scale. Learn how to configure organizations, enable self-hosting, monitor audit logs, and manage identity and access.
+Pulumi Cloud helps you manage infrastructure and operations at scale. Learn how to configure organizations, enable self-hosting, monitor audit logs, bring your own encryption keys and manage identity and access.
 
 - [Pulumi Cloud organizations](/docs/pulumi-cloud/admin/organizations/): Set up and manage organizations for team collaboration and resource management.
 - [Self-hosting Pulumi Cloud](/docs/pulumi-cloud/admin/self-hosted/): Explore how to self-host Pulumi Cloud to meet your organization’s specific needs.
 - [Audit logs](/docs/pulumi-cloud/admin/audit-logs/): Access and configure audit logs to track activities and ensure compliance.
+- [Customer Managed Keys](/docs/pulumi-cloud/admin/customer-managed-keys/): Bring your own encryption keys for enhanced security and compliance.
 - [Identity and access management](/docs/pulumi-cloud/access-management/): Control access to resources with identity and access management.

content/docs/pulumi-cloud/admin/audit-logs.md

@@ -237,3 +237,7 @@ Custom defined keys:
 | Environment Schedule Deleted             | indicates the deletion of an environment schedule                                                                |
 | Environment Rotated                      | indicates the rotation of secrets in an environment                                                              |
 | Stack Provider Open                      | indicates the opening of a stack provider within an environment                                                  |
+| Customer Managed Key Added               | indicates the adding of a new customer managed key                                                               |
+| Customer Managed Key Set Default         | indicates the setting of a new default customer managed key                                                      |
+| Customer Managed Key Disabled            | indicates the disabling of a customer managed key                                                                |
+| Customer Managed Key Disabled All        | indicates the disabling of all customer managed keys                                                             |

content/docs/pulumi-cloud/admin/customer-managed-keys/_index.md

@@ -0,0 +1,102 @@
+---
+title_tag: "Pulumi Cloud: Customer Managed Keys"
+meta_desc: Bring your own encryption keys to protect data within Pulumi Cloud for enhanced security and compliance.
+title: "Customer Managed Keys"
+h1: Customer Managed Keys
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  cloud:
+    name: Customer Managed Keys
+    parent: pulumi-cloud-admin
+    weight: 4
+    identifier: pulumi-cloud-admin-customer-managed-keys
+aliases:
+  - /docs/pulumi-cloud/customer-managed-keys/
+---
+
+{{% notes "info" %}}
+Customer Managed Keys are available for organizations using the Enterprise and Business Critical editions.
+Learn more about editions on the [pricing page](/pricing/).
+{{% /notes %}}
+
+## Overview
+
+Pulumi Cloud supports Customer Managed Keys (CMKs) to improve the security and compliance of your data. CMKs allow you
+to use your own encryption keys to protect sensitive data in Pulumi Cloud through an external
+Key Management System (KMS).
+
+CMKs encrypt data keys, which are used to encrypt data in Pulumi Cloud. When you add your first CMK, all
+existing data keys encrypted with the Pulumi-managed key will be automatically re-encrypted with the new CMK.
+
+Only organization admins can manage CMKs.
+
+{{% notes "info" %}}
+Currently, Customer Managed Keys are only used to encrypt data in Pulumi ESC, and only AWS KMS is
+supported.
+We are working on adding support for more KMS providers and expanding encryption to additional Pulumi products. If you
+have specific requirements, please [contact us](/contact/).
+{{% /notes %}}
+
+## Viewing Customer Managed Keys
+
+To view Customer Managed Keys:
+
+1. Go to the organization’s **Settings**.
+2. Select **Customer Managed Keys**.
+
+The Customer Managed Keys page displays the following details for each key:
+
+- **Name**: The unique name of the key provided by an admin.
+- **Type**: The encryption key type, such as AWS KMS.
+- **Default**: Indicates if the key is the default encryption key for the organization. All new data keys responsible
+  for encrypting data created by your organization will be encrypted with this key.
+- **Set as default**: A button to set the key as the default encryption key. This option is unavailable for keys already
+  set as default or undergoing re-encryption.
+- **Disable**: A button to disable the key. This option is unavailable for default keys or keys undergoing
+  re-encryption.
+
+## Adding a Customer Managed Key
+
+Adding a Customer Managed Key enables you to use your own encryption key to protect sensitive data in Pulumi Cloud.
+
+{{% notes "info" %}}
+When the first Customer Managed Key is added, all data keys encrypted with the Pulumi-managed key will be automatically
+re-encrypted with the new Customer Managed Key.
+{{% /notes %}}
+
+### AWS KMS
+
+1. Set up a role in AWS IAM and a key in AWS KMS as
+   described [here](/docs/pulumi-cloud/admin/customer-managed-keys/aws-kms/).
+2. Go to the **Customer Managed Keys** settings page in Pulumi Cloud.
+3. Click **Add Customer Managed Key**.
+4. Enter a unique name for the key.
+5. Provide the **Role ARN** with access to the AWS KMS key.
+6. Provide the **Key ARN** of the AWS KMS key. Alias ARNs are also supported.
+
+## Disabling a Customer Managed Key
+
+Disabling a key prevents it from being used to create new data keys, but existing data keys remain encrypted with the
+key until they are re-encrypted. You must specify a re-encryption key to re-encrypt existing data keys.
+
+Disabling a key is not available for default keys or keys undergoing re-encryption.
+
+To disable a Customer Managed Key:
+
+1. Click the three-dot menu next to the key you want to disable.
+2. Select **Disable**.
+3. Choose a re-encryption key to re-encrypt existing data keys.
+4. Click **Disable** to confirm.
+5. A banner will appear, showing the re-encryption process status. It disappears once the process is complete.
+
+## Disabling All Customer Managed Keys
+
+Disabling all keys prevents them from being used to create new data keys, but existing data keys remain encrypted with
+the keys until they are re-encrypted. All data keys will be re-encrypted with the Pulumi-managed key.
+
+To disable all Customer Managed Keys:
+
+1. Click **Disable all Customer Managed Keys**.
+2. Confirm the re-encryption process in the dialog that appears.
+3. Click **Disable all** to confirm.
+4. A banner will appear, showing the re-encryption process status. It disappears once the process is complete.

content/docs/pulumi-cloud/admin/customer-managed-keys/aws-kms.md

@@ -0,0 +1,120 @@
+---
+title_tag: "AWS KMS"
+meta_desc: "Learn how to configure AWS KMS for Pulumi Cloud Customer Managed Keys to enhance security and compliance."
+title: "AWS KMS"
+h1: "AWS KMS"
+meta_image: /images/docs/meta-images/docs-meta.png
+menu:
+  cloud:
+    name: "AWS KMS"
+    parent: pulumi-cloud-admin-customer-managed-keys
+    weight: 1
+    identifier: pulumi-cloud-admin-customer-managed-keys-aws-kms
+aliases:
+  - /docs/pulumi-cloud/customer-managed-keys/aws-kms/
+---
+
+This guide provides step-by-step instructions for configuring AWS Key Management Service (KMS) to use [Customer Managed
+Keys (CMKs) with Pulumi Cloud](/docs/pulumi-cloud/admin/customer-managed-keys/). It covers setting up the necessary AWS
+IAM roles, trust policies, and KMS key permissions
+to enhance the security and compliance of your Pulumi Cloud environment.
+
+## Prerequisites
+
+* You must have sufficient AWS IAM and KMS privileges to create identity providers, IAM roles and KMS keys.
+
+{{< notes type="warning" >}}
+Please note that this guide provides step-by-step instructions based on the official provider documentation which is
+subject to change. For the most current and precise information, always refer to
+the [official AWS documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html).
+{{< /notes >}}
+
+## Create the identity provider
+
+1. In the navigation pane of the [IAM console](https://console.aws.amazon.com/iam/), choose **Identity providers**, and
+   then choose **Add provider**.
+2. In the **Provider type** section, click the radio button next to **OpenID Connect**.
+3. For the **Provider URL**, provide the following URL: `https://api.pulumi.com/oidc`
+4. For the **Audience** field, the value is the name of your Pulumi organization prefixed with `aws:` (e.g.
+   `aws:{org}`). Then click **Add provider**.
+
+## Configure the IAM role
+
+Once you have created the identity provider, you will see a notification at the top of your screen prompting you to
+assign an IAM role.
+
+1. Click the **Assign role** button.
+2. Select the **Create a new role** option, then click **Next**.
+3. On the IAM **Create role** page, ensure the **Web identity** radio button is selected.
+4. In the **Web identity** section:
+    * Select `api.pulumi.com/oidc` under **Identity provider**.
+    * Select the name of your Pulumi organization under **Audience**. Then click **Next**.
+5. Skip the **Add permissions** page by clicking **Next**.
+6. Provide a name and optional description for the IAM role. Then click **Create role**.
+
+## Review trust policy
+
+Next, select the **trust relationships** tab, which is where the trust policy of the role is defined. Ensure audience
+and subject are configured as shown below:
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Principal": {
+        "Federated": "arn:aws:iam::123456789012:oidc-provider/api.pulumi.com/oidc"
+      },
+      "Action": "sts:AssumeRoleWithWebIdentity",
+      "Condition": {
+        "StringEquals": {
+          "api.pulumi.com/oidc:aud": "aws:<pulumi-org-name>",
+          "api.pulumi.com/oidc:sub": "pulumi:cmk:pulumi.organization.login:<pulumi-org-name>"
+        }
+      }
+    }
+  ]
+}
+```
+
+Before you log out of the AWS console, make sure to make a note of your role’s ARN value as you will need it to set up
+the AWS KMS key as well as the Customer Managed Key in Pulumi Cloud.
+
+## Create the AWS KMS key
+
+1. In the navigation pane of the [KMS console](https://console.aws.amazon.com/kms/), choose **Customer managed keys**,
+   and then choose **Create key**.
+2. Select the **Symmetric** key type, the **Encrypt and decrypt** key usage and click **Next**.
+3. Add labels as needed, then click **Next**.
+4. Define key administrative permissions as needed, then click **Next**.
+5. Select the IAM role you created in the previous step under **Key users**, then click **Next**.
+6. Ensure that the **Key policy** defines the correct actions for the selected role, then finish the wizard.
+
+```json
+{
+  "Statement": [
+    {
+      "Sid": "Allow use of the key",
+      "Effect": "Allow",
+      "Principal": {
+        "AWS": "arn:aws:iam::123456789012:role/<role-name>"
+      },
+      "Action": [
+        "kms:Encrypt",
+        "kms:Decrypt",
+        "kms:GenerateDataKey"
+      ],
+      "Resource": "*"
+    }
+  ]
+}
+```
+
+Before you log out of the AWS console, make sure to make a note of your key’s ARN value and or alias ARN value as you
+will need it to set up the Customer Managed Key in Pulumi Cloud.
+
+## Add the Customer Managed Key in Pulumi Cloud
+
+Now you can add the Customer Managed Key in Pulumi Cloud as described in
+the [Customer Managed Keys documentation](/docs/pulumi-cloud/admin/customer-managed-keys/).