elastic / elastic/docs-content

Document the API path for encrypting an existing deployment with a customer-managed key

Open Beginner friendly
#8,236 3 comments 0 reactions 0 assignees View on GitHub
Team:Admin
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.