[docs] Document internal API restriction in 9.0 #191943
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
TinaHeiligers
added
Team:Core
|
A documentation preview will be available soon. Request a new doc build by commenting
If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here. |
|
Pinging @elastic/kibana-core (Team:Core) |
|
@elasticmachine merge upstream |
TinaHeiligers
commented
Sep 3, 2024
TinaHeiligers
commented
Sep 3, 2024
docs/user/api.asciidoc
Outdated
| @@ -5,6 +5,8 @@ Some {kib} features are provided via a REST API, which is ideal for creating an | |||
| integration with {kib}, or automating certain aspects of configuring and | |||
| deploying {kib}. | |||
|
|
|||
| NOTE: Access to internal {kib} API endpoints will be restricted in 9.0. For more information, refer to https://github.com/elastic/kibana/issues/163654. | |||
There was a problem hiding this comment.
I went with a note rather than a warning because, strictly speaking, end users should only be consuming public APIs.
There was a problem hiding this comment.
NOTE makes sense to me 👍
Is it useful to link to the github issue? I'm not sure that it would help a user to read through that issue. We could ask the docs team for input, but maybe it's sufficient to just say something like:
NOTE: Access to internal {kib} API endpoints will be restricted in 9.0. Please move any integrations to publicly documented APIs.
There was a problem hiding this comment.
I agree that providing advice here rather than sending them to another page is better.
There was a problem hiding this comment.
++ we're not intending to document the restrictInternalAPIs setting and it makes sense to give advice instead of the issue.
There was a problem hiding this comment.
Done in db31e15
💚 Build Succeeded
Metrics [docs]
History
To update your PR or re-run it, just comment with: |
4 tasks
TinaHeiligers
added a commit
that referenced
this pull request
Oct 2, 2024
fix #163654 This PR enforces internal API restrictions in our standard offering. Internal APIs are subject to rapid change and are intentionally not public. By restricting their access, we protect consumers from these rapid changes. This PR does not change any public APIs and they remain available for external consumption. ## Note to reviewers: I chose the most practical way of resolving the failures (add the header or disable the restriction). ## Details Requests to internal Kibana APIs will be restricted globally. This allows more flexibility in making breaking changes to internal APIs, without a risk to external consumers. ## Why are we doing this? The restriction is there to help mitigate the risk of breaking external integrations consuming APIs. Internal APIs are subject to frequent changes, necessary for feature development. ## What this means to plugin authors : Kibana core applies the restriction when enabled through HTTP config. ## What this means to Kibana consumers: Explicitly restricting access to internal APIs has advantages for external consumers: - Consumers can safely integrate with Kibana's stable, public APIs - Consumers are protected from Internal route development, which may involve breaking changes - Relevant information in Kibana's external documentation that is user-friendly and complete. KB article explaining the change (tracked as part of elastic/kibana-team#1044) ## Release note Starting with this release, requests to internal Kibana APIs are globally restricted by default. This change is designed to provide more flexibility in making breaking changes to internal APIs while protecting external consumers from unexpected disruptions. **Key Changes**: • _Internal API Access_: External consumers no longer have access to Kibana’s internal APIs, which are now strictly reserved for internal development and subject to frequent changes. This helps ensure that external integrations only interact with stable, public APIs. • _Error Handling_: When a request is made to an internal API without the proper internal identifier (header or query parameter), Kibana will respond with a 400 Bad Request error, indicating that the route exists but is not allowed under the current Kibana configuration. ## How to test this ### Running kibana 1. Set `server.restrictInternalApis: true` in `kibana.yml` 2. Start es with any license 3. Start kibana 4. Make an external request to an internal API: <details> <summary>curl request to get the config for 9.0:</summary> ```unset curl --location 'localhost:5601/abc/api/kibana/management/saved_objects/_bulk_get' \ --header 'Content-Type: application/json' \ --header 'kbn-xsrf: kibana' \ --header 'x-elastic-internal-origin: kibana' \ --header 'Authorization: Basic ZWxhc3RpYzpjaGFuZ2VtZQ==' \ --data '[ { "type": "config", "id": "9.0.0" } ]' ``` </details> The request should be successful. 5. Make the same curl request without the internal origin header <details> <summary>curl:</summary> ```unset curl --location 'localhost:5601/abc/api/kibana/management/saved_objects/_bulk_get' \ --header 'Content-Type: application/json' \ --header 'kbn-xsrf: kibana' \ --header 'Authorization: Basic ZWxhc3RpYzpjaGFuZ2VtZQ==' \ --data '[ { "type": "config", "id": "9.0.0" } ]' ``` </details> The response should be an error similar to: `{"statusCode":400,"error":"Bad Request","message":"uri [/api/kibana/management/saved_objects/_bulk_get] with method [post] exists but is not available with the current configuration"}` 6. Remove `server.restrictInternalApis` from `kibana.yml` or set it to `false`. 7. Repeat both curl requests above. Both should respond without an error. ### Checklist Delete any items that are not applicable to this PR. - [X] [Documentation] was added for features that require explanation or tutorials (In PR #191943) - [x] [Unit or functional tests](https://www.elastic.co/guide/en/kibana/master/development-tests.html) were updated or added to match the most common scenarios (and PR #192407) - [x] If a plugin configuration key changed, check if it needs to be allowlisted in the cloud and added to the [docker list](https://github.com/elastic/kibana/blob/main/src/dev/build/tasks/os_packages/docker_generator/resources/base/bin/kibana-docker) (docker list updated in #156935, cloud stack packs for 9.0 kibana to follow) ### Risk Matrix | Risk | Probability | Severity | Mitigation/Notes | |---------------------------|-------------|----------|-------------------------| | The restriction is knowingly bypassed by end-users adding the required header to use `internal` APIs | Low | High | Kibana's internal APIs are not documented in the OAS specifications. External consumption will be prevented unless explicitly bypassed. | | Upstream services don't include the header and requests to `internal` APIs fail | Medium | Medium | The Core team needs to ensure intra-stack components are updated too | ### For maintainers - [x] This was checked for breaking API changes and was [labeled appropriately](https://www.elastic.co/guide/en/kibana/master/contributing.html#kibana-release-notes-process) --------- Co-authored-by: Elastic Machine <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
fix: #191941
Adds note that access to internal APIs will be restricted as of 9.0: