[Fleet] Prepare Fleet API for promotion to GA #123150
Comments
joshdover
added
enhancement
|
#121485 has a few downstream dependencies, does Fleet API GA have to depend on it? |
@juliaElastic I don't believe we identified any needs for breaking changes on the HTTP API to support our RBAC evolution goals. Can you confirm and if so, check this one off the list? |
Yes, we don't plan any breaking changes for RBAC. I'll close that one out. |
joshdover
changed the title
|
@juliaElastic @kpollich Would it make sense to also include these?: |
|
@kpollich We've had a couple of recent issues related to the data stream API, we've discussed putting some time here to make it more fault-tolerant. Could improvements here be a candidate? Related issues: |
I think the Optimize issue does not change the API itself, so it can be done independently of moving to GA. |
|
@kpollich I added a few more enhancements to this issue: |
|
We may want to consider this one as well as a fix required for GA: #137005 |
|
@joshdover Thanks - added to the description. |
|
It'd be great to integrate Fleet's OpenAPI docs with a first party Elastic docs site, preferably https://docs.elastic.co/. OpenAPI support isn't quite ready yet, but is planned and tracked here https://github.com/elastic/docs.elastic.co/issues/37. We should be doing everything we can do clean up and improve our existing OpenAPI files to make sure they're ready for integration with a first-party docs site when possible. |
|
@nimarezainia can we make sure that the docs are good to be shipped before 8.5 official release? |
|
Update: Some more docs details will be added to: elastic/observability-docs#2180 then our writers will take it from there and create some getting started materials. As the steps needed to get it to a Beta stage are now all done, i'll move this issue to a later iteration. |
|
We need to make sure once we formally enter a beta period that any public-facing docs for the Fleet API or its OpenAPI spec to say |
|
marking it beta is the easy part. What do we want to collect from customers? a sample workflow or test guide would be great. |
|
Relevant docs/OpenAPI issue: #137240 |
|
We need to address some issues with Fleet's OpenAPI spec to unblock the docs team: #149990 |
|
@kpollich converting this to a meta issue as we already added the follow up ones in our sprint. |
|
@kpollich Per discussion, going to close this issue for planning purposes. Feel free to reference any follow up docs issues needed. |
## Summary Small pr to remove Experimental from the Fleet openapi README. Related to #123150
One design goal of Fleet is to be 100% API-based in our business logic. This allows for easy external integration and management of the Fleet platform and paves the way for future 1st class features, such as Infrastructure-as-Code (IaC) tooling support (Terraform, etc.).
Today, Fleet publishes an OpenAPI spec which is currently marked as experimental.
There will be a beta period prior to the Fleet API's general availability. This beta period is intended to provide internal and external consumers of the Fleet API some time to begin adopting new features, and to provide feedback and input on the transition to General Availability.
1️⃣ Required for beta
Beta requirements are now fulfilled.
These issues must be completed before the Fleet API can enter a formal beta period.
"Recipe" documentation
We need some level of "how to use this API" documentation around the Fleet API that captures common operations and processes. These docs should include all of the following operations:
Package Policy API improvements and breaking changes
The package policy API is difficult to use programmatically. It requires too much knowledge of the structure of specific integrations and their inputs. It should improved top-to-bottom to better support automation use cases at scale. Several of the changes below will be considered breaking, so we need to handle these before we can consider the Fleet API ready for a beta period.
Audit OpenAPI spec and remove unused endpoints
Any endpoint that is completely unused or doesn't have a use-case should be removed prior to beta to limit the API's surface area.
Update bulk actions API
In supporting #141567, we'll likely be making breaking changes to the bulk actions API response structure. We should make sure these changes land and documentation is accurate before we consider the Fleet API beta. cc @juliaElastic.
2️⃣ Required for GA
The GA requirements are now fulfilled
These issues don't block the initial beta, but they should be completed prior to the Fleet API transition into General Availability.
First-party reference documentation
Currently, Fleet maintains its own set of OpenAPI documentation in GitHub here. This documentation is not hosted or bundled with any Elastic-owned documentation. Typically, we use a link to a Swagger UI provider to allow for exploring the API spec. This is not scalable, and we need to provide first-party documentation for the Fleet API in order to promote it to GA.
It'd be great to get API docs on https://docs.elastic.co, which supports MDX docs. It's not clear, though, how we'd integrate our OpenAPI spec files into this docs system currently. https://github.com/elastic/docs.elastic.co/issues/37 tracks the implementation for a React component that consumes OpenAPI specs and produces a UI within the docs.elastic.co site.
[No longer required] API versioning + breaking change management
Another concern with the Fleet API moving forward is limiting breaking changes. There are two distinct efforts related to this:
Other API fixes
Any breaking changes needed for RBAC evolution(none anticipated)Optional
These are "nice to have" improvements that aren't necessarily required for promoting the Fleet API to beta or GA.
The text was updated successfully, but these errors were encountered: