FleetClient

Client for the Kibana Fleet core API.

Fleet provides centralized management of Elastic Agents and their policies. This client covers the Fleet internals: initializing Fleet, reading and updating the global and per-space Fleet settings, checking Fleet Server health, and checking the current user’s Fleet permissions.

All Fleet APIs are space-aware: every method accepts an optional space_id to target a specific Kibana space.

class kibana._sync.client.fleet.FleetClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: NamespaceClient

Client for the Kibana Fleet core API (setup, settings, health).

Fleet provides a web-based UI and APIs in Kibana for centrally managing Elastic Agents and their policies. This client covers the Fleet internals: initializing Fleet (setup), reading and updating the global Fleet settings, reading and updating the per-space Fleet settings, checking Fleet Server health, and checking the current user’s Fleet permissions.

All Fleet APIs are space-aware: every method accepts an optional space_id to target a specific Kibana space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Initialize Fleet (idempotent)
>>> result = client.fleet.setup()
>>> print(result.body["isInitialized"])
True
>>>
>>> # Read the global Fleet settings
>>> settings = client.fleet.get_settings()
>>> print(settings.body["item"]["id"])
fleet-default-settings

Initializing Fleet

Fleet setup creates the Elasticsearch resources Fleet needs to operate. It is idempotent and safe to call multiple times:

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

result = client.fleet.setup()
print(result.body["isInitialized"])   # True
print(result.body["nonFatalErrors"])  # []

Checking Permissions and Fleet Server Health

# Check whether the current user can use Fleet
perms = client.fleet.check_permissions()
if not perms.body["success"]:
    print(perms.body["error"])  # e.g. "MISSING_PRIVILEGES"

# Also verify Fleet Server setup privileges
perms = client.fleet.check_permissions(fleet_server_setup=True)

# Check the health of a configured Fleet Server host by its ID
health = client.fleet.health_check(id="fleet-server-host-id-1")
print(health.body["status"])  # "ONLINE" or "OFFLINE"

Global Fleet Settings

# Read the global Fleet settings
settings = client.fleet.get_settings()
item = settings.body["item"]
print(item["prerelease_integrations_enabled"])

# Update a setting (only the provided fields are changed)
client.fleet.update_settings(prerelease_integrations_enabled=True)

# Configure automatic deletion of unenrolled agents
client.fleet.update_settings(
    delete_unenrolled_agents={
        "enabled": True,
        "is_preconfigured": False,
    }
)

Per-Space Fleet Settings

Space settings restrict which data stream namespace prefixes may be used in a Kibana space. Note that Kibana 9.4.3 rejects prefixes containing a - character:

# Read the space settings for the default space
space_settings = client.fleet.get_space_settings()
print(space_settings.body["item"]["allowed_namespace_prefixes"])

# Restrict namespaces in a specific space
client.fleet.update_space_settings(
    allowed_namespace_prefixes=["teama", "teamb"],
    space_id="marketing",
)

# Remove all restrictions again
client.fleet.update_space_settings(
    allowed_namespace_prefixes=[],
    space_id="marketing",
)
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize the FleetClient.

Parameters:

  • client (Kibana) – The parent Kibana client instance to delegate requests to.

  • default_space_id (str | None) – Optional default space ID for all operations.

  • validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> fleet_client = FleetClient(kibana_client)
setup(*, space_id=None, validate_spaces=None)[source]

Initiate Fleet setup.

Initialize Fleet and create the necessary Elasticsearch resources for Fleet to operate. Safe to call multiple times (idempotent). Returns the initialization status and any non-fatal errors encountered during setup.

Parameters:

  • space_id (str | None) – Optional space ID to run the setup in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isInitialized: True if Fleet is ready to accept agent enrollment

  • nonFatalErrors: List of {"name", "message"} objects describing non-blocking issues encountered during setup

Return type:

ObjectApiResponse containing the setup result

Raises:

Example

>>> result = client.fleet.setup()
>>> print(result.body["isInitialized"])
True
>>> print(result.body["nonFatalErrors"])
[]
get_settings(*, space_id=None, validate_spaces=None)[source]

Get settings.

Get the global Fleet settings.

Parameters:

  • space_id (str | None) – Optional space ID to read the settings from.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the global Fleet settings, including id, version, prerelease_integrations_enabled, delete_unenrolled_agents, preconfigured_fields, ilm_migration_status and secret-storage requirement flags.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> settings = client.fleet.get_settings()
>>> print(settings.body["item"]["prerelease_integrations_enabled"])
False
update_settings(*, additional_yaml_config=None, delete_unenrolled_agents=None, has_seen_add_data_notice=None, integration_knowledge_enabled=None, kibana_ca_sha256=None, kibana_urls=None, prerelease_integrations_enabled=None, space_id=None, validate_spaces=None)[source]

Update settings.

Update the global Fleet settings. Only the provided fields are changed; omitted fields keep their current values.

Parameters:

  • additional_yaml_config (str | None) – Deprecated. Additional Fleet Server YAML configuration.

  • delete_unenrolled_agents (dict[str, Any] | None) – Automatic deletion policy for unenrolled agents, an object with the required keys enabled (bool) and is_preconfigured (bool).

  • has_seen_add_data_notice (bool | None) – Deprecated. Whether the “add data” notice has been dismissed.

  • integration_knowledge_enabled (bool | None) – Whether integration knowledge content is enabled.

  • kibana_ca_sha256 (str | None) – Deprecated. SHA-256 of the Kibana CA certificate.

  • kibana_urls (list[str] | None) – Deprecated. Kibana URLs used by agents (maximum 10 URI strings).

  • prerelease_integrations_enabled (bool | None) – Whether pre-release integrations may be installed from the package registry.

  • space_id (str | None) – Optional space ID to update the settings in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the updated global Fleet settings.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.fleet.update_settings(
...     prerelease_integrations_enabled=True,
... )
>>> print(updated.body["item"]["prerelease_integrations_enabled"])
True
get_space_settings(*, space_id=None, validate_spaces=None)[source]

Get space settings.

Get the Fleet settings for the current Kibana space. Added in Kibana 9.1.0.

Parameters:

  • space_id (str | None) – Optional space ID to read the space settings from.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • allowed_namespace_prefixes: List of namespace prefixes allowed in this space

  • managed_by: Optional identifier of the manager of these settings

Return type:

ObjectApiResponse containing an item object with

Raises:

Example

>>> settings = client.fleet.get_space_settings()
>>> print(settings.body["item"]["allowed_namespace_prefixes"])
[]
update_space_settings(*, allowed_namespace_prefixes=None, space_id=None, validate_spaces=None)[source]

Create or update space settings.

Create or update the Fleet settings for the current Kibana space. Added in Kibana 9.1.0.

Note: as of Kibana 9.4.3 the live server rejects prefixes that contain a - character (Must not contain -), even though the published OpenAPI schema allows arbitrary strings.

Parameters:

  • allowed_namespace_prefixes (list[str] | None) – List of namespace prefixes (maximum 10) that data streams in this space are allowed to use. Pass an empty list to remove all restrictions.

  • space_id (str | None) – Optional space ID to update the space settings in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the updated allowed_namespace_prefixes (and optionally managed_by).

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.fleet.update_space_settings(
...     allowed_namespace_prefixes=["teama", "teamb"],
... )
>>> print(updated.body["item"]["allowed_namespace_prefixes"])
['teama', 'teamb']
health_check(*, id, space_id=None, validate_spaces=None)[source]

Check Fleet Server health.

Check the health status of a Fleet Server instance by its host ID. Returns the server status and name if available.

Parameters:

  • id (str) – The Fleet Server host ID to check (the ID of a Fleet Server host configured in Fleet settings).

  • space_id (str | None) – Optional space ID to run the health check in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • status: Fleet Server status (e.g. "ONLINE" or "OFFLINE")

  • name: The Fleet Server name, if available

  • host_id: The checked host ID, if the host is unreachable

Return type:

ObjectApiResponse containing the health check result

Raises:

Example

>>> health = client.fleet.health_check(id="fleet-server-host-id-1")
>>> print(health.body["status"])
ONLINE
check_permissions(*, fleet_server_setup=None, space_id=None, validate_spaces=None)[source]

Check permissions.

Check whether the current user has the required permissions to use Fleet. Optionally verifies Fleet Server setup privileges.

Parameters:

  • fleet_server_setup (bool | None) – When True, check Fleet Server setup privileges in addition to standard Fleet privileges.

  • space_id (str | None) – Optional space ID to check the permissions in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • success: True if the user has all required permissions

  • error: Present when success is False; one of "MISSING_SECURITY", "MISSING_PRIVILEGES" or "MISSING_FLEET_SERVER_SETUP_PRIVILEGES"

Return type:

ObjectApiResponse containing the permission check result

Raises:

Example

>>> perms = client.fleet.check_permissions()
>>> print(perms.body["success"])
True
perform_request(method, path, *, params=None, headers=None, body=None)

Perform an HTTP request via the parent client with space context enhancement.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)

  • path (str) – API endpoint path

  • params (dict[str, Any] | None) – Query parameters

  • headers (dict[str, str] | None) – Request headers

  • body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]

AsyncFleetClient

Asynchronous version of the FleetClient for use with async/await syntax.

class kibana._async.client.fleet.AsyncFleetClient(client, default_space_id=None, validate_spaces=True)[source]

Bases: AsyncNamespaceClient

Async client for the Kibana Fleet core API (setup, settings, health).

Fleet provides a web-based UI and APIs in Kibana for centrally managing Elastic Agents and their policies. This client covers the Fleet internals: initializing Fleet (setup), reading and updating the global Fleet settings, reading and updating the per-space Fleet settings, checking Fleet Server health, and checking the current user’s Fleet permissions.

All Fleet APIs are space-aware: every method accepts an optional space_id to target a specific Kibana space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Initialize Fleet (idempotent)
>>> result = await client.fleet.setup()
>>> print(result.body["isInitialized"])
True
>>>
>>> # Read the global Fleet settings
>>> settings = await client.fleet.get_settings()
>>> print(settings.body["item"]["id"])
fleet-default-settings

Usage

The AsyncFleetClient provides the same methods as FleetClient but all methods are async and must be awaited:

from kibana import AsyncKibana
import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        # Initialize Fleet (async)
        result = await client.fleet.setup()
        print(result.body["isInitialized"])

        # Read and update the global settings (async)
        settings = await client.fleet.get_settings()
        await client.fleet.update_settings(
            prerelease_integrations_enabled=True
        )

        # Check permissions (async)
        perms = await client.fleet.check_permissions()
        print(perms.body["success"])

asyncio.run(main())
__init__(client, default_space_id=None, validate_spaces=True)[source]

Initialize the AsyncFleetClient.

Parameters:

  • client (AsyncKibana) – The parent AsyncKibana client instance to delegate requests to.

  • default_space_id (str | None) – Optional default space ID for all operations.

  • validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> fleet_client = AsyncFleetClient(kibana_client)
async setup(*, space_id=None, validate_spaces=None)[source]

Initiate Fleet setup.

Initialize Fleet and create the necessary Elasticsearch resources for Fleet to operate. Safe to call multiple times (idempotent). Returns the initialization status and any non-fatal errors encountered during setup.

Parameters:

  • space_id (str | None) – Optional space ID to run the setup in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • isInitialized: True if Fleet is ready to accept agent enrollment

  • nonFatalErrors: List of {"name", "message"} objects describing non-blocking issues encountered during setup

Return type:

ObjectApiResponse containing the setup result

Raises:

Example

>>> result = await client.fleet.setup()
>>> print(result.body["isInitialized"])
True
>>> print(result.body["nonFatalErrors"])
[]
async get_settings(*, space_id=None, validate_spaces=None)[source]

Get settings.

Get the global Fleet settings.

Parameters:

  • space_id (str | None) – Optional space ID to read the settings from.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the global Fleet settings, including id, version, prerelease_integrations_enabled, delete_unenrolled_agents, preconfigured_fields, ilm_migration_status and secret-storage requirement flags.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> settings = await client.fleet.get_settings()
>>> print(settings.body["item"]["prerelease_integrations_enabled"])
False
async update_settings(*, additional_yaml_config=None, delete_unenrolled_agents=None, has_seen_add_data_notice=None, integration_knowledge_enabled=None, kibana_ca_sha256=None, kibana_urls=None, prerelease_integrations_enabled=None, space_id=None, validate_spaces=None)[source]

Update settings.

Update the global Fleet settings. Only the provided fields are changed; omitted fields keep their current values.

Parameters:

  • additional_yaml_config (str | None) – Deprecated. Additional Fleet Server YAML configuration.

  • delete_unenrolled_agents (dict[str, Any] | None) – Automatic deletion policy for unenrolled agents, an object with the required keys enabled (bool) and is_preconfigured (bool).

  • has_seen_add_data_notice (bool | None) – Deprecated. Whether the “add data” notice has been dismissed.

  • integration_knowledge_enabled (bool | None) – Whether integration knowledge content is enabled.

  • kibana_ca_sha256 (str | None) – Deprecated. SHA-256 of the Kibana CA certificate.

  • kibana_urls (list[str] | None) – Deprecated. Kibana URLs used by agents (maximum 10 URI strings).

  • prerelease_integrations_enabled (bool | None) – Whether pre-release integrations may be installed from the package registry.

  • space_id (str | None) – Optional space ID to update the settings in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the updated global Fleet settings.

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.fleet.update_settings(
...     prerelease_integrations_enabled=True,
... )
>>> print(updated.body["item"]["prerelease_integrations_enabled"])
True
async get_space_settings(*, space_id=None, validate_spaces=None)[source]

Get space settings.

Get the Fleet settings for the current Kibana space. Added in Kibana 9.1.0.

Parameters:

  • space_id (str | None) – Optional space ID to read the space settings from.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • allowed_namespace_prefixes: List of namespace prefixes allowed in this space

  • managed_by: Optional identifier of the manager of these settings

Return type:

ObjectApiResponse containing an item object with

Raises:

Example

>>> settings = await client.fleet.get_space_settings()
>>> print(settings.body["item"]["allowed_namespace_prefixes"])
[]
async update_space_settings(*, allowed_namespace_prefixes=None, space_id=None, validate_spaces=None)[source]

Create or update space settings.

Create or update the Fleet settings for the current Kibana space. Added in Kibana 9.1.0.

Note: as of Kibana 9.4.3 the live server rejects prefixes that contain a - character (Must not contain -), even though the published OpenAPI schema allows arbitrary strings.

Parameters:

  • allowed_namespace_prefixes (list[str] | None) – List of namespace prefixes (maximum 10) that data streams in this space are allowed to use. Pass an empty list to remove all restrictions.

  • space_id (str | None) – Optional space ID to update the space settings in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing an item object with the updated allowed_namespace_prefixes (and optionally managed_by).

Raises:
Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.fleet.update_space_settings(
...     allowed_namespace_prefixes=["teama", "teamb"],
... )
>>> print(updated.body["item"]["allowed_namespace_prefixes"])
['teama', 'teamb']
async health_check(*, id, space_id=None, validate_spaces=None)[source]

Check Fleet Server health.

Check the health status of a Fleet Server instance by its host ID. Returns the server status and name if available.

Parameters:

  • id (str) – The Fleet Server host ID to check (the ID of a Fleet Server host configured in Fleet settings).

  • space_id (str | None) – Optional space ID to run the health check in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • status: Fleet Server status (e.g. "ONLINE" or "OFFLINE")

  • name: The Fleet Server name, if available

  • host_id: The checked host ID, if the host is unreachable

Return type:

ObjectApiResponse containing the health check result

Raises:

Example

>>> health = await client.fleet.health_check(
...     id="fleet-server-host-id-1"
... )
>>> print(health.body["status"])
ONLINE
async check_permissions(*, fleet_server_setup=None, space_id=None, validate_spaces=None)[source]

Check permissions.

Check whether the current user has the required permissions to use Fleet. Optionally verifies Fleet Server setup privileges.

Parameters:

  • fleet_server_setup (bool | None) – When True, check Fleet Server setup privileges in addition to standard Fleet privileges.

  • space_id (str | None) – Optional space ID to check the permissions in.

  • validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

  • success: True if the user has all required permissions

  • error: Present when success is False; one of "MISSING_SECURITY", "MISSING_PRIVILEGES" or "MISSING_FLEET_SERVER_SETUP_PRIVILEGES"

Return type:

ObjectApiResponse containing the permission check result

Raises:

Example

>>> perms = await client.fleet.check_permissions()
>>> print(perms.body["success"])
True
async perform_request(method, path, *, params=None, headers=None, body=None)

Perform an async HTTP request via the parent client with space context enhancement.

Parameters:

  • method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)

  • path (str) – API endpoint path

  • params (dict[str, Any] | None) – Query parameters

  • headers (dict[str, str] | None) – Request headers

  • body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]