Configure customer-managed encryption keys

Set up customer-managed encryption keys (CMEK) with AWS KMS to encrypt Pinecone data with keys you control, using IAM roles and key policies.

This page describes how to set up and use customer-managed encryption keys (CMEK) to secure data within a Pinecone project. CMEK allows you to encrypt your data using keys that you manage in your cloud provider's key management system (KMS). Pinecone supports CMEK using Amazon Web Services (AWS) KMS.

Set up CMEK using AWS KMS

Before you begin

The following steps assume you have:

Access to the AWS console.
A Pinecone Enterprise plan.

1. Create a role

In the AWS console, create a role that Pinecone can use to access the AWS Key Management System (KMS) key. You can either grant Pinecone access to a key in your account, or if your customers provide their own keys, you can grant access to keys that are outside of your account.

Open the Amazon Identity and Access Management (IAM) console.
In the navigation pane, click Roles.
Click Create role.
In the Trusted entity type section, select Custom trust policy.
In the Custom trust policy section, enter one of the following JSON snippets.
Pick a snippet based on whether you want to allow Pinecone to assume a role from all regions or from explicit regions. Add an optional external ID for additional security. If you use an external ID, you must provide it to Pinecone when adding a CMEK key.

Explicit regions + external ID

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegionswithID",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1"
                ]
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key.
                    "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
                }
            }
        }
    ]
}

Explicit regions + no external ID

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPineconeToAssumeIntoRoleFromExplicitRegions",
            "Effect": "Allow",
            "Principal": {
                "AWS": [
                    // Explicit role per Pinecone region. Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-east-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_us-west-2",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-west-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_eu-central-1",
                    "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_ap-southeast-1"
                ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

All regions + external ID

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowPineconeToAssumeIntoRoleFromAllRegions",
            "Effect": "Allow",
            "Principal": {
                "AWS": "*"
            },
            "Action": "sts:AssumeRole",
            "Condition": {
                "StringEquals": {
                    // Optional. Replace with a UUID v4 for additional security. If you use an external ID, you must provide it to Pinecone when adding an API key.
                    "sts:ExternalId": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
                },
                "StringLike": {
                    // Replace XXXXXXXXXXXX with Pinecone's AWS account number.
                    "aws:PrincipalArn": "arn:aws:iam::XXXXXXXXXXXX:role/pinecone_cmek_access_*"
                }
            }
        }
    ]
}

Click Next.
Keep the default permissions as is and click Next.
Enter a Role name and click Create role.
Copy the Role ARN (e.g., arn:aws:iam::XXXXXX:role/YYYYYY). This will be used to create a CMEK-enabled project.

Open the Amazon Identity and Access Management (IAM) console.
In the navigation pane, click Roles.
Click Create role.
In the Trusted entity type section, select Custom trust policy.

In the Custom trust policy section, enter the following JSON:

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt",
                "kms:Encrypt"
            ],
            "Resource": "arn:aws:kms:*:XXXXXX:key/*"
        }
    ]
}

Replace XXXXXX with the account ID of the customer who owns the key.
Add a Statement array for each customer account ID.

Click Next.
Keep the default permissions as is and click Next.
Enter a Role name and click Create role.
Copy the Role ARN (e.g., arn:aws:iam::XXXXXX:role/YYYYYY). This will be used to create a CMEK-enabled project.

2. Create an AWS KMS key

In the AWS console, create the KMS key that Pinecone will use to encrypt your data:

Open the Amazon Key Management Service (KMS) console.
In the navigation pane, click Customer managed keys.
Click Create key.
In the Key type section, select Symmetric.
In the Key usage section, select Encrypt and decrypt.
Under Advanced options > Key material origin, select KMS.
In the Regionality section, select Single-Region key.

You can create a multi-regional key to safeguard against data loss in case of regional failure. However, Pinecone only accepts one Key ARN per project. If you set a multi-regional key and need to change the Key ARN to switch region, please contact Support for help.
Click Next.
Enter an Alias and click Next.
Keep the default administrators as is and click Next.
Select the role you created from the Key users list and click Next.
Click Finish.
Copy the Key ARN (e.g., arn:aws:kms:us-east-1:XXXXXXX:key/YYYYYYY). This will be used to create a CMEK-enabled project.

AWS KMS automatic key rotation is supported. Pinecone references the Key ARN, not the underlying key material. As long as the Key ARN remains unchanged and accessible, you can perform key rotations inside AWS KMS without making any changes in Pinecone.

3. Create a CMEK-enabled project

Once your role and key is configured, you can create a CMEK-enabled project using the Pinecone console:

Go to Settings > Organization settings > Projects.
Click +Create project.
Enter a Name.
Select Encrypt with Customer Managed Encryption Key.
Click Create project.
Copy and save the generated API key in a secure place for future use.

You will not be able to see the API key again after you close the dialog.
Click Close.

Add a key

To start encrypting your data with a customer-managed key, you need to add the key to the CMEK-enabled project using the Pinecone console:

Go to Manage > CMEK for the CMEK-enabled project.
Click Add CMEK.

You can only add one key per project, and you cannot change the key in Pinecone once it is set.
Enter a Key name.
Enter the Role ARN for the role you created.
Enter a Key ARN for the key you created.
If you created a role with an external ID, enter the External ID. If not, leave this field blank.
Click Create key.

Delete a key

Before a key can be deleted from a project, all indexes in the project must be deleted. Then, you can delete the key using the Pinecone console:

Go to the Manage > CMEK tab for the project in which the key was created.
For the key you want to delete, click the ellipsis (...) menu > Delete.
Enter the key name to confirm deletion.
Click Delete key.

Limitations

CMEK can be enabled for serverless indexes in AWS regions only.
Backups are unavailable for indexes created in a CMEK-enabled project.
You can't change a key once it's set.
You can add only one key per project.