forked from elastic/kibana
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[UA][Core] Surface integrations with internal APIs in upgrade assista…
…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 <[email protected]>
- Loading branch information
Showing
41 changed files
with
916 additions
and
307 deletions.
There are no files selected for viewing
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
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
54 changes: 54 additions & 0 deletions
54
examples/routing_example/server/routes/deprecated_routes/internal.ts
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,54 @@ | ||
/* | ||
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one | ||
* or more contributor license agreements. Licensed under the "Elastic License | ||
* 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side | ||
* Public License v 1"; you may not use this file except in compliance with, at | ||
* your election, the "Elastic License 2.0", the "GNU Affero General Public | ||
* License v3.0 only", or the "Server Side Public License, v 1". | ||
*/ | ||
|
||
import type { IRouter } from '@kbn/core/server'; | ||
import { DEPRECATED_ROUTES } from '../../../common'; | ||
|
||
export const registerInternalDeprecatedRoute = (router: IRouter) => { | ||
router.get( | ||
{ | ||
path: DEPRECATED_ROUTES.INTERNAL_DEPRECATED_ROUTE, | ||
validate: false, | ||
options: { | ||
// Explicitly set access is to internal | ||
access: 'internal', | ||
deprecated: { | ||
documentationUrl: 'https://elastic.co/', | ||
severity: 'critical', | ||
message: 'Additonal message for internal deprecated api', | ||
reason: { type: 'deprecate' }, | ||
}, | ||
}, | ||
}, | ||
async (ctx, req, res) => { | ||
return res.ok({ | ||
body: { | ||
result: | ||
'Called deprecated route with `access: internal`. Check UA to see the deprecation.', | ||
}, | ||
}); | ||
} | ||
); | ||
|
||
router.get( | ||
{ | ||
path: DEPRECATED_ROUTES.INTERNAL_ONLY_ROUTE, | ||
validate: false, | ||
// If no access is specified then it defaults to internal | ||
}, | ||
async (ctx, req, res) => { | ||
return res.ok({ | ||
body: { | ||
result: | ||
'Called route with `access: internal` Although this API is not marked as deprecated it will show in UA. Check UA to see the deprecation.', | ||
}, | ||
}); | ||
} | ||
); | ||
}; |
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
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
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
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
96 changes: 0 additions & 96 deletions
96
.../core/deprecations/core-deprecations-server-internal/src/deprecations/api_deprecations.ts
This file was deleted.
Oops, something went wrong.
62 changes: 62 additions & 0 deletions
62
...recations-server-internal/src/deprecations/api_deprecations/access/access_deprecations.ts
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
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,62 @@ | ||
/* | ||
* Copyright Elasticsearch B.V. and/or licensed to Elasticsearch B.V. under one | ||
* or more contributor license agreements. Licensed under the "Elastic License | ||
* 2.0", the "GNU Affero General Public License v3.0 only", and the "Server Side | ||
* Public License v 1"; you may not use this file except in compliance with, at | ||
* your election, the "Elastic License 2.0", the "GNU Affero General Public | ||
* License v3.0 only", or the "Server Side Public License, v 1". | ||
*/ | ||
|
||
import type { | ||
ApiDeprecationDetails, | ||
DomainDeprecationDetails, | ||
} from '@kbn/core-deprecations-common'; | ||
|
||
import type { PostValidationMetadata } from '@kbn/core-http-server'; | ||
import type { BuildApiDeprecationDetailsParams } from '../types'; | ||
import { | ||
getApiDeprecationMessage, | ||
getApiDeprecationsManualSteps, | ||
getApiDeprecationTitle, | ||
} from './i18n_texts'; | ||
|
||
export const getIsAccessApiDeprecation = ({ | ||
isInternalApiRequest, | ||
isPublicAccess, | ||
}: PostValidationMetadata): boolean => { | ||
const isNotPublicAccess = !isPublicAccess; | ||
const isNotInternalRequest = !isInternalApiRequest; | ||
|
||
return !!(isNotPublicAccess && isNotInternalRequest); | ||
}; | ||
|
||
export const buildApiAccessDeprecationDetails = ({ | ||
apiUsageStats, | ||
deprecatedApiDetails, | ||
}: BuildApiDeprecationDetailsParams): DomainDeprecationDetails<ApiDeprecationDetails> => { | ||
const { apiId, apiTotalCalls, totalMarkedAsResolved } = apiUsageStats; | ||
const { routeVersion, routePath, routeDeprecationOptions, routeMethod } = deprecatedApiDetails; | ||
|
||
const deprecationLevel = routeDeprecationOptions?.severity || 'warning'; | ||
|
||
return { | ||
apiId, | ||
title: getApiDeprecationTitle(deprecatedApiDetails), | ||
level: deprecationLevel, | ||
message: getApiDeprecationMessage(deprecatedApiDetails, apiUsageStats), | ||
documentationUrl: routeDeprecationOptions?.documentationUrl, | ||
correctiveActions: { | ||
manualSteps: getApiDeprecationsManualSteps(), | ||
mark_as_resolved_api: { | ||
routePath, | ||
routeMethod, | ||
routeVersion, | ||
apiTotalCalls, | ||
totalMarkedAsResolved, | ||
timestamp: new Date(), | ||
}, | ||
}, | ||
deprecationType: 'api', | ||
domainId: 'core.http.access-deprecations', | ||
}; | ||
}; |
Oops, something went wrong.