[Fleet] Improvement on agents endpoints

criamico commented 10 months ago

Summary

There are some aspects of our APIs that would benefit from an assessment.

We have some agent endpoints that have similar structure and accept similar options:

POST agents/bulk_upgrade
POST agents/bulk_unenroll
POST agents/bulk_unassign
POST /agents/bulk_update_agent_tags

Enhancement 1

These endpoints accept the following schema: agents: schema.oneOf([schema.arrayOf(schema.string()), schema.string()]), as they can accept both a list of agent ids or a KQL query.

The request body should be changed to accept agent_ids or kuery, the same way we have in other endpoints and that would make much more clear for the users that they can pass a query

Another endpoint that would need this change are:

agents/{agentId}/request_diagnostics

Enhancement 2

The documentation for these endpoints is not very clear and doesn't include any example of queries, only agent ids batches

Enhancement 3 - Harmonization

These endpoints accept similar options. Some of them are the same:

    force: schema.maybe(schema.boolean()),
    batchSize: schema.maybe(schema.number()),

We should try to "harmonize" them to have a predictable behaviour. For instance we pass "force" to bulk_upgrade, but it's only used to check the versions.

Mentioning this other ticket here as it's related: https://github.com/elastic/kibana/issues/170423

elasticmachine commented 10 months ago

Pinging @elastic/fleet (Team:Fleet)

lucabelluccini commented 10 months ago

🙇 If possible let's also mention if KQL query must be escaped and what are the fields which can be used to filter the agents.

elastic / kibana