elastic / elastic/docs-content
Document the API path for encrypting an existing deployment with a customer-managed key
- Dominant language
- No language data
- Stars
- 47
- Forks
- 261
- Avg merge
- 3d 12h
- Merged PRs (30d)
- 116
Description
## Page
[Use a customer-managed encryption key](https://www.elastic.co/docs/deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key) (`deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key.md`)
## What's missing
The **Encrypt an existing deployment with your key** section documents only the Elastic Cloud console flow (deployment **Security** page > **Encryption at rest** > **Manage encryption key**). Encrypting an existing deployment is also supported through the Elastic Cloud API, but the API path is not documented anywhere on the page.
Today the `settings.byok.key_resource_path` example appears only under **Create a deployment encrypted with your key**, which reads as though the API supports setting a key at creation time only.
## Why it matters
Customers adopting BYOK on an existing footprint typically have many deployments, so the API is the path they will actually use rather than clicking through each deployment in the console. The console-only documentation understates what the feature can do for exactly the audience most likely to need it.
An upcoming Elastic blog post announcing GA of BYOK for existing deployments references the API path, so readers who follow the docs link will not find it covered.
## Suggested change
Add an API subsection under **Encrypt an existing deployment with your key**, mirroring the structure already used in **Create a deployment encrypted with your key**:
- the endpoint and method used to set a customer-managed key on an existing deployment
- the required API key permissions
- a worked `curl` example showing `settings.byok.key_resource_path`
- a note on how to track the resulting plan change
The existing note that a customer-managed key cannot be edited or removed once set should apply to the API path too, so it is worth restating or cross-linking there.
## Related
- Docs PR marking this capability GA: elastic/docs-content#8166
- Release note: elastic/cloud#158683
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with deploy-manage/security/encrypt-deployment-with-customer-managed-encryption-key.md, especially the existing and create-deployment sections, then review the linked GA docs PR and release note for the API details. Done means the existing-deployment section documents the endpoint, permissions, curl example, plan tracking, and the key-removal restriction.
Written by the indexing model from the issue text.
Assessment
- Domain
- cloud, documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 72/100