[WIP] Add guidance on reducing the number of Fleet integration policies

[vishaangelova]

Summary

Customers who monitor many hosts running the same service had no documented way to avoid creating one integration policy per host. The issue cites a customer asking whether 200 Oracle databases require 200 Oracle integrations, and reports that when they instead list all 200 hosts in a single integration policy, the integration turns unhealthy. Nothing in the docs explained why that happens or what to do instead.

This PR adds a new doc, Reduce the number of integration policies (scale-integration-policies.md), under Fleet and Elastic Agent → Manage integrations.

Closes #2166

Other changes

• Folds fleet-agent-environment-variables.md into the new page and deletes it. That stub only said "use the env provider" without showing why you'd want to; the new page is the same topic with the missing motivation and procedure. Its published URL is preserved through both mapped_pages and a redirects.yml entry that maps the old anchor to #reuse-one-integration-policy-with-variables.
• Adds entry points from the places readers hit this problem: both scaling-limit sections in agent-policy.md, the end of the add procedure in add-integration-to-policy.md, the manage-integrations.md table, and the Fleet-managed sections of providers.md and env-provider.md.

Verification

Product claims were checked against source rather than the issue text:

• title: Oracle DSN on the hosts variable, multi: true — elastic/integrations, packages/oracle/manifest.yml. The multi-value field is what makes the anti-pattern tempting, which is why the page leads with it.
• New hosts / Existing hosts tabs — step_select_hosts.tsx.
• Reusable integration policies gated on an Enterprise license — use_multiple_agent_policies.ts.
• Actions → View policy — agent policy actions_menu.tsx.
• elastic-agent inspect --variables — elastic-agent, internal/pkg/agent/cmd/inspect.go.

Follow-up

Integration policy conditions (new in 9.5) are a fourth consolidation technique, but they're currently undocumented for Fleet users anywhere. Rather than version-gate part of an otherwise cumulative page, that work is left for a separate PR that fixes dynamic-input-configuration.md#conditions — which is where the product's own Learn more link points — and then adds the technique here.

Generative AI disclosure

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

• Yes
• No

2. Tool(s) and model(s) used: Cursor (Claude Opus 5)

[github-actions]

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.

[github-actions]

🔍 Preview links for changed docs

• reference/fleet/add-integration-to-policy.md
• reference/fleet/agent-policy.md
• reference/fleet/env-provider.md
• reference/fleet/fleet-agent-environment-variables.md
• reference/fleet/manage-integrations.md
• reference/fleet/providers.md
• reference/fleet/scale-integration-policies.md

[github-actions]

Elastic Docs Style Checker (Vale)

Summary: 2 warnings found

⚠️ Warnings (2): Fix when the suggestion improves clarity or correctness.

File	Line	Rule	Message
reference/fleet/add-integration-to-policy.md	38	Elastic.Spelling	'thes' is a possible misspelling.
reference/fleet/scale-integration-policies.md	3	Elastic.MappedPages	Avoid editing mapped_pages unless you are preserving an existing URL mapping. Talk with your local technical writer before changing this key.

---

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.