[9.1.0][REQUEST]: Document how to use Kibana spaces with Fleet

[kpollich]

Description

In #1142, we introduced Fleet’s new privilege model with support for space-aware access control. This follow-up expands on how to use Fleet's space awareness capabilities:

• Enabling the space awareness feature
• Assigning Agent Policies to different spaces (and moving them)
• Making integration assets available across spaces

Enabling space awareness in Fleet

As of 9.1.0, Fleet supports a space-aware data model. This allows you to use Kibana spaces to manage Agent Policies and integrations separately per space. Combined with granular user roles, this enables true role-based access control for Elastic Agent management.

• New deployments on 9.1.0 or later: space awareness is enabled by default.
• Upgraded deployments from earlier versions: space awareness must be explicitly enabled.

To enable space awareness in upgraded deployments:

1. Navigate to the Fleet app.
2. Click the Settings tab.
3. Scroll to Advanced settings.
4. Under Migrate to space-aware agent policies, click Start migration.
5. Confirm the migration via the modal.

This is a one-time migration that copies your existing Fleet data into a new, space-aware model. Previous data will be preserved in snapshots in case rollback is needed.

Managing Agent Policies across spaces

To control where an Agent Policy is available:

1. Navigate to the Agent Policy’s Settings tab.

   

2. Use the Spaces dropdown to select one or more spaces.

   

Agent Policies can be assigned to multiple spaces. In the example below, the policy is visible in both the "Default" space and "My second space."

Access to a policy is still governed by each user's Fleet permissions within the selected spaces.

Managing integration assets across spaces

When you add an integration to an Agent Policy, its assets (dashboards, visualizations, etc.) are installed only in the current space by default.

If the Agent Policy spans multiple spaces, you'll need to install the integration's assets in each space manually:

1. Switch to the desired Kibana space.

2. Go to the Integrations app → Installed integrations tab.

3. Click the name of the integration.

   

4. Open the Assets tab.

   

5. Click Install Kibana assets in current space.

This installs dashboards and other UI assets into the selected space.

Note: Due to limitations in Kibana’s saved object model, integration assets are copied per space. These saved objects are considered managed and are readonly.

Resources

Previous docs work: #1142

Collaboration

The product team will provide the initial content.

Point of contact.

Main contact: @kpollich

Stakeholders: @elastic/fleet @nimarezainia

[benironside]

I added the instructions for enabling space awareness in upgraded deployments to /solutions/security/get-started/spaces-defend-faq — it would probably be good to replace that with a link to the doc that gets created as part of this issue, instead.

[nicpenning]

This installs dashboards and other UI assets into the selected space.

Note: Due to limitations in Kibana’s saved object model, integration assets are copied per space. These saved objects are considered managed and are readonly.

What is the behavior when upgrading integrations? Will it update those assets in all spaces or does each integration need to be upgraded in each space?

Secondarily, could it be clarified from which versions the policies can be upgraded from? Such as 8.x -> 9.0 -> 9.1 or at least mention that any support migration path will allow Fleet policies to be converted if applicable. Part of my wondering is: are there any fleet policies that would not be upgradeable due to earlier versions of fleet policies or will all be able to be upgraded to use space awareness? Worst case scenario, a policy could just be recreated to with with space awareness, I imagine.

[kpollich]

What is the behavior when upgrading integrations? Will it update those assets in all spaces or does each integration need to be upgraded in each space?

All the assets across all spaces will be updated as a part of the single integration upgrade operation.

Secondarily, could it be clarified from which versions the policies can be upgraded from? Such as 8.x -> 9.0 -> 9.1 or at least mention that any support migration path will allow Fleet policies to be converted if applicable. Part of my wondering is: are there any fleet policies that would not be upgradeable due to earlier versions of fleet policies or will all be able to be upgraded to use space awareness? Worst case scenario, a policy could just be recreated to with with space awareness, I imagine.

AFAIU there won't be any policies that fail to migrate due to compatibility issues.

The migration logic is relatively straightforward in that we take any existing agent/integration policies and create new saved objects for each of them with the underlying namespaceType property on the SO schema changed. Each saved object's attributes property (the actual user-facing fields) is brought along one-to-one. So, it's less of a data transformation and more of a copy/paste.

The migration logic lives here: https://github.com/elastic/kibana/blob/839cb471382ba41c40b8f66a6177648bef635ad1/x-pack/platform/plugins/shared/fleet/server/services/spaces/enable_space_awareness.ts

That being said, you are correct that recreating a policy after enabling the space awareness feature will always be a worst-case scenario that can resolve any kind of migration issue.

[nicpenning]

Excellent! It is very obvious that the team at Elastic is paying great attention to implementing such a needed feature. Looking forward to 9.1!! Nice job team!

[karenzone]

Link to PR: elastic/docs-content#2284