KMS-Verschlüsselung im Secrets Manager

Mit der KMS-Verschlüsselung können alle Geheimniswerte in einer Secrets Manager-Instanz mithilfe eines STACKIT Key Management Service (KMS)-Schlüssels verschlüsselt werden. Diese Seite beschreibt die Voraussetzungen, die Einrichtung über die API (einschließlich curl-Beispielen) und wichtige Hinweise.

Übersicht

Was wird verschlüsselt? Alle Geheimniswerte einer Secrets Manager-Instanz.
Womit? Mit einer spezifischen KMS-Schlüsselversion (keyVersion).
Wer autorisiert? Ein Service Account, dessen E-Mail-Adresse in der KMS-Konfiguration der Instanz hinterlegt ist und der mindestens die Rolle „Secrets Manager Reader“ oder „Secrets Manager Admin“ besitzt.
Wann wird es definiert? Entweder während der Instanzerstellung oder später über ein Instanz-Update.
Wechseln/Entfernen: Bereits konfigurierte KMS-Schlüssel können gewechselt oder entfernt werden.
Portal UI: Derzeit keine Konfiguration über die Portal UI (geplant); verwenden Sie vorerst die API.

Voraussetzungen

Ein KMS-Schlüssel wurde erstellt: Erstellen Sie Key Ring, Schlüssel und Schlüsselversion in KMS (beachten Sie Region und Projekt). Siehe STACKIT KMS.
Service Account wurde erstellt: Erstellen und verwalten Sie den Service Account; geben Sie später dessen E-Mail in die Instanzkonfiguration ein. Weisen Sie mindestens die Rolle „Secrets Manager Reader“ oder „Secrets Manager Admin“ zu. Siehe STACKIT-Zugriffsverwaltung verstehen
API/CLI-Zugriff vorbereiten: Fordern Sie ein Zugriffstoken (Bearer-Token) an und halten Sie die Basis-URL der Secrets Manager-API (OpenAPI) bereit. Siehe Secrets Manager konfigurieren.
Hinweis zur Region: Stellen Sie eine konsistente regionId zwischen Secrets Manager und dem verwendeten KMS-Schlüssel sicher.

KMS-Konfigurationsdatenmodell

Die Instanzkonfiguration speichert ein kmsKey-Objekt:

{
 "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
 }
}

Feldübersicht

regionId: Region des KMS-Schlüssels
projectId: Projekt-ID, in der sich der KMS-Schlüssel befindet
serviceAccountEmail: Service Account, der KMS-Operationen für diese Instanz ausführt
keyRingId: ID des Key Rings
keyId: ID des Schlüssels innerhalb des Key Rings
keyVersion: Die spezifische Schlüsselversion, die zum Verschlüsseln von Geheimnissen verwendet wird

API-Beispiele (cURL)

Auth: Verwenden Sie ein Bearer-Token eines entsprechenden Service Accounts. Base URL: Setzen Sie SM_API auf die OpenAPI-Basis-URL der 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"

Eine Instanz mit einem KMS-Schlüssel erstellen

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

Beispiel

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
 }
 }'

Einen KMS-Schlüssel ändern oder später hinzufügen

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

Beispiel

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
   }
 }'

Einen KMS-Schlüssel wechseln oder entfernen

Wechseln: Führen Sie ein PUT wie oben beschrieben aus, jedoch mit den Daten des neuen* KMS-Schlüssels (keyId/keyVersion, etc.).
Entfernen: Je nach API-Version erfolgt das Entfernen durch
- Weglassen von kmsKey aus dem PUT payload oder
- explizites Setzen von kmsKey auf null.
  Prüfen Sie Ihre OpenAPI-Spezifikation für Ihre Version.

Portal UI

Derzeit ist es nicht möglich, KMS über die Portal UI zu konfigurieren. Diese Funktion ist geplant. Verwenden Sie bis dahin die API (siehe Beispiele oben).

Fehlerbehebung und Best Practices

403 / Permission denied (KMS/IAM):
Überprüfen Sie, ob der Service Account in serviceAccountEmail existiert und über die erforderlichen Rollen verfügt (mindestens_Secrets Manager Reader_ oder Admin). (at least Secrets Manager Reader or Admin).
Project mismatch:
Stellen Sie sicher, dass die projectId in der Instanzkonfiguration mit dem Projekt des KMS-Schlüssels übereinstimmt.
Region mismatch:
Stellen Sie sicher, dass die regionId der Instanz und die Region des KMS-Key übereinstimmen.
Prinzip der geringsten Berechtigung (Least Privilege):
Weisen Sie nur die minimal erforderlichen Berechtigungen zu und setzen Sie auf Aufgabentrennung.