Skip to content

tidy BYOK documentation #7304

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
+441 −433
Open

tidy BYOK documentation #7304

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f757e07
tidy BYOK documentation
christinaausley Nov 12, 2025
f5df5f3
backport
christinaausley Nov 12, 2025
e30e8cc
minor UI adjustment
christinaausley Nov 12, 2025
1f7bc37
fix build
christinaausley Nov 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
99 changes: 50 additions & 49 deletions docs/components/saas/byok/aws-kms-setup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,56 +1,56 @@
---
id: aws-external-encryption-setup
title: "Encryption at rest using external encryption keys"
description: "Learn how to configure encryption at rest for a Camunda 8 SaaS Orchestration cluster using external Amazon KMS encryption keys."
description: "Learn how to configure encryption at rest for a Camunda 8 SaaS Orchestration cluster using external AWS KMS encryption keys."
---

Learn how to configure encryption at rest for your Camunda 8 SaaS Orchestration cluster using Amazon KMS.
Learn how to configure encryption at rest for your Camunda 8 SaaS Orchestration cluster using AWS KMS.

## Prerequisites

| Requirement | Description |
| --------------------- | -------------------------------------------------------------------------- |
| Amazon account | Access to an Amazon account with KMS permissions. |
| KMS permissions | Ability to create and manage KMS keys and attach policies. |
| Cluster region | KMS key must reside in the same Amazon region as your Camunda 8.8 cluster. |
| Technical familiarity | Some experience with Amazon console, IAM roles, and KMS is recommended. |
| Requirement | Description |
| --------------------- | --------------------------------------------------------------------------- |
| AWS account | Access to an AWS account with AWS KMS permissions. |
| AWS KMS permissions | Ability to create and manage AWS KMS keys and attach key policies. |
| Cluster region | The AWS KMS key must reside in the same AWS Region as your Camunda cluster. |
| Technical familiarity | Some experience with the AWS Management Console, IAM roles, and AWS KMS. |

:::warning Important

- Deleting or disabling your KMS key will make your cluster and data inaccessible.
- Key management is fully customer-side in Amazon KMS. Camunda cannot rotate keys.
- Deleting or disabling your AWS KMS key will make your cluster and data inaccessible.
- Key management is fully customer-side in AWS KMS. Camunda cannot rotate keys.
:::

## Step 1: Create a Camunda 8 SaaS Orchestration cluster

1. Sign in to the [Camunda Console](https://console.camunda.io/).
2. Navigate to the **Cluster** section and click **Create New Cluster**.
3. Select an Amazon region for your cluster.
2. Navigate to the **Cluster** section and click **Create new cluster**.
3. Select an AWS Region for your cluster.
4. Choose **Single region** or **Dual region backup**.
- Dual region requires one key per region. Keys can be separate.
5. Under **Encryption at rest**, choose **External**.
- Dual region requires one key per region; keys can be separate.
5. Under **Encryption at rest**, choose **External**.
Copy link
Contributor Author

@christinaausley christinaausley Nov 12, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@psetzer-camunda Are you still seeing this selection/UI in your environment? For some reason it wasn't showing for me.

![external option encryption at rest](./img/external-encryption.png)
6. Click **Create cluster**.

After creation, note the **Amazon Role ARN** displayed in the Console for your cluster.
After creation, note the **AWS Role ARN** displayed in the Console for your cluster.

## Step 2: Create and configure an AWS KMS key

You can create the key either via CLI or manually in the AWS console.
You can create the key either via AWS CLI or manually in the AWS Management Console.

### Option A: Create the key using AWS CLI

![create key using AWS CLI](./img/create-key-cli.png)

We provide automated scripts to create the necessary KMS key(s) with the correct policy and permissions. Choose the option that matches your backup configuration.
We provide automated scripts to create the necessary AWS KMS key(s) with the correct policy and permissions. Choose the option that matches your backup configuration.

#### Single-region backup

Use this script to create a single KMS key in the same region as the cluster.
Use this script to create a single AWS KMS key in the same Region as the cluster.

**What the script does:**

- Creates a KMS key with the required policy for Camunda access.
- Creates an AWS KMS key with the required policy for Camunda access.
- Sets up an alias for easier key management.
- Outputs the key ARN to provide to Camunda.

Expand All @@ -68,11 +68,11 @@ Use this script to create a single KMS key in the same region as the cluster.

#### Dual-region backup

Use this script to create a multi-region primary key in the cluster's region and a replica key in backup region.
Use this script to create a multi-Region primary key in the cluster’s Region and a replica key in the backup Region.

**What the script does:**

- Creates a multi-region primary key and replica key.
- Creates a multi-Region primary key and replica key.
- Applies the correct policies to both keys.
- Outputs both key ARNs to provide to Camunda.

Expand All @@ -84,7 +84,7 @@ Use this script to create a multi-region primary key in the cluster's region and
4. Copy the two outputted key ARNs and provide them to Camunda.

:::note Alternative
For dual-region setups, you can also run the single-region script twice—once in the cluster's region and once in backup region. Make sure to modify the `REGION` variable before creating the second key.
For dual-region setups, you can also run the single-region script twice—once in the cluster’s Region and once in the backup Region. Make sure to modify the `REGION` variable before creating the second key.
:::

### Option B: Manual key creation in AWS Console
Expand All @@ -93,16 +93,16 @@ For dual-region setups, you can also run the single-region script twice—once i

#### Single-region backup

1. **Sign in to AWS Console**
- Navigate to the KMS service and select the correct region.
1. **Sign in to the AWS Management Console**
- Navigate to the AWS KMS service and select the correct Region.
2. **Create a customer managed key**
- Click **Create key**.
- Choose **Symmetric** and **Encrypt and decrypt** usage.
3. **Add labels**
- Add an alias (e.g., `camunda-saas-byok`).
- Add a description (e.g., `KMS key for Camunda SaaS BYOK`).
- Add an alias (for example, `camunda-saas-byok`).
- Add a description (for example, `AWS KMS key for Camunda SaaS BYOK`).
4. **Define key administrators**
- Select IAM users/roles that will administer the key.
- Select IAM users or roles that will administer the key.
5. **Define key usage permissions**
- Skip this step; permissions are configured in the next step.
6. **Edit key policy**
Expand All @@ -113,24 +113,24 @@ For dual-region setups, you can also run the single-region script twice—once i

#### Dual-region backup

You can either create a multi-region key and replica or create two single-region keys.
You can either create a multi-Region key and replica or create two single-Region keys.

##### Method A: Multi-region key (recommended)
##### Method A: Multi-Region key (recommended)

1. Follow the single-region steps, selecting **Multi-Region key** under **Advanced options**.
2. After creating the primary key in cluster's region, go to **Regional replicas** and click **Create replica key**.
3. Select the region for the replica and confirm. The region should be the same as the backup region.
2. After creating the primary key in the cluster’s Region, go to **Regional replicas** and click **Create replica key**.
3. Select the Region for the replica and confirm. The Region should be the same as the backup Region.
4. Copy both key ARNs and provide them to Camunda.

##### Method B: Two single-region keys
##### Method B: Two single-Region keys

1. Create a key in the cluster's region using the single-region steps.
2. Repeat the process in the backup region using a different alias (e.g., `camunda-saas-byok-replica`).
1. Create a key in the cluster’s Region using the single-region steps.
2. Repeat the process in the backup Region using a different alias (for example, `camunda-saas-byok-replica`).
3. Provide both key ARNs to Camunda.

### Sample key policy

Replace `<tenant-role-arn>` with the **Amazon Role ARN** from Step 1, and `<customer-aws-account>` with your AWS account ID.
Replace `<tenant-role-arn>` with the **AWS Role ARN** from Step 1, and `<customer-aws-account>` with your AWS account ID.

<details>
<summary>View sample key policy JSON</summary>
Expand All @@ -149,7 +149,7 @@ Replace `<tenant-role-arn>` with the **Amazon Role ARN** from Step 1, and `<cust
"Resource": "*"
},
{
"Sid": "Allow Camunda tenant IAM Role basic key access",
"Sid": "Allow Camunda tenant IAM role basic key access",
"Effect": "Allow",
"Principal": {
"AWS": "<tenant-role-arn>"
Expand All @@ -164,7 +164,7 @@ Replace `<tenant-role-arn>` with the **Amazon Role ARN** from Step 1, and `<cust
"Resource": "*"
},
{
"Sid": "Allow Camunda tenant IAM Role to create grants for provisioning encrypted EBS volumes",
"Sid": "Allow Camunda tenant IAM role to create grants for provisioning encrypted EBS volumes",
"Effect": "Allow",
"Principal": {
"AWS": "<tenant-role-arn>"
Expand All @@ -180,17 +180,17 @@ Replace `<tenant-role-arn>` with the **Amazon Role ARN** from Step 1, and `<cust

:::warning Key policy guidance

- Don’t restrict the Camunda cluster **Role** from required KMS actions.
- Don’t restrict the Camunda cluster **role** from required AWS KMS actions.
- Key rotation is managed in AWS KMS; Camunda cannot rotate keys.
- Revoking access immediately breaks the cluster.
:::

## Step 3: Associate the KMS key with your Camunda cluster
## Step 3: Associate the AWS KMS key with your Camunda cluster

1. Return to the **Camunda Console** and locate the **KMS Key ARN** input field.
1. Return to the **Camunda Console** and locate the **AWS KMS key ARN** input field.
![KMS AWS key ARN input field](./img/aws-key-arn.png)
- For dual region, two fields will be available—enter the correct key for each region.
2. Paste your Amazon KMS Key ARN(s) from Step 2.
- For dual region, two fields will be available—enter the correct key for each Region.
2. Paste your AWS KMS key ARN(s) from Step 2.
3. Confirm and apply. Camunda provisions storage using your key for:
- Document handling storage
- Backup storage
Expand All @@ -203,32 +203,33 @@ Once a key is applied, it cannot be edited or replaced. To change keys, you must

## Step 4: Verify encryption and logging

- In the **Camunda Console**, check the cluster details **Encryption at rest** tab to confirm the **KMS Key ARN** is applied correctly.
- In the **Camunda Console**, check the cluster details **Encryption at rest** tab to confirm the **AWS KMS key ARN** is applied correctly.
![cluster details page](./img/cluster-details-page.png)
- In AWS, verify key usage:
1. Navigate to **Customer managed keys**.
2. Select your key and view **Key policy** and **Key usage** tabs.
3. Review **Recent activity** to confirm operations (Encrypt, Decrypt, GenerateDataKey).

### Monitor KMS usage
### Monitor AWS KMS usage

- **CloudTrail** logs all KMS operations.
- **CloudWatch** can trigger alarms for:
- **AWS CloudTrail** logs all AWS KMS operations.
- **Amazon CloudWatch** can trigger alarms for:
- Key deletion or disabling
- Unauthorized access attempts
- Policy or grant modifications
- Regularly review logs to detect unauthorized activity.
- Optionally, integrate with **Amazon EventBridge** for event-based monitoring and automation.

:::warning Monitoring reminder
You are responsible for monitoring key usage and access logs within your AWS account. Use CloudTrail and CloudWatch to detect misconfigurations or unauthorized access.
You are responsible for monitoring key usage and access logs within your AWS account. Use AWS CloudTrail, Amazon CloudWatch, and Amazon EventBridge to detect misconfigurations or unauthorized access.
:::

## Additional considerations

- **Key rotation**: Enable [automatic rotation](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html) or rotate manually in AWS KMS.
- **Cost**: Using Amazon KMS keys incurs storage and management charges in your Amazon account. See the [Camunda pricing model](/components/saas/byok/index.md#cost-implications).
- **Cost**: Using AWS KMS keys incurs storage and management charges in your AWS account. See the [BYOK cost implications](/components/saas/byok/index.md#cost-implications).
- **Failure scenarios**: Deleting keys or revoking permissions makes cluster data inaccessible. See [troubleshooting steps](/components/saas/byok/faq-and-troubleshooting.md#troubleshooting-external-encryption-keys).

:::note Reference
For more information, see the [Amazon KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
For more information, see the [AWS KMS documentation](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html).
:::
29 changes: 15 additions & 14 deletions docs/components/saas/byok/faq-and-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,21 @@
---
id: faq-and-troubleshooting
title: "FAQ & troubleshooting"
description: "Frequently asked questions and troubleshooting guidance for encryption at rest, encryption key types, and external encryption keys in Camunda 8 SaaS."
description: "Frequently asked questions and troubleshooting guidance for encryption at rest, encryption key types, and external AWS KMS encryption keys in Camunda 8 SaaS."
keywords:
[
"encryption",
"BYOK",
"KMS",
"AWS KMS",
"encryption keys",
"security",
"FAQ",
"troubleshooting",
]
---

Frequently asked questions and troubleshooting guidance for encryption at rest, encryption key types, and external encryption keys in Camunda 8 SaaS:
Frequently asked questions and troubleshooting guidance for encryption at rest, encryption key types, and external AWS KMS encryption keys in Camunda 8 SaaS.

## General questions

Expand All @@ -31,7 +32,7 @@ Applies to both Orchestration clusters and Web Modeler in Camunda 8 SaaS.
- Provider-managed (default): Cloud provider keys.
- Camunda-managed software key: Uses Google KMS at software protection level (FIPS 140-2 Level 1).
- Camunda-managed hardware key: Uses Google KMS HSM (FIPS 140-2 Level 3).
- External key: Customer-supplied KMS key (AWS only currently).
- External key: Customer-supplied AWS KMS key (AWS only currently).

Full comparison: [encryption at rest](/components/saas/encryption-at-rest.md)

Expand All @@ -45,12 +46,12 @@ Yes. All clusters use provider-managed encryption by default.

## Camunda-managed keys

- Software vs hardware: Software uses FIPS 140-2 Level 1, hardware uses FIPS 140-2 Level 3. Both support zero downtime rotation.
- Software vs. hardware: Software uses FIPS 140-2 Level 1, hardware uses FIPS 140-2 Level 3. Both support zero downtime rotation.
- Backups always use provider-managed keys.

## External encryption keys

- Use your own KMS key (AWS only) to encrypt cluster data. You control rotation and revocation and are responsible for monitoring via CloudTrail and CloudWatch.
- Use your own AWS KMS key to encrypt cluster data. You control rotation and revocation and are responsible for monitoring via AWS CloudTrail and Amazon CloudWatch.
- Supported on enterprise plans only.
- Revoking access immediately blocks cluster access; a new key or restored access is required.
- Camunda does not store your key.
Expand All @@ -59,21 +60,21 @@ Setup instructions: [external encryption setup guide](/components/saas/byok/aws-

## Other questions

- Performance: Minimal impact; handled by cloud KMS.
- Performance: Minimal impact; handled by AWS KMS.
- Per-cluster keys: Supported.
- Encryption in transit: TLS enforced.
- Cost: Charges apply in your AWS account. See [cost implications](/components/saas/byok/index.md#cost-implications).
- Cost: AWS KMS key storage and management charges apply in your AWS account. See [cost implications](/components/saas/byok/index.md#cost-implications).

## Troubleshooting external encryption keys

| Issue | Possible cause | Resolution |
| --------------------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster cannot access KMS key | Key policy does not grant the Camunda Cluster Amazon Role access | Update KMS key policy with correct Amazon Role ARN from Camunda Console. |
| Encryption/decryption errors | Key disabled, deleted, or in wrong region | Re-enable, restore, or create a new key in the correct region. |
| CloudTrail does not show activity | CloudTrail not enabled or retention too short | Enable CloudTrail in cluster region and store logs beyond 90 days. [View CloudTrail events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) |
| Key rotation issues | Cluster encryption update not supported | Create a new key and associate it with a new cluster. Verify encryption settings before use. |
| Issue | Possible cause | Resolution |
| --------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cluster cannot access AWS KMS key | Key policy does not grant the Camunda cluster AWS Role access | Update the AWS KMS key policy with the correct AWS Role ARN from the Camunda Console. |
| Encryption/decryption errors | Key disabled, deleted, or in wrong Region | Re-enable, restore, or create a new key in the correct AWS Region. |
| CloudTrail does not show activity | AWS CloudTrail not enabled or retention too short | Enable AWS CloudTrail in the cluster Region and store logs beyond 90 days. [View CloudTrail events](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) |
| Key rotation issues | Cluster encryption update not supported | Create a new key and associate it with a new cluster. Verify encryption settings before use. |

:::note Support
For persistent issues with key policies, region, or key status, contact [Amazon support](https://aws.amazon.com/contact-us/).
For persistent issues with key policies, Region, or key status, contact [AWS support](https://docs.aws.amazon.com/awssupport/latest/user/case-management.html).
For Camunda-specific cluster provisioning issues, contact [Camunda support](https://camunda.com/services/support-guide/).
:::
Loading
Loading