FleetPoliciesClient¶

Client for the Kibana Fleet agent and package policies API.

Agent policies define how Elastic Agents behave: which outputs they ship data to, their monitoring settings and which integrations they run. Package policies attach an integration package (with its inputs and variables) to one or more agent policies. Agentless policies deploy an integration without a self-managed Elastic Agent (Elastic Cloud / serverless only).

Fleet policies are space-aware resources: every method accepts an optional space_id to target a specific space.

class kibana._sync.client.fleet_policies.FleetPoliciesClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Fleet agent and package policies API.

Fleet policies are space-aware resources: every method accepts an optional space_id to target a specific 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="...")
>>>
>>> # Create an agent policy and attach a package policy to it
>>> policy = client.fleet_policies.create_agent_policy(
...     name="my-agent-policy",
...     namespace="default",
...     sys_monitoring=False,
... )
>>> policy_id = policy.body["item"]["id"]
>>>
>>> pkg = client.fleet_policies.create_package_policy(
...     name="my-package-policy",
...     package={"name": "log", "version": "2.4.4"},
...     policy_ids=[policy_id],
...     inputs={"logs-logfile": {"enabled": True}},
... )
>>>
>>> # Clean up
>>> client.fleet_policies.delete_package_policy(
...     package_policy_id=pkg.body["item"]["id"]
... )
>>> client.fleet_policies.delete_agent_policy(agent_policy_id=policy_id)

Managing Agent Policies

from kibana import Kibana

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

# Create an agent policy (without the system monitoring package)
created = client.fleet_policies.create_agent_policy(
    name="my-agent-policy",
    namespace="default",
    description="Policy for web servers",
    monitoring_enabled=["logs", "metrics"],
    sys_monitoring=False,
)
agent_policy_id = created.body["item"]["id"]

# Get, update and list agent policies
policy = client.fleet_policies.get_agent_policy(
    agent_policy_id=agent_policy_id
)
client.fleet_policies.update_agent_policy(
    agent_policy_id=agent_policy_id,
    name="my-agent-policy",
    namespace="default",
    description="Updated description",
)
policies = client.fleet_policies.get_agent_policies(
    kuery='ingest-agent-policies.name:"my-agent-policy"'
)

# Copy, then delete the copy
copy = client.fleet_policies.copy_agent_policy(
    agent_policy_id=agent_policy_id, name="my-agent-policy (copy)"
)
client.fleet_policies.delete_agent_policy(
    agent_policy_id=copy.body["item"]["id"]
)

Inspecting Compiled Policies

# Full compiled policy document (what an enrolled agent receives)
full = client.fleet_policies.get_full_agent_policy(
    agent_policy_id=agent_policy_id
)

# The same document as downloadable elastic-agent.yml (YAML string)
yaml_doc = client.fleet_policies.download_agent_policy(
    agent_policy_id=agent_policy_id
)
print(yaml_doc.body)

# Outputs used by one or many policies
outputs = client.fleet_policies.get_agent_policy_outputs(
    agent_policy_id=agent_policy_id
)
bulk_outputs = client.fleet_policies.get_agent_policies_outputs(
    ids=[agent_policy_id]
)

Managing Package Policies

# Attach the "udp" integration using the simplified inputs format
pkg = client.fleet_policies.create_package_policy(
    name="my-udp-policy",
    package={"name": "udp", "version": "2.5.1"},
    policy_ids=[agent_policy_id],
    inputs={
        "udp-udp": {
            "enabled": True,
            "streams": {
                "udp.udp": {
                    "enabled": True,
                    "vars": {
                        "listen_address": "localhost",
                        "listen_port": 8964,
                        "data_stream.dataset": "udp.custom",
                    },
                }
            },
        }
    },
)
package_policy_id = pkg.body["item"]["id"]

# Upgrade dry run, then upgrade to the latest installed version
dry_run = client.fleet_policies.upgrade_package_policies_dry_run(
    package_policy_ids=[package_policy_id]
)
client.fleet_policies.upgrade_package_policies(
    package_policy_ids=[package_policy_id]
)

# Delete package policies (single or bulk)
client.fleet_policies.delete_package_policy(
    package_policy_id=package_policy_id, force=True
)

Agentless Policies

Agentless policies are only supported in Elastic Cloud and serverless environments; self-managed deployments reject these calls with a 400 error.

created = client.fleet_policies.create_agentless_policy(
    name="my-agentless-policy",
    package={"name": "cspm", "version": "1.0.0"},
)
client.fleet_policies.delete_agentless_policy(
    policy_id=created.body["item"]["id"]
)

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the FleetPoliciesClient.

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_policies_client = FleetPoliciesClient(kibana_client)

get_agent_policies(*, page=None, per_page=None, sort_field=None, sort_order=None, show_upgradeable=None, kuery=None, no_agent_count=None, with_agent_count=None, full=None, format=None, space_id=None, validate_spaces=None)[source]¶

Get agent policies.

GET /api/fleet/agent_policies

Lists agent policies, optionally filtered with a KQL query and paginated.

Parameters:

page (int | None) – Page number to return (1-based).
per_page (int | None) – Number of policies per page.
sort_field (str | None) – Field to sort the results by.
sort_order (str | None) – Sort direction, either "asc" or "desc".
show_upgradeable (bool | None) – Only return policies with agents that can be upgraded.
kuery (str | None) – KQL filter, e.g. 'ingest-agent-policies.name:"my-policy"'.
no_agent_count (bool | None) – Do not compute the agent count per policy (deprecated in favor of with_agent_count).
with_agent_count (bool | None) – Include the number of enrolled agents for each policy.
full (bool | None) – Return the full policy representation (including package policies).
format (str | None) – Representation of package policies within each agent policy: "simplified" or "legacy".
space_id (str | None) – Optional space ID to scope the operation to.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with items (list of agent policies), total, page and perPage.

Raises:

BadRequestError – If a query parameter is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

FleetPoliciesClient¶

AsyncFleetPoliciesClient¶