diff --git a/content/docs/pulumi-cloud/admin/_index.md b/content/docs/pulumi-cloud/admin/_index.md index 35d37dd9c573..38b26920bc20 100644 --- a/content/docs/pulumi-cloud/admin/_index.md +++ b/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. diff --git a/content/docs/pulumi-cloud/admin/audit-logs.md b/content/docs/pulumi-cloud/admin/audit-logs.md index 3c857a775bb4..17cb36725d4d 100644 --- a/content/docs/pulumi-cloud/admin/audit-logs.md +++ b/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 | diff --git a/content/docs/pulumi-cloud/admin/customer-managed-keys/_index.md b/content/docs/pulumi-cloud/admin/customer-managed-keys/_index.md new file mode 100644 index 000000000000..68553e0786e3 --- /dev/null +++ b/content/docs/pulumi-cloud/admin/customer-managed-keys/_index.md @@ -0,0 +1,103 @@ +--- +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. The +encrypted data itself does not change. + +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. The encrypted data itself does not change. +{{% /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. diff --git a/content/docs/pulumi-cloud/admin/customer-managed-keys/aws-kms.md b/content/docs/pulumi-cloud/admin/customer-managed-keys/aws-kms.md new file mode 100644 index 000000000000..7974e9e00552 --- /dev/null +++ b/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:", + "api.pulumi.com/oidc:sub": "pulumi:cmk:pulumi.organization.login:" + } + } + } + ] +} +``` + +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/" + }, + "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/).