Skip to main content

Bring your own key (BYOK)

Register, list, update, or delete your customer managed keys (CMKs), associate CMKs with services, and view CMK usage across services in Aiven projects using the Aiven Console, Aiven Provider for Terraform, Aiven API, or the Aiven CLI.

important

Bring your own key (BYOK) is a BYOC enterprise feature. Contact Aiven to request access.

Encryption scope​

BYOK encrypts the following using your CMKs:

  • Backups: All backups created by Aiven services are encrypted with your CMK.
  • Service data at rest: CMKs protect all data stored by the service.
  • Data in transit between the service and backups: Encryption occurs on the service node before data leaves the cluster, so backup transfers use your CMK.

Prerequisites​

  • Key management service (KMS) that supports customer-managed keys in one of the supported cloud providers:
    • Google Cloud KMS: asymmetric RSA 2048 or RSA 4096 keys
    • Oracle Cloud Infrastructure (OCI) Vault: AES keys
    • AWS KMS: symmetric encryption keys (ENCRYPT_DECRYPT)

List CMK accessors​

List customer managed key (CMK) accessors - principals that need to be granted access to perform encrypt/decrypt operations on your behalf.

API endpoint​

GET /v1/project/PROJECT_ID/secrets/cmks/accessors

Reference: CMKAccessorsList API

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier

Sample request​

curl -X GET https://api.aiven.io/v1/project/PROJECT_ID/secrets/cmks/accessors \
  -H "Authorization: Bearer AIVEN_API_TOKEN"

Sample response​

A successful request returns a 200 OK status code and a JSON object with the accessors for each provider, for example:

{
  "accessors": {
    "gcp": {
      "access_group": "access.example.12345678-1234-1234-1234-123456789abc@aiven.io"
    },
    "oci": {
      "access_group": "ocid1.group.oc1..abcdABCD....",
      "access_tenant": "ocid1.tenancy.oc1..abcdABCD...."
    },
    "aws": {
      "role_arn": "arn:aws:iam::123456789012:role/aiven-cmk-anchor"
    }
  }
}
note

Use the accessor values returned by this operation when granting Aiven access to your key:

  • Google Cloud KMS: Grant the access_group email address the roles/cloudkms.cryptoOperator role on your key.
  • OCI Vault: Use access_tenant and access_group OCIDs to create cross-tenancy IAM policies.
  • AWS KMS: Use the role_arn as the trusted principal in your KMS key policy (see AWS KMS setup).

Set up customer-managed keys on your cloud provider​

Before registering a CMK with Aiven, set up the key and grant Aiven access on your cloud provider.

Google Cloud KMS setup​

Create a key ring​

gcloud kms keyrings create <keyring-name> \
  --location <region> \
  --project <your-project>

Create a CryptoKey​

gcloud kms keys create <key-name> \
  --location <region> \
  --keyring <keyring-name> \
  --purpose encryption \
  --project <your-project>

For HSM-backed keys:

gcloud kms keys create <key-name> \
  --location <region> \
  --keyring <keyring-name> \
  --purpose encryption \
  --protection-level hsm \
  --project <your-project>

Record the key resource name:

projects/<project>/locations/<location>/keyRings/<keyring>/cryptoKeys/<key-name>

Grant Aiven access to your key​

  1. Get Aiven's access group email using List CMK accessors.
  2. Grant the Cloud KMS CryptoKey Encrypter/Decrypter role to Aiven's group:
gcloud kms keys add-iam-policy-binding <key-name> \
  --location <region> \
  --keyring <keyring-name> \
  --project <your-project> \
  --member "group:<aiven-cmk-group>@aiven.io" \
  --role "roles/cloudkms.cryptoKeyEncrypterDecrypter"

Oracle Cloud Infrastructure (OCI) Vault setup​

OCI key validation can fail with a generic error when the key region is not available for BYOK. If key validation fails after you confirm the key OCID and IAM policy, contact Aiven support.

Create cross-tenancy IAM policies​

  1. Get Aiven's tenancy OCID and group OCID using List CMK accessors. Use OCI access_tenant for <aiven-tenancy-ocid> and OCI access_group for <aiven-cmk-group-ocid>.
  2. Create the policy in the root compartment of your tenancy.
  3. Create cross-tenancy IAM policies in your tenancy to grant Aiven access to the key:
oci iam policy create \
  --compartment-id <customer-tenancy-ocid> \
  --name aiven-cmk-access \
  --statements '[
    "define tenancy AT as <aiven-tenancy-ocid>",
    "define group AG as <aiven-cmk-group-ocid>",
    "admit group AG of tenancy AT to use keys in tenancy"
  ]'

All three statements are required. Do not remove the define group statement.

Optional: Restrict access to a specific key by adding a condition to the admit statement:

oci iam policy create \
  --compartment-id <customer-tenancy-ocid> \
  --name aiven-cmk-access \
  --statements '[
    "define tenancy AT as <aiven-tenancy-ocid>",
    "define group AG as <aiven-cmk-group-ocid>",
    "admit group AG of tenancy AT to use keys in tenancy where target.key.id = \"<key-ocid>\""
  ]'

Create a Vault​

oci kms management vault create \
  --compartment-id <compartment-ocid> \
  --display-name <vault-name> \
  --vault-type DEFAULT

For HSM-backed vaults:

oci kms management vault create \
  --compartment-id <compartment-ocid> \
  --display-name <vault-name> \
  --vault-type VIRTUAL_PRIVATE

Record the Vault's management endpoint and crypto endpoint.

Create a Master Encryption Key​

oci kms management key create \
  --compartment-id <compartment-ocid> \
  --display-name <key-name> \
  --endpoint <vault-management-endpoint> \
  --key-shape '{"algorithm": "AES", "length": 32}'

Record the key OCID:

ocid1.key.oc1.<region>.<hash>

AWS KMS setup​

Aiven authenticates to your AWS KMS key using cross-account IAM access. You grant access by adding Aiven's IAM role ARN as a trusted principal in your KMS key policy. No resources need to be created in Aiven's AWS account—everything is controlled through your key policy.

Step 1: Create a KMS key​

Create a symmetric encryption key in the AWS region where your Aiven services will run:

aws kms create-key \
  --description "Aiven CMK for data-at-rest encryption" \
  --key-usage ENCRYPT_DECRYPT \
  --origin AWS_KMS

Record the key ARN from the output:

arn:aws:kms:<region>:<account-id>:key/<key-id>
aws kms create-alias \
  --alias-name alias/aiven-cmk \
  --target-key-id <key-id>

Step 3: Grant Aiven access via the key policy​

Get Aiven's IAM role ARN using List CMK accessors (role_arn), then update your KMS key policy to allow Aiven to perform encrypt and decrypt operations.

The key policy must include the following statement:

{
  "Sid": "Allow Aiven to use this key for CMK operations",
  "Effect": "Allow",
  "Principal": {
    "AWS": "<aiven-role-arn>"
  },
  "Action": [
    "kms:Encrypt",
    "kms:Decrypt"
  ],
  "Resource": "*"
}

The full key policy must also retain the root account statement so that your IAM policies can still manage the key:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "Enable IAM policies for key management",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::<your-account-id>:root"
      },
      "Action": "kms:*",
      "Resource": "*"
    },
    {
      "Sid": "Allow Aiven to use this key for CMK operations",
      "Effect": "Allow",
      "Principal": {
        "AWS": "<aiven-role-arn>"
      },
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt"
      ],
      "Resource": "*"
    }
  ]
}

Apply the key policy:

aws kms put-key-policy \
  --key-id <key-id> \
  --policy-name default \
  --policy file://key-policy.json
note

You can revoke Aiven's access at any time by removing the Aiven principal from the key policy, or by disabling or deleting the key. All KMS operations performed by Aiven are logged in your AWS CloudTrail, giving you a full audit trail.

Manage a project CMK​

Use the Aiven Provider for Terraform, Aiven API, or Aiven CLI to manage customer managed keys (CMKs) for encrypting service data.

For per-service CMK assignment and rotation, see Manage service CMK associations.

Register CMK resource identifier​

Register a customer managed key resource identifier for an Aiven project.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.
  2. Click Register key.
  3. Select your cloud provider: AWS, Google Cloud, or Oracle.
  4. In the Grant access section, copy the Access group value and grant Aiven access to your key in your cloud provider's KMS. The dialog also shows a ready-to-use CLI command that you can copy and run.
  5. Under Key details, enter a Key name and the Key resource path.
  6. Optional: Select Set as project default to encrypt all new services with this key automatically.
  7. Click Validate and register.

When validation succeeds, a confirmation dialog appears. If the key is set as the project default, the dialog confirms it and suggests going to Service encryption to assign the key to existing services. Click Done.

If Aiven cannot verify access, a Cannot verify encrypt/decrypt access error appears. Check the access group permissions in your cloud provider and click Validate and register again.

Update CMK​

Update attributes or parameters on an existing customer managed key configuration.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.
  2. Find the key to set as default.
  3. Click Actions and select Set as default.

The key is marked Default in the key list. All new services in the project use this key unless you choose a different key at creation time.

Get CMK details​

Get the details of a customer managed key configuration.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.
  2. Click the key name to open its details page.

The details page shows the cloud provider, key ID, key resource path, last updated date, and whether the key is the project default. You can toggle the Default key setting and view all services using the key under Associated services.

List CMKs​

List all customer managed key configurations for a project.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.

The Bring your own key (BYOK) page lists all registered keys with their cloud provider, status, number of associated services, and creation date.

If no keys have been registered yet, the page shows a prompt to Register key.

Remove CMK​

Delete a customer managed key configuration.

note

You can delete a CMK only when it has no service associations in active, activating, or deactivating status. Move each linked service to another CMK or remove the CMK association before deletion.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.
  2. Click Actions next to the key to remove and select Remove.

If the key is in use by active services, a Cannot remove a key in use dialog appears. Remove the CMK from all connected services first, then try again.

You can also remove a key from its details page: click the key name, then click Remove in the top-right corner.

Manage service CMK associations​

Associate a specific customer managed key (CMK) with individual services during creation or update. This allows you to use different CMKs for different services, change CMKs for existing services, or remove CMK associations altogether.

Associate a CMK when creating a service​

Create a service with a specific CMK by providing the CMK ID in the service creation request.

Set cloud to control the cloud region for the new service.

  1. In the Aiven Console, open your project.
  2. Click Create service.
  3. Select a service type, cloud provider, and plan.
  4. In the Service details section, select a key from the Encryption key (BYOK) dropdown.
  5. Click Create service.

Change or remove the CMK for an existing service​

Update a service to use a different CMK or remove its CMK association.

API endpoint​

PUT /v1/project/PROJECT_ID/service/SERVICE_NAME

Path parameters​

ParameterTypeRequiredDescription
PROJECT_IDStringTrueProject identifier
SERVICE_NAMEStringTrueService name

Request body parameters​

ParameterTypeRequiredDescription
cmk_idStringFalseCustomer managed key (CMK) identifier to use for this service. Pass an empty UUID (00000000-0000-0000-0000-000000000000) to remove the CMK association and use Aiven-managed keys instead.

Sample request (change CMK)​

curl -X PUT https://api.aiven.io/v1/project/PROJECT_ID/service/SERVICE_NAME \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer AIVEN_API_TOKEN" \
  -d '{
        "cmk_id": "87654321-4321-4321-4321-87654321dcba"
      }'

Sample request (remove CMK association)​

curl -X PUT https://api.aiven.io/v1/project/PROJECT_ID/service/SERVICE_NAME \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer AIVEN_API_TOKEN" \
  -d '{
        "cmk_id": "00000000-0000-0000-0000-000000000000"
      }'

Sample response​

A successful request returns a 200 OK status code and a JSON object representing the updated service:

{
  "service": {
    "service_name": "my-pg-service",
    "service_type": "pg",
    "cloud_name": "google-europe-west3",
    "state": "REBALANCING",
    "cmk_id": "87654321-4321-4321-4321-87654321dcba"
  }
}

View CMK details in service information​

When you retrieve service information, the response now includes the cmk_id field showing which CMK is actively protecting that service's data. This allows you to verify encryption key usage and track which services are using which CMKs.

  1. In the Aiven Console, open your service.
  2. On the Overview page, go to Connection information.

The Encryption key (BYOK) row shows the key name and resource path. If the key is the project default, it is labeled Default.

List services associated with a CMK​

Find all services in a project that are using a specific customer managed key. This is useful for auditing, capacity planning, or managing CMK usage across your infrastructure.

  1. In the Aiven Console, open your project and click BYOK in the left sidebar.
  2. Click the key name to open its details page.

The Associated services section lists all services using the key, with their status and cloud region. To assign more services to this key, click Add service.

Related pages