Document the ECE install password by ChallenHB · Pull Request #9007 · elastic/docs-content

ChallenHB · 2026-10-23T17:42:10Z

Summary

Documents the install password that ECE 4.3 adds to protect the bootstrap secrets a host reads when it joins an installation. The feature is implemented in https://github.com/elastic/cloud/pull/159892 and tracked in https://github.com/elastic/cp-hosted-team/issues/5059.

deploy-manage/deploy/cloud-enterprise/install.md: new section, scoped to ECE 4.3, that explains what the password protects, how to start a new installation with it, how to set, generate, or remove it on an existing installation with set-install-password, and that it must only be set once every host runs 4.3 or later.
deploy-manage/deploy/cloud-enterprise/install-ece-on-additional-hosts.md: notes that additional hosts must be installed with the same password, either with --install-password or through the INSTALL_PASSWORD environment variable.

The new section links to the set-install-password reference page that the cloud PR adds, so this PR should merge after that one. Until then the cross-repo link check will fail.

Generative AI disclosure

Did you use a generative AI (GenAI) tool to assist in creating this contribution?

Yes
No

Tool(s) and model(s) used: Claude Code, Claude Fable 5.1

🤖 Generated with Claude Code

Add a section to the ECE installation page that explains how to protect the bootstrap secrets with an install password, and note on the additional-hosts page that such hosts must be installed with the same password. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

github-actions · 2026-10-23T17:42:44Z

Elastic Docs AI PR menu

Check the box to run an AI review for this pull request.

Review docs changes (docs-review). Status: not started.

Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

List the install password among the orchestrator-level security settings and explain what the bootstrap secrets expose by default. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

shainaraskas

I think this PR needs a little tweaking to bring attention to these concepts where they're most needed / fit in with the current docs structure (such as it is). let me know what you think.

shainaraskas · 2026-10-23T20:03:23Z

 - [**TLS certificates**](secure-your-elastic-cloud-enterprise-installation/manage-security-certificates.md): Apply security controls to network communications. With {{ece}}, you manage proxy certificates for the HTTP layer. The transport layer is managed by ECE.
 - [**Platform role-based access control**](/deploy-manage/users-roles/cloud-enterprise-orchestrator.md): Define the roles of users who have access to your organization and its resources. Note that you can also [manage non-cloud users and roles](/deploy-manage/users-roles/cluster-or-deployment-auth/defining-roles.md).
 - [**Authentication providers**](/deploy-manage/users-roles/cloud-enterprise-orchestrator.md): Integrate with external authentication providers, including Active Directory, LDAP, and SAML.
+- {applies_to}`ece: ga 4.3` [**Install password**](/deploy-manage/deploy/cloud-enterprise/install.md#ece-install-password): Require a password to add hosts to the installation, so that the secrets a new host reads while joining can't be read by other hosts on the network.


would link down and explain on this page instead

shainaraskas · 2026-10-23T20:04:57Z

 Security comes in layers, and running separate services on separate infrastructure is the last layer of defense, on top of other security features like the JVM security manager, system call filtering, and running nodes in isolated containers with no shared secrets.


+### Hosts that join the installation [ece-securing-install-password]


although this whole h2 is a little weird, I agree that this is an ok canonical home for this stuff compared to other options in this section. would port key details into here (e.g. set-install-password command, --generate, --unset)

shainaraskas · 2026-10-23T20:08:15Z

does the warning at the bottom of this page need to be tweaked as well?
https://www.elastic.co/docs/deploy-manage/deploy/cloud-enterprise/post-installation-steps

eedugon · 2026-10-26T13:04:07Z

I love the content of this PR and how it's written, @ChallenHB, thanks!

However the main issue here is where exactly to place every bit of the information, because our install docs are currently a bit messy (as @shainaraskas mentioned the main install doc is just a landing page about the install overall procedure and including there that information would make it useless for the reader following an actual and real installation doc with the steps).

Note that we have plans to improve the installation docs in a significant way and make the experience simpler, hopefully soon (cc: @georgewallace :) ), but currently we have multiple docs with the actual installation instructions and almost the same content, as Shaina mentions in one of her comments.

My proposal is to create a new doc ("Configure an ECE installation password" for example) with the majority of the narrative you have added in this PR instead of spreading it between the security and the install docs, and then add extra context, information and links in other pages, such as:

Security related doc : As this is clearly improves the security of the platform we should mention it there with a link to the new doc and some recommendations if needed (this is already done in the PR I'd say but maybe we add too much there).
Install instructions (Initial host vs other hosts): The actual installation instructions should recommend or mention the inclussion of the install password when installing a new system (applies_to 4.3), and also reminding its usage when adding hosts in systems where the password is set. This could be added through snippets, and linking to the new doc for more information about the "install password".
ECE upgrade doc: we could also mention that after upgrading to 4.3 the users could also setup the install password to further secure the platform, and link to the new doc, more than to the install docs.
Command reference (this should go to the cloud repo, maybe you already have a PR to add that).

Let me know your thoughts! I wouldn't have problems trying to apply some commits directly to the PR myself if you want @ChallenHB .

@shainaraskas, let me know your thoughts about putting the main narrative and procedures around the initial password in a dedicated new doc, as maybe it's a bad idea!

PS - because this new feature spans across installation, configuration (the pass can be changed, added, or removed at any time), and security, it might make sense the dedicated doc.

shainaraskas · 2026-10-26T17:50:38Z

@eedugon I agree with you mostly, but we can minimize a lot of the content in favor of the reference doc (which challen added over here for us :) ) - e.g. we probably don't need change/add/remove instructions directly in the core docs

ChallenHB · 2026-10-26T20:07:00Z

@eedugon
Your suggestions for the structure of the docs sounds good to me.

I wouldn't have problems trying to apply some commits directly to the PR myself if you want

That would be great!

AlexP-Elastic

Procedural 🟥 since it's my understanding this repo isn't versioned, so we have to wait until we release 4.3.0 in November to merge this?

shainaraskas · 2026-10-28T18:25:44Z

@AlexP-Elastic it's ideal to wait a little because 4.3 is a ways off, but if this was published early, the feature would be marked as planned rather than displaying 4.3, so users would understand the functionality is not yet available

eedugon · 2026-10-29T07:55:15Z

@shainaraskas , @AlexP-Elastic : In this case i think it would be better to wait until 4.3 is released to merge this PR. But I agree we could also merge earlier.

Even though https://www.elastic.co/docs/reference/cloud/cloud-enterprise/ece-installation-script-set-install-password is already published (and that's totally ok from my point of view, as it's an individual doc that shows ECE: planned with no extra implications), in this PR we are going to update a few existing docs to show the new behavior, and I'd say it's better to merge together with 4.3 if we have the chance.

Another option would be creating an ece-4.3 branch in docs-content, and merge there the doc updates (similar to what ECK folks do) before a final merging to main after the release is completed.

eedugon · 2026-10-29T07:59:08Z

@eedugon I agree with you mostly, but we can minimize a lot of the content in favor of the reference doc (which challen added over here for us :) ) - e.g. we probably don't need change/add/remove instructions directly in the core docs

Thanks for showing that! Definitely the existence of that doc would change a bit the narrative here, and I agree to minimize the content when possible!

@ChallenHB , as talked in private I'll share a few structural changes in a new commit here next week and we can review and decide together.

Add a dedicated security guide and shared snippets for initial and additional hosts. Link from installation, configuration, post-installation, and upgrade procedures, and remove duplicated content from the installation landing and security overview. AI-Assisted: OpenAI Codex (GPT-6.1), for restructuring, drafting, and validation.

eedugon · 2026-11-03T13:50:28Z

I've pushed c31c249 with the structural changes discussed:

Add a dedicated Configure an install password for ECE guide under ECE security, reusing the original narrative and linking to the command reference for password management. Clarify that the password is optional and isn't generated automatically.
Remove the install password section from the installation landing page.
Add shared first-host and additional-host snippets to the actual installation procedures, including Podman and air-gapped installations.
Link from configuration and post-installation guidance, distinguishing this protection from securing the local bootstrap-secrets.json file. Add an after-upgrade recommendation once all hosts run a compatible version.
Reduce the security overview to a brief description linking to the new guide.

New content is scoped to ECE 4.3+. No new Vale findings; the build reports no errors or warnings, with only existing repository hints causing the strict build to exit with code 1.

AI assistance: OpenAI Codex (GPT-6.1), for restructuring, drafting, and validation.

Move the local secrets file clarification into the post-installation warning and link to the install password guide. AI-Assisted: OpenAI Codex (GPT-6.1), for drafting and validation.

github-actions · 2026-11-03T13:54:30Z

🔍 Preview links for changed docs

✅ Elastic Docs Style Checker (Vale)

No issues found on modified lines!

The Vale linter checks documentation changes against the Elastic Docs style guide. To use Vale locally or report issues, refer to Elastic style guide for Vale.

ChallenHB · 2026-11-04T23:00:22Z

@eedugon
The content and structure looks good. I'm happy with a merge once we're ready for it.
Thanks again for adding your updates!

eedugon · 2026-11-05T19:11:11Z

@shainaraskas : let us know your thoughts on the new structure and hopefully final content. We would need a review from someone other than me as I've been applying the latest commits to the PR :)

shainaraskas

very nice - thanks for the contribution @ChallenHB and for the restructure, @eedugon

I find the note on the install pages to be a little chunky because it's long and pushes the command down, but I don't think we have an alternative atm.

shainaraskas · 2026-11-06T21:05:59Z

 bash <(curl -fsSL https://download.elastic.co/cloud/elastic-cloud-enterprise.sh) upgrade --user admin --pass $PASSWORD --cloud-enterprise-version {{version.ece}}
 ```

+## After the upgrade


this feels like it could get stale easily (e.g. for anyone who already set an install password after 4.2.0). are we trying to sell this feature prominently? if not, it might not belong on this page

ChallenHB requested a review from a team as a code owner October 23, 2026 17:42

Add the install password to the ECE security overview

9aa0c0a

List the install password among the orchestrator-level security settings and explain what the bootstrap secrets expose by default. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

shainaraskas reviewed Oct 23, 2026

View reviewed changes

AlexP-Elastic requested changes Oct 28, 2026

View reviewed changes

eedugon self-assigned this Oct 29, 2026

eedugon added 2 commits November 3, 2026 14:51

Merge branch 'main' into ece-install-password

679ac73

Clarify install password scope in the bootstrap secrets warning

927f404

Move the local secrets file clarification into the post-installation warning and link to the install password guide. AI-Assisted: OpenAI Codex (GPT-6.1), for drafting and validation.

eedugon requested a review from shainaraskas November 3, 2026 13:55

github-actions Bot deployed to docs-preview November 3, 2026 14:02

View deployment

eedugon requested a review from a team November 5, 2026 19:08

shainaraskas approved these changes Nov 6, 2026

View reviewed changes

		Security comes in layers, and running separate services on separate infrastructure is the last layer of defense, on top of other security features like the JVM security manager, system call filtering, and running nodes in isolated containers with no shared secrets.


		### Hosts that join the installation [ece-securing-install-password]

Conversation

ChallenHB commented Oct 23, 2026

Summary

Generative AI disclosure

Uh oh!

github-actions Bot commented Oct 23, 2026

Elastic Docs AI PR menu

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

shainaraskas Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas Oct 23, 2026

Choose a reason for hiding this comment

Uh oh!

shainaraskas commented Oct 23, 2026

Uh oh!

eedugon commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shainaraskas commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChallenHB commented Oct 26, 2026

Uh oh!

AlexP-Elastic left a comment

Choose a reason for hiding this comment

Uh oh!

shainaraskas commented Oct 28, 2026

Uh oh!

eedugon commented Oct 29, 2026

Uh oh!

eedugon commented Oct 29, 2026

Uh oh!

eedugon commented Nov 3, 2026

Uh oh!

github-actions Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

github-actions Bot commented Nov 3, 2026

✅ Elastic Docs Style Checker (Vale)

Uh oh!

ChallenHB commented Nov 4, 2026

Uh oh!

eedugon commented Nov 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

shainaraskas left a comment

Choose a reason for hiding this comment

Uh oh!

shainaraskas Nov 6, 2026

Choose a reason for hiding this comment

Uh oh!

This branch was successfully deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

eedugon commented Oct 26, 2026 •

edited

Loading

shainaraskas commented Oct 26, 2026 •

edited

Loading

github-actions Bot commented Nov 3, 2026 •

edited

Loading

eedugon commented Nov 5, 2026 •

edited

Loading