KMS encryption in the Secrets Manager

With KMS encryption, all secret values in a Secrets Manager instance can be encrypted using a STACKIT Key Management Service (KMS) key. This page describes the prerequisites, the setup via API (including curl examples), and important notes.

Overview

What is encrypted? All secret values of a Secrets Manager instance.
With what? With a specific KMS key version (keyVersion).
Who authorizes? A service account whose email address is stored in the instance’s KMS configuration and which has at least the role “Secrets Manager Reader” or “Secrets Manager Admin” role.
When to define it? Either during instance creation or later via an instance update.
Switch/remove: Already configured KMS keys can be switched or removed.
Portal UI: Currently no configuration via the Portal UI (planned); for now use the API.

Prerequisites

A KMS key has been created: Create key ring, key, and key version in KMS (note region and project). See STACKIT KMS.
Service account has been created: Create and manage the service account; later put its email into the instance configuration. Assign at least the role “Secrets Manager Reader” or “Secrets Manager Admin”. See Understand STACKIT IAM
Prepare API/CLI access: Obtain an access token (Bearer token) and have the Secrets Manager API base URL (OpenAPI) ready. See Configure the Secrets Manager.
Region note: Ensure consistent regionId between Secrets Manager and the KMS key you use.

KMS configuration data model

The instance configuration stores a kmsKey object:

{
 "kmsKey": {
 "regionId": "string",
 "projectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "serviceAccountEmail": "string",
 "keyRingId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "keyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
 "keyVersion": 0
 }
}

Field overview

regionId: Region of the KMS key
projectId: Project ID where the KMS key resides
serviceAccountEmail: Service account that performs KMS operations for this instance
keyRingId: ID of the key ring
keyId: ID of the key within the key ring
keyVersion: The specific key version used to encrypt secrets

API examples (cURL)

Auth: Use a Bearer token of an appropriate service account.
Base URL: Set SM_API to the OpenAPI base URL of the Secrets Manager API.

## Example: environment variables
export SM_API="<SECRETS_MANAGER_API_BASE_URL>"
export TOKEN="<BEARER_TOKEN>"
export PROJECT_ID="00000000-0000-0000-0000-000000000000"
export REGION_ID="eu01"

Create an instance with a KMS key

HTTP
POST /v2/projects/{projectId}/regions/{regionId}/instances

Example

export INSTANCE_NAME="my-secrets-instance"

curl -sS -X POST "$SM_API/v2/projects/$PROJECT_ID/regions/$REGION_ID/instances" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
 "name": "'"$INSTANCE_NAME"'",
 "kmsKey": {
 "regionId": "'"$REGION_ID"'",
 "projectId": "'"$PROJECT_ID"'",
 "serviceAccountEmail": "svc-secrets@customer.example",
 "keyRingId": "11111111-1111-1111-1111-111111111111",
 "keyId": "22222222-2222-2222-2222-222222222222",
 "keyVersion": 1
 }
 }'

Change a KMS key, or add one later

HTTP
PUT /v2/projects/{projectId}/regions/{regionId}/instances/{instanceId}

Example

export INSTANCE_ID="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee"

curl -sS -X PUT "$SM_API/v2/projects/$PROJECT_ID/regions/$REGION_ID/instances/$INSTANCE_ID" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -d '{
 "name": "my-secrets-instance",
 "kmsKey": {
 "regionId": "'"$REGION_ID"'",
 "projectId": "'"$PROJECT_ID"'",
 "serviceAccountEmail": "svc-secrets@customer.example",
 "keyRingId": "11111111-1111-1111-1111-111111111111",
 "keyId": "33333333-3333-3333-3333-333333333333",
 "keyVersion": 2
 }
 }'

Switch or remove a KMS key

Switch: Perform a PUT as above but with the data of the new KMS key (keyId/keyVersion, etc.).
Remove: Depending on the API version, removal is achieved by
- omitting kmsKey from the PUT payload or
- setting kmsKey explicitly to null.
  Check your OpenAPI specification for your version.

Portal UI

At the moment it is not possible to configure KMS via the Portal UI. This feature is planned. Until then, use the API (see examples above).

Troubleshooting and best practices

403 / Permission denied (KMS/IAM):
Verify that the service account in serviceAccountEmail exists and has the required roles (at least Secrets Manager Reader or Admin).
Project mismatch:
Ensure that the projectId in the instance configuration matches the project of the KMS key.
Region mismatch:
Ensure that the instance regionId and the KMS key’s region match.
Principle of least privilege:
Assign only the minimum necessary permissions and separate duties.