# Migrate Local KMS to Cloud KMS (/docs/sombra/deploying/customizing-sombra/migrating-local-to-cloud-kms)

This guide explains how to migrate a self‑hosted Sombra from Local KMS to a cloud KMS. It uses AWS KMS as the concrete example, and is generalizable if other KMS providers are supported in the future.

## Migration constraints [#migration-constraints]

- No hybrid KMS: Sombra does not support using multiple KMS providers at the same time
- Hard cutover required: a maintenance window is needed to switch providers
- Encryption context mismatch: CEKs produced under Local KMS cannot be decrypted under a cloud KMS and vice‑versa

<Callout type="warn">
  In‑flight requests created under Local KMS will not be decryptable after you switch to a cloud KMS. Complete or cancel them before migration, or plan to restart them after cutover. See [Pause Processing](../../../dsr-automation/processing-requests/pause-processing.mdx) and [Cancelling a Request](../../../dsr-automation/processing-requests/cancelling-a-request.mdx).
</Callout>

## Risks and implications [#risks-and-implications]

- In‑progress DSRs started under Local KMS cannot proceed after cutover
- Files attached to requests that were encrypted under Local KMS will not be decryptable post‑cutover
- Focus on draining or pausing in‑flight requests before the cutover

## Prerequisites [#prerequisites]

1. Cloud KMS setup (AWS example)
   - Create a KMS key in your cloud provider
   - Grant Sombra permissions to use the key (for AWS, via IAM policy)
   - Obtain the key identifier (for AWS, the KMS key ARN)
2. Key management
   - Generate a new `JWT_ECDSA_KEY` for signing
   - Keep the old `JWT_ECDSA_KEY` alongside the new key (comma‑separated, new first). See [Migrating from Transcend‑Hosted Sombra](./migrating-from-transcend-hosted-sombra.mdx).
   - Store keys in your external secrets manager (e.g., External Secrets Operator, Vault). See [Secrets Management](./secrets-management.mdx).
3. Request status
   - Prefer to complete/cancel all in‑progress requests
   - Alternatively, pause DSR processing during the cutover and be prepared to restart previously in‑flight requests

## Migration window [#migration-window]

Plan a 1–2 hour maintenance window. During this window:

- Sombra is stopped
- Environment variables are switched to the cloud KMS
- Sombra is restarted and validated

## Migration steps [#migration-steps]

### Pre‑migration (before the window) [#premigration-before-the-window]

- Understand access before/after: Prior to migration, files from completed requests encrypted under Local KMS can be downloaded by data subjects (and via API/CLI). After migration, those files will no longer be decryptable.
- Optionally download completed requests for record‑keeping:
  - API reference: [Download keys for request files](/docs/api-reference/data-subject-request/get-v1-data-subject-request-id-download-keys) and [Download individual files](/docs/api-reference/data-subject-request/get-v1-files)
  - CLI: [Transcend request download-files](https://github.com/transcend-io/tools/blob/main/packages/cli/README.md#transcend-request-download-files)
  - Admin Dashboard: [Incoming Requests](https://app.transcend.io/privacy-requests/incoming-requests)
- Set up the cloud KMS key and access permissions
- Generate a new `JWT_ECDSA_KEY` and prepare both new and old keys for deployment
- Complete/cancel in‑progress requests, or plan to pause processing

### During migration (maintenance window) [#during-migration-maintenance-window]

1\. Stop Sombra
2\. Update environment variables (AWS example):

```shellscript
KMS_PROVIDER=AWS
AWS_KMS_KEY_ARN=<your-kms-key-arn>
AWS_REGION=<your-region>
JWT_ECDSA_KEY=<new-key>,<old-key>  # comma-separated, new first
```

1. Start Sombra
2. Verify the service starts and health checks pass

### Post‑migration [#postmigration]

- All new DSR requests use the cloud KMS
- Old requests remain visible in the admin UI, but associated files encrypted under Local KMS will not be decryptable
- Monitor logs and error rates; address any configuration or permission issues

## Rollback [#rollback]

If issues occur during the window:

1. Stop Sombra
2. Revert `KMS_PROVIDER=local`
3. Start Sombra

<Callout type="warn">
  Requests created under the cloud KMS after cutover cannot be decrypted under Local KMS if you roll back.
</Callout>

## FAQ [#faq]

- Can we run two KMS providers at once?
  - No. Hybrid operation is not supported; perform a hard cutover.
- What happens to historical downloads?
  - Files encrypted under Local KMS will not be decryptable after cutover; download what you need beforehand.
- Where should `JWT_ECDSA_KEY` be stored?
  - In external secrets management. Cloud KMS does not hold or sign with this key.
- How do we rotate keys post‑migration?
  - See the key rotation guide linked below.

## Related links [#related-links]

- [Key Management](./key-management.mdx)
- [Secrets Management](./secrets-management.mdx)
- [Rotating Sombra Keys](./key-rotation.mdx)