Support Kibana deprecation logging in Upgrade Assistant #117241
Assignees
Labels
deprecation_warnings
enhancement
New value added to drive a business result
Feature:Upgrade Assistant
Team:Core
Core services & architecture: plugins, logging, config, saved objects, http, ES client, i18n, etc
Comments
cjcenizal
added
enhancement
|
Pinging @elastic/kibana-stack-management (Team:Stack Management) |
lukeelmers
added
deprecation_warnings
Team:Core
alisonelizabeth
added
Feature:Upgrade Assistant
and removed
Feature:Upgrade Assistant
labels
rudolf
removed
the
Team:Kibana Management
This was referenced Oct 2, 2024
Closed
4 tasks
7 tasks
Bamieh
added a commit
that referenced
this issue
Nov 12, 2024
…nt (#199026) ## Summary > In #117241 we're surfacing usage of APIs marked as `deprecated: true` in the Upgrade Assistant to help users prepare for a major upgrade. While internal APIs aren't really deprecated in the same sense we are making a breaking change by blocking external integrations with these APIs. Since this could be equally disruptive to users depending on these APIs it would help our users to surface such usage in the UA too. The `api` deprecations now have two sub types: 1. routes deprecations `options.deprecated: { … }` 2. access deprecations `options.access: 'internal'` This PR adds the second `api` deprecation subtype. The reason i kept one `api` deprecation type and i didnt create a new type is that they have exactly the same registration process but are triggered by different attributes. The `api` deprecation is fully managed by the core team internal services and are configured by the user through the route interface so it makes sense to keep them as one type. I also can see us adding more subtypes to this and just piggybacking on the current flow instead of duplicating it everytime. **Checklist** - [x] Create deprecation subtype - [x] Example plugin - [x] Surface the deprecation in UA - [x] Api access deprecation copy (@florent-leborgne ) - [x] Update README and code annotations - [x] Unit tests - [x] Integration tests Closes #194675 ### Design decisions: If the API has both route deprecation (`options.deprecated: { … }` ) AND is an internal api `options.access: 'internal'` The current behavior i went for in my PR: I show this API once in the UA under the internal access deprecation. While showing the route deprecation details if defined. This seems to make the most sense since users should stop using this API altogether. ### Copy decisions: @florent-leborgne wrote the copy for this deprecation subtype. <img width="1319" alt="image" src="https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130"> <img width="713" alt="image" src="https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678"> ## Testing Run kibana locally with the test example plugin that has deprecated routes ``` yarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples ``` The following comprehensive deprecated routes examples are registered inside the folder: `examples/routing_example/server/routes/deprecated_routes` Run them in the dev console to trigger the deprecation condition so they show up in the UA: ``` GET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false ``` --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Bamieh
added a commit
that referenced
this issue
Nov 12, 2024
…ssistant (#199026) (#199764) # Backport This will backport the following commits from `main` to `8.x`: - [[UA][Core] Surface integrations with internal APIs in upgrade assistant (#199026)](#199026) <!--- Backport version: 8.9.8 --> ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) <!--BACKPORT [{"author":{"name":"Ahmad Bamieh","email":"ahmad.bamyeh@elastic.co"},"sourceCommit":{"committedDate":"2024-11-12T11:19:22Z","message":"[UA][Core] Surface integrations with internal APIs in upgrade assistant (#199026)\n\n## Summary\r\n\r\n> In #117241 we're surfacing\r\nusage of APIs marked as `deprecated: true` in the Upgrade Assistant to\r\nhelp users prepare for a major upgrade. While internal APIs aren't\r\nreally deprecated in the same sense we are making a breaking change by\r\nblocking external integrations with these APIs. Since this could be\r\nequally disruptive to users depending on these APIs it would help our\r\nusers to surface such usage in the UA too.\r\n\r\nThe `api` deprecations now have two sub types:\r\n1. routes deprecations `options.deprecated: { … }`\r\n2. access deprecations `options.access: 'internal'`\r\n\r\nThis PR adds the second `api` deprecation subtype. The reason i kept one\r\n`api` deprecation type and i didnt create a new type is that they have\r\nexactly the same registration process but are triggered by different\r\nattributes. The `api` deprecation is fully managed by the core team\r\ninternal services and are configured by the user through the route\r\ninterface so it makes sense to keep them as one type. I also can see us\r\nadding more subtypes to this and just piggybacking on the current flow\r\ninstead of duplicating it everytime.\r\n\r\n\r\n**Checklist**\r\n- [x] Create deprecation subtype\r\n- [x] Example plugin\r\n- [x] Surface the deprecation in UA\r\n- [x] Api access deprecation copy (@florent-leborgne )\r\n- [x] Update README and code annotations\r\n- [x] Unit tests\r\n- [x] Integration tests\r\n\r\n\r\nCloses https://github.com/elastic/kibana/issues/194675\r\n\r\n### Design decisions:\r\nIf the API has both route deprecation (`options.deprecated: { … }` ) AND\r\nis an internal api `options.access: 'internal'`\r\n\r\nThe current behavior i went for in my PR:\r\nI show this API once in the UA under the internal access deprecation.\r\nWhile showing the route deprecation details if defined. This seems to\r\nmake the most sense since users should stop using this API altogether.\r\n\r\n### Copy decisions:\r\n@florent-leborgne wrote the copy for this deprecation subtype.\r\n<img width=\"1319\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130\">\r\n\r\n<img width=\"713\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678\">\r\n\r\n\r\n## Testing\r\n\r\nRun kibana locally with the test example plugin that has deprecated\r\nroutes\r\n```\r\nyarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples\r\n```\r\n\r\nThe following comprehensive deprecated routes examples are registered\r\ninside the folder:\r\n`examples/routing_example/server/routes/deprecated_routes`\r\n\r\nRun them in the dev console to trigger the deprecation condition so they\r\nshow up in the UA:\r\n\r\n```\r\nGET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false\r\n```\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"a10eb1fe4e55aa0cfbbb4b12a8d740a867463283","branchLabelMapping":{"^v9.0.0$":"main","^v8.17.0$":"8.x","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","backport:prev-minor","v8.17.0"],"number":199026,"url":"https://github.com/elastic/kibana/pull/199026","mergeCommit":{"message":"[UA][Core] Surface integrations with internal APIs in upgrade assistant (#199026)\n\n## Summary\r\n\r\n> In #117241 we're surfacing\r\nusage of APIs marked as `deprecated: true` in the Upgrade Assistant to\r\nhelp users prepare for a major upgrade. While internal APIs aren't\r\nreally deprecated in the same sense we are making a breaking change by\r\nblocking external integrations with these APIs. Since this could be\r\nequally disruptive to users depending on these APIs it would help our\r\nusers to surface such usage in the UA too.\r\n\r\nThe `api` deprecations now have two sub types:\r\n1. routes deprecations `options.deprecated: { … }`\r\n2. access deprecations `options.access: 'internal'`\r\n\r\nThis PR adds the second `api` deprecation subtype. The reason i kept one\r\n`api` deprecation type and i didnt create a new type is that they have\r\nexactly the same registration process but are triggered by different\r\nattributes. The `api` deprecation is fully managed by the core team\r\ninternal services and are configured by the user through the route\r\ninterface so it makes sense to keep them as one type. I also can see us\r\nadding more subtypes to this and just piggybacking on the current flow\r\ninstead of duplicating it everytime.\r\n\r\n\r\n**Checklist**\r\n- [x] Create deprecation subtype\r\n- [x] Example plugin\r\n- [x] Surface the deprecation in UA\r\n- [x] Api access deprecation copy (@florent-leborgne )\r\n- [x] Update README and code annotations\r\n- [x] Unit tests\r\n- [x] Integration tests\r\n\r\n\r\nCloses https://github.com/elastic/kibana/issues/194675\r\n\r\n### Design decisions:\r\nIf the API has both route deprecation (`options.deprecated: { … }` ) AND\r\nis an internal api `options.access: 'internal'`\r\n\r\nThe current behavior i went for in my PR:\r\nI show this API once in the UA under the internal access deprecation.\r\nWhile showing the route deprecation details if defined. This seems to\r\nmake the most sense since users should stop using this API altogether.\r\n\r\n### Copy decisions:\r\n@florent-leborgne wrote the copy for this deprecation subtype.\r\n<img width=\"1319\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130\">\r\n\r\n<img width=\"713\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678\">\r\n\r\n\r\n## Testing\r\n\r\nRun kibana locally with the test example plugin that has deprecated\r\nroutes\r\n```\r\nyarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples\r\n```\r\n\r\nThe following comprehensive deprecated routes examples are registered\r\ninside the folder:\r\n`examples/routing_example/server/routes/deprecated_routes`\r\n\r\nRun them in the dev console to trigger the deprecation condition so they\r\nshow up in the UA:\r\n\r\n```\r\nGET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false\r\n```\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"a10eb1fe4e55aa0cfbbb4b12a8d740a867463283"}},"sourceBranch":"main","suggestedTargetBranches":["8.x"],"targetPullRequestStates":[{"branch":"main","label":"v9.0.0","labelRegex":"^v9.0.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/199026","number":199026,"mergeCommit":{"message":"[UA][Core] Surface integrations with internal APIs in upgrade assistant (#199026)\n\n## Summary\r\n\r\n> In #117241 we're surfacing\r\nusage of APIs marked as `deprecated: true` in the Upgrade Assistant to\r\nhelp users prepare for a major upgrade. While internal APIs aren't\r\nreally deprecated in the same sense we are making a breaking change by\r\nblocking external integrations with these APIs. Since this could be\r\nequally disruptive to users depending on these APIs it would help our\r\nusers to surface such usage in the UA too.\r\n\r\nThe `api` deprecations now have two sub types:\r\n1. routes deprecations `options.deprecated: { … }`\r\n2. access deprecations `options.access: 'internal'`\r\n\r\nThis PR adds the second `api` deprecation subtype. The reason i kept one\r\n`api` deprecation type and i didnt create a new type is that they have\r\nexactly the same registration process but are triggered by different\r\nattributes. The `api` deprecation is fully managed by the core team\r\ninternal services and are configured by the user through the route\r\ninterface so it makes sense to keep them as one type. I also can see us\r\nadding more subtypes to this and just piggybacking on the current flow\r\ninstead of duplicating it everytime.\r\n\r\n\r\n**Checklist**\r\n- [x] Create deprecation subtype\r\n- [x] Example plugin\r\n- [x] Surface the deprecation in UA\r\n- [x] Api access deprecation copy (@florent-leborgne )\r\n- [x] Update README and code annotations\r\n- [x] Unit tests\r\n- [x] Integration tests\r\n\r\n\r\nCloses https://github.com/elastic/kibana/issues/194675\r\n\r\n### Design decisions:\r\nIf the API has both route deprecation (`options.deprecated: { … }` ) AND\r\nis an internal api `options.access: 'internal'`\r\n\r\nThe current behavior i went for in my PR:\r\nI show this API once in the UA under the internal access deprecation.\r\nWhile showing the route deprecation details if defined. This seems to\r\nmake the most sense since users should stop using this API altogether.\r\n\r\n### Copy decisions:\r\n@florent-leborgne wrote the copy for this deprecation subtype.\r\n<img width=\"1319\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130\">\r\n\r\n<img width=\"713\" alt=\"image\"\r\nsrc=\"https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678\">\r\n\r\n\r\n## Testing\r\n\r\nRun kibana locally with the test example plugin that has deprecated\r\nroutes\r\n```\r\nyarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples\r\n```\r\n\r\nThe following comprehensive deprecated routes examples are registered\r\ninside the folder:\r\n`examples/routing_example/server/routes/deprecated_routes`\r\n\r\nRun them in the dev console to trigger the deprecation condition so they\r\nshow up in the UA:\r\n\r\n```\r\nGET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false\r\nGET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false\r\n```\r\n\r\n---------\r\n\r\nCo-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>","sha":"a10eb1fe4e55aa0cfbbb4b12a8d740a867463283"}},{"branch":"8.x","label":"v8.17.0","labelRegex":"^v8.17.0$","isSourceBranch":false,"state":"NOT_CREATED"}]}] BACKPORT--> Co-authored-by: Elastic Machine <elasticmachine@users.noreply.github.com>
tkajtoch
pushed a commit
to tkajtoch/kibana
that referenced
this issue
Nov 12, 2024
…nt (elastic#199026) ## Summary > In elastic#117241 we're surfacing usage of APIs marked as `deprecated: true` in the Upgrade Assistant to help users prepare for a major upgrade. While internal APIs aren't really deprecated in the same sense we are making a breaking change by blocking external integrations with these APIs. Since this could be equally disruptive to users depending on these APIs it would help our users to surface such usage in the UA too. The `api` deprecations now have two sub types: 1. routes deprecations `options.deprecated: { … }` 2. access deprecations `options.access: 'internal'` This PR adds the second `api` deprecation subtype. The reason i kept one `api` deprecation type and i didnt create a new type is that they have exactly the same registration process but are triggered by different attributes. The `api` deprecation is fully managed by the core team internal services and are configured by the user through the route interface so it makes sense to keep them as one type. I also can see us adding more subtypes to this and just piggybacking on the current flow instead of duplicating it everytime. **Checklist** - [x] Create deprecation subtype - [x] Example plugin - [x] Surface the deprecation in UA - [x] Api access deprecation copy (@florent-leborgne ) - [x] Update README and code annotations - [x] Unit tests - [x] Integration tests Closes elastic#194675 ### Design decisions: If the API has both route deprecation (`options.deprecated: { … }` ) AND is an internal api `options.access: 'internal'` The current behavior i went for in my PR: I show this API once in the UA under the internal access deprecation. While showing the route deprecation details if defined. This seems to make the most sense since users should stop using this API altogether. ### Copy decisions: @florent-leborgne wrote the copy for this deprecation subtype. <img width="1319" alt="image" src="https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130"> <img width="713" alt="image" src="https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678"> ## Testing Run kibana locally with the test example plugin that has deprecated routes ``` yarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples ``` The following comprehensive deprecated routes examples are registered inside the folder: `examples/routing_example/server/routes/deprecated_routes` Run them in the dev console to trigger the deprecation condition so they show up in the UA: ``` GET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false ``` --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
CAWilson94
pushed a commit
to CAWilson94/kibana
that referenced
this issue
Nov 18, 2024
…nt (elastic#199026) ## Summary > In elastic#117241 we're surfacing usage of APIs marked as `deprecated: true` in the Upgrade Assistant to help users prepare for a major upgrade. While internal APIs aren't really deprecated in the same sense we are making a breaking change by blocking external integrations with these APIs. Since this could be equally disruptive to users depending on these APIs it would help our users to surface such usage in the UA too. The `api` deprecations now have two sub types: 1. routes deprecations `options.deprecated: { … }` 2. access deprecations `options.access: 'internal'` This PR adds the second `api` deprecation subtype. The reason i kept one `api` deprecation type and i didnt create a new type is that they have exactly the same registration process but are triggered by different attributes. The `api` deprecation is fully managed by the core team internal services and are configured by the user through the route interface so it makes sense to keep them as one type. I also can see us adding more subtypes to this and just piggybacking on the current flow instead of duplicating it everytime. **Checklist** - [x] Create deprecation subtype - [x] Example plugin - [x] Surface the deprecation in UA - [x] Api access deprecation copy (@florent-leborgne ) - [x] Update README and code annotations - [x] Unit tests - [x] Integration tests Closes elastic#194675 ### Design decisions: If the API has both route deprecation (`options.deprecated: { … }` ) AND is an internal api `options.access: 'internal'` The current behavior i went for in my PR: I show this API once in the UA under the internal access deprecation. While showing the route deprecation details if defined. This seems to make the most sense since users should stop using this API altogether. ### Copy decisions: @florent-leborgne wrote the copy for this deprecation subtype. <img width="1319" alt="image" src="https://github.com/user-attachments/assets/9a32f6d1-686a-4405-aec6-786ac5e10130"> <img width="713" alt="image" src="https://github.com/user-attachments/assets/1304c98d-4c64-468e-a7d6-19c1193bf678"> ## Testing Run kibana locally with the test example plugin that has deprecated routes ``` yarn start --plugin-path=examples/routing_example --plugin-path=examples/developer_examples ``` The following comprehensive deprecated routes examples are registered inside the folder: `examples/routing_example/server/routes/deprecated_routes` Run them in the dev console to trigger the deprecation condition so they show up in the UA: ``` GET kbn:/api/routing_example/d/internal_deprecated_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_only_route?elasticInternalOrigin=false GET kbn:/internal/routing_example/d/internal_versioned_route?apiVersion=1&elasticInternalOrigin=false ``` --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
In #105692, the idea of surfacing Kibana deprecation logs came up, but UA currently lacks support for this type of functionality.
Blocked by:
In terms of UI/UX, we could mirror the way UA currently surfaced ES deprecation logs. If we could store them in the same index and use the same format, that would minimize the amount of work we need to do in UA and simplify the user experience.
CC @elastic/kibana-core
The text was updated successfully, but these errors were encountered: