Enhance Fleet & Agent docs with comprehensive deployment guides #4346

alexandra5000 · 2025-12-15T16:54:40Z

Summary

This PR adds detailed guides for deploying Fleet Server and Elastic Agent, including configuration flags, environment variables, and mutual TLS (mTLS) setup. The new documents provide organized information for various deployment models, ensuring users have access to best practices and prerequisites for successful implementation. Additionally, tips for configuration management and security considerations are included to aid users in effectively managing their deployments.

Closes #4146

Generative AI disclosure

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

Yes
No

If you answered "Yes" to the previous question, please specify the tool(s) and model(s) used (e.g., Google Gemini, OpenAI ChatGPT-4, etc.).

Tool(s) and model(s) used: Claude Sonnet 4.5 via Cursor

github-actions · 2025-12-15T16:55:45Z

Vale Linting Results

Summary: 11 suggestions found

💡 Suggestions (11)

File	Line	Rule	Message
reference/fleet/_snippets/best-practices-certificates.md	6	Elastic.FutureTense	'will be' might be in future tense. Write in the present tense to describe the state of the product as it is now.
reference/fleet/deploy-elastic-agent.md	57	Elastic.Acronyms	'SHA' has no definition.
reference/fleet/deploy-elastic-agent.md	114	Elastic.Capitalization	'or other outputs' should use sentence-style capitalization.
reference/fleet/deploy-elastic-agent.md	176	Elastic.Capitalization	'output configuration' should use sentence-style capitalization.
reference/fleet/deploy-elastic-agent.md	228	Elastic.Semicolons	Use semicolons judiciously.
reference/fleet/deploy-elastic-agent.md	230	Elastic.Capitalization	'Mutual TLS (mTLS) configuration' should use sentence-style capitalization.
reference/fleet/deploy-fleet-server.md	57	Elastic.Acronyms	'SHA' has no definition.
reference/fleet/deploy-fleet-server.md	149	Elastic.Acronyms	'SAN' has no definition.
reference/fleet/deploy-fleet-server.md	217	Elastic.Capitalization	'Mutual TLS (mTLS) configuration' should use sentence-style capitalization.
reference/fleet/install-fleet-managed-elastic-agent.md	45	Elastic.FutureTense	'will also' might be in future tense. Write in the present tense to describe the state of the product as it is now.
reference/fleet/install-fleet-managed-elastic-agent.md	47	Elastic.WordChoice	Consider using 'can, might' instead of 'may', unless the term is in the UI.

github-actions · 2025-12-15T16:56:59Z

🔍 Preview links for changed docs

alexandra5000 · 2025-12-16T10:11:44Z

Hi @karenzone - sorry to call you out like this, but would you have some time to review this?

The idea behind the PR is to create new pages that consolidate the (so far a bit scattered) info on Fleet/Agent deployments. The guides are split into sections by connection type. I decided to keep the platform-specific guides as separate pages and added links to the new pages where I thought it was relevant.

I was mostly working based on the existing docs and configuration examples, so in reality I didn't write a lot of truly "new" content, but still I feel like someone with Agent/Fleet experience should take a look at this - that's why I'm asking you 🙂

karenzone · 2025-12-17T00:00:33Z

Hi @karenzone - sorry to call you out like this, but would you have some time to review this?

@alexandra5000, I am OOO tomorrow, and returning on Thursday. I can review then.

karenzone

@alexandra5000, made a first pass to get a sense of what's going on here. I will make another pass tomorrow with some suggestions.

I understand why you placed these new topics where you did in the TOC. As they're so similar, I'm wondering if they should be closer together to reinforce that these two tasks are quite similar. I'll kick that around a bit.

alexandra5000 · 2025-12-19T21:26:16Z

@karenzone the problem I had with this is that the only logical place to put them together would be at the very top level (same as deployment-models.md, for example). I didn't feel like they belonged so high up though - this is more suitable for general or more abstract/informational pages IMO.

I'm looking forward to hearing your thoughts on this!

vishaangelova · 2025-12-19T22:31:50Z

Hey @alexandra5000 — we merged the PR adding applies_to tags to ingest-docs (#3238), which caused a number of conflicts in this PR. (Sorry about that!)

When you address the merge conflicts, please take into account the changes in #3238 as they have already been reviewed and approved by @karenzone and @bmorelli25.

karenzone · 2025-12-22T00:30:45Z

The book has outgrown its initial IA, and is tricky to add to. This PR could benefit from more pre-IA analysis with regard to the approach and location.

Fleet Server is an Elastic Agent with additional capabilities enabled, and the settings are similar for both. Maintaining the same content in two different places sets us up for content diverging. We have some capabilities for single sourcing content, and that approach is worth considering.

AI tends to be wordier than needed, and leans toward admonitions instead of normal content. Worth a look in context of this PR.

alexandra5000 · 2025-12-30T16:54:31Z

@vishaangelova Conflicts resolved, I paid attention to keep what you had in your PR 🫡

@karenzone Right, good points all. I made some changes to the content itself and the placement. I've also added some snippets to hopefully make it easier to maintain. I'm still thinking about other good ways to single-source the content.

vishaangelova · 2026-01-06T10:44:50Z

reference/fleet/add-fleet-server-kubernetes.md

+applies_to:
+  stack: ga


Let’s remove this as the applies_to in the metadata for this file is already added on lines 7-9 (current line numbering)

Suggested change

applies_to:

stack: ga

vishaangelova · 2026-01-06T10:49:32Z

reference/fleet/deploy-elastic-agent.md

+sub:
+  component_name: "Elastic Agent"
+  component_ref: "{{agent}}"


I don’t think you need to define the sub here, it’s not a local substitution, it’s already in the docs-content’s docset.yml: https://github.com/elastic/docs-content/blob/main/docset.yml#L134

So it would be enough to just use {{agent}} as a sub across all of the docs.

vishaangelova · 2026-01-06T10:58:36Z

reference/fleet/deploy-elastic-agent.md

+applies_to:
+  stack: ga


Regardless of how the agent is deployed on the host, you can use that agent with a Serverless project… With my current understanding of using applies_to in the frontmatter, I think here it should also include Serverless.

Suggested change

applies_to:

stack: ga

applies_to:

stack: ga

serverless: ga

vishaangelova · 2026-01-06T10:59:33Z

reference/fleet/deploy-elastic-agent.md

+mapped_pages:
+  - https://www.elastic.co/guide/en/fleet/current/deploy-elastic-agent.html


This page did not exist in previous doc versions, so you don’t need to add mapped_pages.

Suggested change

mapped_pages:

- https://www.elastic.co/guide/en/fleet/current/deploy-elastic-agent.html

vishaangelova · 2026-01-06T11:02:42Z

reference/fleet/deploy-fleet-server.md

+sub:
+  component_name: "Fleet Server"
+  component_ref: "{{fleet-server}}"


Similarly to my comment for the other doc, this sub is already defined in docs-content’s docset.yml: https://github.com/elastic/docs-content/blob/main/docset.yml#L137

You can just use {{fleet-server}} as a sub across all of the docs.

vishaangelova · 2026-01-06T11:12:37Z

reference/fleet/deploy-fleet-server.md

+mapped_pages:
+  - https://www.elastic.co/guide/en/fleet/current/deploy-fleet-server.html


Similarly to my previous comment:

Suggested change

mapped_pages:

- https://www.elastic.co/guide/en/fleet/current/deploy-fleet-server.html

vishaangelova · 2026-01-06T11:14:29Z

reference/fleet/deploy-fleet-server.md

+applies_to:
+  stack: ga


This should probably say serverlesss: unavailable because self-managed Fleet Server is not available on Serverless.

Suggested change

applies_to:

stack: ga

applies_to:

stack: ga

serverless: unavailable

vishaangelova · 2026-01-06T11:19:19Z

reference/fleet/secure-connections.md

I don’t agree with the deletions in this file. Let’s discuss this.

vishaangelova · 2026-01-06T11:25:26Z

reference/fleet/add-fleet-server-on-prem.md

-    * When using the **Advanced** option, it’s recommended to generate a unique service token for each {{fleet-server}}. For other ways to generate service tokens, refer to [`elasticsearch-service-tokens`](elasticsearch://reference/elasticsearch/command-line-tools/service-tokens-command.md).
-    * If you’ve configured a non-default port for {{fleet-server}} in the {{fleet-server}} integration, you need to include the `--fleet-server-host` and `--fleet-server-port` options in the `elastic-agent install` command. Refer to the [install command documentation](/reference/fleet/agent-command-reference.md#elastic-agent-install-command) for details.
+    * When using the **Advanced** option, it's recommended to generate a unique service token for each {{fleet-server}}. For other ways to generate service tokens, refer to [`elasticsearch-service-tokens`](elasticsearch://reference/elasticsearch/command-line-tools/service-tokens-command.md).
+    * If you've configured a non-default port for {{fleet-server}} in the {{fleet-server}} integration, you need to include the `--fleet-server-host` and `--fleet-server-port` options in the `elastic-agent install` command. For detailed information about all available configuration flags and environment variables, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md).


I disagree with the deletion of the link to the elastic-agent install command reference. I think this should still point to the agent command reference doc, and not to the “how-to” doc as the command reference doc should be the ultimate go-to for all available flags.

vishaangelova · 2026-01-06T11:30:10Z

reference/fleet/add-fleet-server-on-prem.md


            * Before running the `install` command, make sure you replace the values in angle brackets.
            * The URL specified by `--url` must match the DNS name used to generate the certificate specified by `--fleet-server-cert`.
+            * For comprehensive configuration details, including all available flags and environment variables, refer to [How to deploy Fleet Server](/reference/fleet/deploy-fleet-server.md).


This line doesn’t fit the list items or the purpose of the list. This info is also added on line 119… (parent list item)

Enhance Fleet & Agent docs with comprehensive deployment guides

a202cea

github-actions bot deployed to docs-preview December 15, 2025 16:55 View deployment

Add 'applies_to' section and update tips to notes in Fleet documentation

cba6981

github-actions bot deployed to docs-preview December 15, 2025 17:10 View deployment

Fix linting errors

f772cba

github-actions bot deployed to docs-preview December 16, 2025 08:18 View deployment

Fix linting

6ebb664

github-actions bot deployed to docs-preview December 16, 2025 08:22 View deployment

Remove redundant info

f29f0d3

github-actions bot deployed to docs-preview December 16, 2025 09:59 View deployment

alexandra5000 marked this pull request as ready for review December 16, 2025 10:11

alexandra5000 requested a review from a team as a code owner December 16, 2025 10:11

karenzone reviewed Dec 19, 2025

View reviewed changes

Include snippets and move content together + rephrase some sections

ce48aba

github-actions bot had a problem deploying to docs-preview December 30, 2025 11:24 Failure

Merge branch 'main' into review-SSL-TLS-CA

936a21a

github-actions bot deployed to docs-preview December 30, 2025 11:32 View deployment

vishaangelova reviewed Jan 6, 2026

View reviewed changes

reference/fleet/secure-connections.md

Copy link

Contributor

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don’t agree with the deletions in this file. Let’s discuss this.

vishaangelova reviewed Jan 6, 2026

View reviewed changes

		mapped_pages:
		- https://www.elastic.co/guide/en/fleet/current/deploy-elastic-agent.html

Enhance Fleet & Agent docs with comprehensive deployment guides #4346

Are you sure you want to change the base?

Enhance Fleet & Agent docs with comprehensive deployment guides #4346

Uh oh!

Conversation

alexandra5000 commented Dec 15, 2025

Summary

Generative AI disclosure

Uh oh!

github-actions bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Vale Linting Results

Uh oh!

github-actions bot commented Dec 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔍 Preview links for changed docs

Uh oh!

alexandra5000 commented Dec 16, 2025

Uh oh!

karenzone commented Dec 17, 2025

Uh oh!

karenzone left a comment

Choose a reason for hiding this comment

Uh oh!

alexandra5000 commented Dec 19, 2025

Uh oh!

vishaangelova commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

karenzone commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexandra5000 commented Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

vishaangelova Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vishaangelova Jan 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Dec 15, 2025 •

edited

Loading

github-actions bot commented Dec 15, 2025 •

edited

Loading

vishaangelova commented Dec 19, 2025 •

edited

Loading

karenzone commented Dec 22, 2025 •

edited

Loading

alexandra5000 commented Dec 30, 2025 •

edited

Loading

vishaangelova Jan 6, 2026 •

edited

Loading

vishaangelova Jan 6, 2026 •

edited

Loading

vishaangelova Jan 6, 2026 •

edited

Loading

vishaangelova Jan 6, 2026 •

edited

Loading

vishaangelova Jan 6, 2026 •

edited

Loading