mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
Add OpenAPI specs for EEM APIs (#190203)
This commit is contained in:
parent
846ebb290f
commit
e9c913dcb0
18 changed files with 952 additions and 18 deletions
|
@ -571,7 +571,7 @@ security and spaces filtering.
|
|||
|
||||
|
||||
|{kib-repo}blob/{branch}/x-pack/plugins/observability_solution/entity_manager/README.md[entityManager]
|
||||
|This plugin provides access to observed asset data, such as information about hosts, pods, containers, services, and more.
|
||||
|This plugin provides access to observed entity data, such as information about hosts, pods, containers, services, and more.
|
||||
|
||||
|
||||
|{kib-repo}blob/{branch}/x-pack/plugins/event_log/README.md[eventLog]
|
||||
|
|
|
@ -1675,6 +1675,7 @@
|
|||
"exit-hook": "^2.2.0",
|
||||
"expect": "^29.6.1",
|
||||
"expose-loader": "^0.7.5",
|
||||
"express": "^4.19.2",
|
||||
"faker": "^5.1.0",
|
||||
"fetch-mock": "^7.3.9",
|
||||
"file-loader": "^4.2.0",
|
||||
|
@ -1768,6 +1769,8 @@
|
|||
"superagent": "^9.0.2",
|
||||
"supertest": "^7.0.0",
|
||||
"svgo": "^2.8.0",
|
||||
"swagger-jsdoc": "^6.2.8",
|
||||
"swagger-ui-express": "^5.0.1",
|
||||
"table": "^6.8.1",
|
||||
"tape": "^5.0.1",
|
||||
"terser": "^5.31.5",
|
||||
|
|
|
@ -468,6 +468,14 @@
|
|||
"matchBaseBranches": ["main"],
|
||||
"labels": ["release_note:skip", "backport:all-open", "Team:Visualizations"],
|
||||
"enabled": true
|
||||
},
|
||||
{
|
||||
"groupName": "Serve swagger docs",
|
||||
"matchDepNames": ["express", "swagger-jsdoc", "swagger-ui-express"],
|
||||
"reviewers": ["team:obs-entities"],
|
||||
"matchBaseBranches": ["main"],
|
||||
"labels": ["release_note:skip", "team:obs-entities"],
|
||||
"enabled": true
|
||||
}
|
||||
],
|
||||
"customManagers": [
|
||||
|
|
567
x-pack/packages/kbn-entities-schema/oas.yaml
Normal file
567
x-pack/packages/kbn-entities-schema/oas.yaml
Normal file
|
@ -0,0 +1,567 @@
|
|||
openapi: 3.1.0
|
||||
info:
|
||||
title: Elastic Entity Model (EEM) API
|
||||
version: v1
|
||||
components:
|
||||
schemas:
|
||||
createEntityDefinitionQuerySchema:
|
||||
type: object
|
||||
properties:
|
||||
installOnly:
|
||||
type: boolean
|
||||
default: false
|
||||
additionalProperties: false
|
||||
getEntityDefinitionQuerySchema:
|
||||
type: object
|
||||
properties:
|
||||
page:
|
||||
type: number
|
||||
perPage:
|
||||
type: number
|
||||
additionalProperties: false
|
||||
resetEntityDefinitionParamsSchema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
required:
|
||||
- id
|
||||
additionalProperties: false
|
||||
deleteEntityDefinitionParamsSchema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
required:
|
||||
- id
|
||||
additionalProperties: false
|
||||
deleteEntityDefinitionQuerySchema:
|
||||
type: object
|
||||
properties:
|
||||
deleteData:
|
||||
type: boolean
|
||||
default: false
|
||||
additionalProperties: false
|
||||
entityDefinitionSchema:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
pattern: ^[\w-]+$
|
||||
version:
|
||||
type: string
|
||||
name:
|
||||
type: string
|
||||
description:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
filter:
|
||||
type: string
|
||||
indexPatterns:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
identityFields:
|
||||
type: array
|
||||
items:
|
||||
anyOf:
|
||||
- type: object
|
||||
properties:
|
||||
field:
|
||||
type: string
|
||||
optional:
|
||||
type: boolean
|
||||
required:
|
||||
- field
|
||||
- optional
|
||||
additionalProperties: false
|
||||
- type: string
|
||||
displayNameTemplate:
|
||||
type: string
|
||||
metadata:
|
||||
type: array
|
||||
items:
|
||||
anyOf:
|
||||
- type: object
|
||||
properties:
|
||||
source:
|
||||
type: string
|
||||
destination:
|
||||
type: string
|
||||
limit:
|
||||
type: number
|
||||
default: 1000
|
||||
required:
|
||||
- source
|
||||
additionalProperties: false
|
||||
- type: string
|
||||
metrics:
|
||||
type: array
|
||||
items:
|
||||
type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
metrics:
|
||||
type: array
|
||||
items:
|
||||
anyOf:
|
||||
- type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 1
|
||||
pattern: "[a-zA-Z]"
|
||||
aggregation:
|
||||
type: string
|
||||
enum:
|
||||
- avg
|
||||
- max
|
||||
- min
|
||||
- sum
|
||||
- value_count
|
||||
- cardinality
|
||||
- last_value
|
||||
- std_deviation
|
||||
field:
|
||||
type: string
|
||||
filter:
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
- aggregation
|
||||
- field
|
||||
additionalProperties: false
|
||||
- type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 1
|
||||
pattern: "[a-zA-Z]"
|
||||
aggregation:
|
||||
type: string
|
||||
enum:
|
||||
- doc_count
|
||||
filter:
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
- aggregation
|
||||
additionalProperties: false
|
||||
- type: object
|
||||
properties:
|
||||
name:
|
||||
type: string
|
||||
minLength: 1
|
||||
maxLength: 1
|
||||
pattern: "[a-zA-Z]"
|
||||
aggregation:
|
||||
type: string
|
||||
enum:
|
||||
- percentile
|
||||
field:
|
||||
type: string
|
||||
percentile:
|
||||
type: number
|
||||
filter:
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
- aggregation
|
||||
- field
|
||||
- percentile
|
||||
additionalProperties: false
|
||||
equation:
|
||||
type: string
|
||||
required:
|
||||
- name
|
||||
- metrics
|
||||
- equation
|
||||
additionalProperties: false
|
||||
staticFields:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: string
|
||||
managed:
|
||||
type: boolean
|
||||
default: false
|
||||
history:
|
||||
type: object
|
||||
properties:
|
||||
timestampField:
|
||||
type: string
|
||||
interval:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
settings:
|
||||
type: object
|
||||
properties:
|
||||
syncField:
|
||||
type: string
|
||||
syncDelay:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
lookbackPeriod:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
default: 1h
|
||||
frequency:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
backfillSyncDelay:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
backfillLookbackPeriod:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
backfillFrequency:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
additionalProperties: false
|
||||
required:
|
||||
- timestampField
|
||||
- interval
|
||||
additionalProperties: false
|
||||
latest:
|
||||
type: object
|
||||
properties:
|
||||
settings:
|
||||
type: object
|
||||
properties:
|
||||
syncField:
|
||||
type: string
|
||||
syncDelay:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
frequency:
|
||||
type: string
|
||||
pattern: ^\d+[m|d|s|h]$
|
||||
additionalProperties: false
|
||||
additionalProperties: false
|
||||
installStatus:
|
||||
anyOf:
|
||||
- type: string
|
||||
enum:
|
||||
- installing
|
||||
- type: string
|
||||
enum:
|
||||
- upgrading
|
||||
- type: string
|
||||
enum:
|
||||
- installed
|
||||
- type: string
|
||||
enum:
|
||||
- failed
|
||||
installStartedAt:
|
||||
type: string
|
||||
required:
|
||||
- id
|
||||
- version
|
||||
- name
|
||||
- type
|
||||
- indexPatterns
|
||||
- identityFields
|
||||
- displayNameTemplate
|
||||
- history
|
||||
additionalProperties: false
|
||||
entitySummarySchema:
|
||||
allOf:
|
||||
- type: object
|
||||
properties:
|
||||
entity:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
identityFields:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
displayName:
|
||||
type: string
|
||||
metrics:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: number
|
||||
definitionVersion:
|
||||
type: string
|
||||
schemaVersion:
|
||||
type: string
|
||||
definitionId:
|
||||
type: string
|
||||
lastSeenTimestamp:
|
||||
type: string
|
||||
firstSeenTimestamp:
|
||||
type: string
|
||||
required:
|
||||
- id
|
||||
- type
|
||||
- identityFields
|
||||
- displayName
|
||||
- metrics
|
||||
- definitionVersion
|
||||
- schemaVersion
|
||||
- definitionId
|
||||
- lastSeenTimestamp
|
||||
- firstSeenTimestamp
|
||||
additionalProperties: false
|
||||
required:
|
||||
- entity
|
||||
- anyOf:
|
||||
- anyOf:
|
||||
- type: string
|
||||
- type: number
|
||||
- type: boolean
|
||||
- enum:
|
||||
- "null"
|
||||
nullable: true
|
||||
- type: array
|
||||
items: {}
|
||||
- type: object
|
||||
additionalProperties: {}
|
||||
entityHistorySchema:
|
||||
allOf:
|
||||
- type: object
|
||||
properties:
|
||||
"@timestamp":
|
||||
type: string
|
||||
entity:
|
||||
type: object
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
type:
|
||||
type: string
|
||||
identityFields:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
displayName:
|
||||
type: string
|
||||
metrics:
|
||||
type: object
|
||||
additionalProperties:
|
||||
type: number
|
||||
definitionVersion:
|
||||
type: string
|
||||
schemaVersion:
|
||||
type: string
|
||||
definitionId:
|
||||
type: string
|
||||
required:
|
||||
- id
|
||||
- type
|
||||
- identityFields
|
||||
- displayName
|
||||
- metrics
|
||||
- definitionVersion
|
||||
- schemaVersion
|
||||
- definitionId
|
||||
additionalProperties: false
|
||||
required:
|
||||
- "@timestamp"
|
||||
- entity
|
||||
- anyOf:
|
||||
- anyOf:
|
||||
- type: string
|
||||
- type: number
|
||||
- type: boolean
|
||||
- enum:
|
||||
- "null"
|
||||
nullable: true
|
||||
- type: array
|
||||
items: {}
|
||||
- type: object
|
||||
additionalProperties: {}
|
||||
paths:
|
||||
/internal/entities/managed/enablement:
|
||||
get:
|
||||
description: Check if managed (built-in) entity discovery is enabled. Enabled
|
||||
entity discovery requires a valid api key and the latest version of the
|
||||
builtin definitions installed and running.
|
||||
tags:
|
||||
- management
|
||||
responses:
|
||||
"200":
|
||||
description: OK - Verify result in response body
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
enabled:
|
||||
type: boolean
|
||||
example: false
|
||||
reason:
|
||||
type: string
|
||||
example: api_key_not_found
|
||||
delete:
|
||||
description: Disable managed (built-in) entity discovery. This stops and deletes
|
||||
the transforms, ingest pipelines, definitions saved objects, and index
|
||||
templates for this entity definition, as well as the stored API key for
|
||||
entity discovery management.
|
||||
tags:
|
||||
- management
|
||||
parameters:
|
||||
- in: query
|
||||
name: deleteData
|
||||
description: If true, delete all entity data in the managed indices
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
responses:
|
||||
"200":
|
||||
description: Built-in entity discovery successfully disabled
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
"403":
|
||||
description: The current user does not have the required permissions to disable
|
||||
entity discovery
|
||||
put:
|
||||
description: Enable managed (built-in) entity discovery.
|
||||
tags:
|
||||
- management
|
||||
parameters:
|
||||
- in: query
|
||||
name: installOnly
|
||||
description: If true, the definition transforms will not be started
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
responses:
|
||||
"200":
|
||||
description: OK - Verify result in response body
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
success:
|
||||
type: boolean
|
||||
example: false
|
||||
reason:
|
||||
type: string
|
||||
example: api_key_service_disabled
|
||||
message:
|
||||
type: string
|
||||
example: API key service is not enabled; try configuring
|
||||
`xpack.security.authc.api_key.enabled` in your
|
||||
elasticsearch config
|
||||
"403":
|
||||
description: The current user does not have the required permissions to enable
|
||||
entity discovery
|
||||
/internal/entities/definition:
|
||||
post:
|
||||
description: Install an entity definition.
|
||||
tags:
|
||||
- definitions
|
||||
parameters:
|
||||
- in: query
|
||||
name: installOnly
|
||||
description: If true, the definition transforms will not be started
|
||||
required: false
|
||||
schema:
|
||||
type: boolean
|
||||
default: false
|
||||
requestBody:
|
||||
description: The entity definition to install
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/entityDefinitionSchema"
|
||||
responses:
|
||||
"200":
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/entityDefinitionSchema"
|
||||
"400":
|
||||
description: The entity definition cannot be installed; see the error for more
|
||||
details
|
||||
"409":
|
||||
description: An entity definition with this ID already exists
|
||||
delete:
|
||||
description: Uninstall an entity definition. This stops and deletes the
|
||||
transforms, ingest pipelines, definitions saved objects, and index
|
||||
templates for this entity definition.
|
||||
tags:
|
||||
- definitions
|
||||
parameters:
|
||||
- in: path
|
||||
name: id
|
||||
description: The entity definition ID
|
||||
schema:
|
||||
$ref: "#/components/schemas/deleteEntityDefinitionParamsSchema/properties/id"
|
||||
required: true
|
||||
- in: query
|
||||
name: deleteData
|
||||
description: If true, delete all entity data in the indices associated with this
|
||||
entity definition
|
||||
schema:
|
||||
$ref: "#/components/schemas/deleteEntityDefinitionQuerySchema/properties/delete\
|
||||
Data"
|
||||
responses:
|
||||
"200":
|
||||
description: Success
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
acknowledged:
|
||||
type: boolean
|
||||
"400":
|
||||
description: The entity definition cannot be removed; see the error for more
|
||||
details
|
||||
"404":
|
||||
description: Entity definition with given ID not found
|
||||
get:
|
||||
description: Get all installed entity definitions.
|
||||
tags:
|
||||
- definitions
|
||||
parameters:
|
||||
- in: query
|
||||
name: page
|
||||
schema:
|
||||
$ref: "#/components/schemas/getEntityDefinitionQuerySchema/properties/page"
|
||||
- in: query
|
||||
name: perPage
|
||||
schema:
|
||||
$ref: "#/components/schemas/getEntityDefinitionQuerySchema/properties/perPage"
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
definitions:
|
||||
type: array
|
||||
items:
|
||||
allOf:
|
||||
- $ref: "#/components/schemas/entityDefinitionSchema"
|
||||
- type: object
|
||||
properties:
|
||||
state:
|
||||
type: object
|
||||
properties:
|
||||
installed:
|
||||
type: boolean
|
||||
running:
|
||||
type: boolean
|
||||
tags: []
|
|
@ -2,5 +2,9 @@
|
|||
"name": "@kbn/entities-schema",
|
||||
"private": true,
|
||||
"version": "1.0.0",
|
||||
"license": "Elastic License 2.0"
|
||||
}
|
||||
"license": "Elastic License 2.0",
|
||||
"scripts": {
|
||||
"openapi:generate": "node scripts/generate",
|
||||
"openapi:serve": "node scripts/serve_oas_ui"
|
||||
}
|
||||
}
|
||||
|
|
14
x-pack/packages/kbn-entities-schema/scripts/generate.js
Normal file
14
x-pack/packages/kbn-entities-schema/scripts/generate.js
Normal file
|
@ -0,0 +1,14 @@
|
|||
/*
|
||||
* 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; you may not use this file except in compliance with the Elastic License
|
||||
* 2.0.
|
||||
*/
|
||||
|
||||
require('../../../../src/setup_node_env');
|
||||
|
||||
const { generateOAS } = require('./generate_oas');
|
||||
const { writeFileSync } = require('fs');
|
||||
|
||||
const spec = generateOAS({ format: '.yaml' });
|
||||
writeFileSync('oas.yaml', spec);
|
67
x-pack/packages/kbn-entities-schema/scripts/generate_oas.js
Normal file
67
x-pack/packages/kbn-entities-schema/scripts/generate_oas.js
Normal file
|
@ -0,0 +1,67 @@
|
|||
/*
|
||||
* 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; you may not use this file except in compliance with the Elastic License
|
||||
* 2.0.
|
||||
*/
|
||||
|
||||
require('../../../../src/setup_node_env');
|
||||
|
||||
const swaggerJsdoc = require('swagger-jsdoc');
|
||||
const { zodToJsonSchema } = require('zod-to-json-schema');
|
||||
|
||||
const {
|
||||
createEntityDefinitionQuerySchema,
|
||||
getEntityDefinitionQuerySchema,
|
||||
resetEntityDefinitionParamsSchema,
|
||||
deleteEntityDefinitionParamsSchema,
|
||||
deleteEntityDefinitionQuerySchema,
|
||||
entityDefinitionSchema,
|
||||
entityLatestSchema,
|
||||
entityHistorySchema,
|
||||
} = require('..');
|
||||
|
||||
const schemaOptions = {
|
||||
target: 'openApi3',
|
||||
$refStrategy: 'none',
|
||||
};
|
||||
|
||||
export const generateOAS = (options) =>
|
||||
swaggerJsdoc({
|
||||
definition: {
|
||||
openapi: '3.1.0',
|
||||
info: {
|
||||
title: 'Elastic Entity Model (EEM) API',
|
||||
version: 'v1',
|
||||
},
|
||||
components: {
|
||||
schemas: {
|
||||
createEntityDefinitionQuerySchema: zodToJsonSchema(
|
||||
createEntityDefinitionQuerySchema,
|
||||
schemaOptions
|
||||
),
|
||||
getEntityDefinitionQuerySchema: zodToJsonSchema(
|
||||
getEntityDefinitionQuerySchema,
|
||||
schemaOptions
|
||||
),
|
||||
resetEntityDefinitionParamsSchema: zodToJsonSchema(
|
||||
resetEntityDefinitionParamsSchema,
|
||||
schemaOptions
|
||||
),
|
||||
deleteEntityDefinitionParamsSchema: zodToJsonSchema(
|
||||
deleteEntityDefinitionParamsSchema,
|
||||
schemaOptions
|
||||
),
|
||||
deleteEntityDefinitionQuerySchema: zodToJsonSchema(
|
||||
deleteEntityDefinitionQuerySchema,
|
||||
schemaOptions
|
||||
),
|
||||
entityDefinitionSchema: zodToJsonSchema(entityDefinitionSchema, schemaOptions),
|
||||
entitySummarySchema: zodToJsonSchema(entityLatestSchema, schemaOptions),
|
||||
entityHistorySchema: zodToJsonSchema(entityHistorySchema, schemaOptions),
|
||||
},
|
||||
},
|
||||
},
|
||||
apis: ['../../plugins/observability_solution/entity_manager/server/routes/**/*.ts'],
|
||||
...options,
|
||||
});
|
20
x-pack/packages/kbn-entities-schema/scripts/serve_oas_ui.js
Normal file
20
x-pack/packages/kbn-entities-schema/scripts/serve_oas_ui.js
Normal file
|
@ -0,0 +1,20 @@
|
|||
/*
|
||||
* 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; you may not use this file except in compliance with the Elastic License
|
||||
* 2.0.
|
||||
*/
|
||||
|
||||
require('../../../../src/setup_node_env');
|
||||
|
||||
const { generateOAS } = require('./generate_oas');
|
||||
const express = require('express');
|
||||
const swaggerUi = require('swagger-ui-express');
|
||||
|
||||
const app = express();
|
||||
app.use('/', swaggerUi.serve, swaggerUi.setup(generateOAS()));
|
||||
|
||||
const port = 3000;
|
||||
app.listen(port, () => {
|
||||
console.log(`OpenAPI UI available on http://localhost:${port}`);
|
||||
});
|
|
@ -11,7 +11,8 @@
|
|||
"**/*.ts"
|
||||
],
|
||||
"exclude": [
|
||||
"target/**/*"
|
||||
"target/**/*",
|
||||
"node_modules",
|
||||
],
|
||||
"kbn_references": [
|
||||
]
|
||||
|
|
|
@ -1,3 +1,3 @@
|
|||
# Entity Manager Plugin
|
||||
|
||||
This plugin provides access to observed asset data, such as information about hosts, pods, containers, services, and more.
|
||||
This plugin provides access to observed entity data, such as information about hosts, pods, containers, services, and more.
|
||||
|
|
|
@ -4,4 +4,4 @@ Entity definitions are a core concept of the entity model. They define the way t
|
|||
|
||||
#### Builtin Definitions
|
||||
|
||||
Entity discovery is an aggregation of _builtin_ definitions (stored in [builtin directory](../server/lib/entities/built_in)) that Elastic defines and maintains. Because we want to provide updates to existing definitions but also install new ones with future releases, we need a way to perform these actions automatically on behalf of users. To achieve that we ask for an initial _enablement_ step that creates an API key stored as an encrypted saved object. The API key is generated through a REST endpoint and is created with the credentials of the user calling that endpoint. The key requires specific privileges to install/kickoff the transforms (see privileges [here](../server/lib/auth/privileges.ts)). Once a valid key is stored, any actions performed on builtin definitions are made through that key.
|
||||
Entity discovery is an aggregation of _builtin_ definitions (stored in [builtin directory](../server/lib/entities/built_in)) that Elastic defines and maintains. Because we want to provide updates to existing definitions but also install new ones with future releases, we need a way to perform these actions automatically on behalf of users. To achieve that we ask for an initial _enablement_ step that creates an API key stored as an encrypted saved object. The API key is generated through a REST endpoint and is created with the credentials of the user calling that endpoint. The key requires specific privileges to install/kickoff the transforms (see privileges [here](../server/lib/auth/privileges.ts)). Once a valid key is stored, any actions performed on builtin definitions are made through that key.
|
||||
|
|
|
@ -20,6 +20,28 @@ import { findEntityDefinitions } from '../../lib/entities/find_entity_definition
|
|||
import { builtInDefinitions } from '../../lib/entities/built_in';
|
||||
import { getClientsFromAPIKey } from '../../lib/utils';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/managed/enablement:
|
||||
* get:
|
||||
* description: Check if managed (built-in) entity discovery is enabled. Enabled entity discovery requires a valid api key and the latest version of the builtin definitions installed and running.
|
||||
* tags:
|
||||
* - management
|
||||
* responses:
|
||||
* 200:
|
||||
* description: OK - Verify result in response body
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* enabled:
|
||||
* type: boolean
|
||||
* example: false
|
||||
* reason:
|
||||
* type: string
|
||||
* example: api_key_not_found
|
||||
*/
|
||||
export function checkEntityDiscoveryEnabledRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
server,
|
||||
|
|
|
@ -13,6 +13,34 @@ import { uninstallBuiltInEntityDefinitions } from '../../lib/entities/uninstall_
|
|||
import { canDisableEntityDiscovery } from '../../lib/auth/privileges';
|
||||
import { EntityDiscoveryApiKeyType } from '../../saved_objects';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/managed/enablement:
|
||||
* delete:
|
||||
* description: Disable managed (built-in) entity discovery. This stops and deletes the transforms, ingest pipelines, definitions saved objects, and index templates for this entity definition, as well as the stored API key for entity discovery management.
|
||||
* tags:
|
||||
* - management
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: deleteData
|
||||
* description: If true, delete all entity data in the managed indices
|
||||
* required: false
|
||||
* schema:
|
||||
* type: boolean
|
||||
* default: false
|
||||
* responses:
|
||||
* 403:
|
||||
* description: The current user does not have the required permissions to disable entity discovery
|
||||
* 200:
|
||||
* description: Built-in entity discovery successfully disabled
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
*/
|
||||
export function disableEntityDiscoveryRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
server,
|
||||
|
|
|
@ -27,6 +27,41 @@ import { ERROR_API_KEY_SERVICE_DISABLED } from '../../../common/errors';
|
|||
import { EntityDiscoveryApiKeyType } from '../../saved_objects';
|
||||
import { startTransform } from '../../lib/entities/start_transform';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/managed/enablement:
|
||||
* put:
|
||||
* description: Enable managed (built-in) entity discovery.
|
||||
* tags:
|
||||
* - management
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: installOnly
|
||||
* description: If true, the definition transforms will not be started
|
||||
* required: false
|
||||
* schema:
|
||||
* type: boolean
|
||||
* default: false
|
||||
* responses:
|
||||
* 403:
|
||||
* description: The current user does not have the required permissions to enable entity discovery
|
||||
* 200:
|
||||
* description: OK - Verify result in response body
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* success:
|
||||
* type: boolean
|
||||
* example: false
|
||||
* reason:
|
||||
* type: string
|
||||
* example: api_key_service_disabled
|
||||
* message:
|
||||
* type: string
|
||||
* example: API key service is not enabled; try configuring `xpack.security.authc.api_key.enabled` in your elasticsearch config
|
||||
*/
|
||||
export function enableEntityDiscoveryRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
server,
|
||||
|
|
|
@ -20,6 +20,40 @@ import { InvalidTransformError } from '../../lib/entities/errors/invalid_transfo
|
|||
import { startTransform } from '../../lib/entities/start_transform';
|
||||
import { installEntityDefinition } from '../../lib/entities/install_entity_definition';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/definition:
|
||||
* post:
|
||||
* description: Install an entity definition.
|
||||
* tags:
|
||||
* - definitions
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: installOnly
|
||||
* description: If true, the definition transforms will not be started
|
||||
* required: false
|
||||
* schema:
|
||||
* type: boolean
|
||||
* default: false
|
||||
* requestBody:
|
||||
* description: The entity definition to install
|
||||
* required: true
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/entityDefinitionSchema'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Success
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/entityDefinitionSchema'
|
||||
* 409:
|
||||
* description: An entity definition with this ID already exists
|
||||
* 400:
|
||||
* description: The entity definition cannot be installed; see the error for more details
|
||||
*/
|
||||
export function createEntityDefinitionRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
server,
|
||||
|
|
|
@ -18,6 +18,40 @@ import { readEntityDefinition } from '../../lib/entities/read_entity_definition'
|
|||
import { EntityDefinitionNotFound } from '../../lib/entities/errors/entity_not_found';
|
||||
import { uninstallEntityDefinition } from '../../lib/entities/uninstall_entity_definition';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/definition:
|
||||
* delete:
|
||||
* description: Uninstall an entity definition. This stops and deletes the transforms, ingest pipelines, definitions saved objects, and index templates for this entity definition.
|
||||
* tags:
|
||||
* - definitions
|
||||
* parameters:
|
||||
* - in: path
|
||||
* name: id
|
||||
* description: The entity definition ID
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/deleteEntityDefinitionParamsSchema/properties/id'
|
||||
* required: true
|
||||
* - in: query
|
||||
* name: deleteData
|
||||
* description: If true, delete all entity data in the indices associated with this entity definition
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/deleteEntityDefinitionQuerySchema/properties/deleteData'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: Success
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* acknowledged:
|
||||
* type: boolean
|
||||
* 400:
|
||||
* description: The entity definition cannot be removed; see the error for more details
|
||||
* 404:
|
||||
* description: Entity definition with given ID not found
|
||||
*/
|
||||
export function deleteEntityDefinitionRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
server,
|
||||
|
|
|
@ -11,6 +11,45 @@ import { getEntityDefinitionQuerySchema } from '@kbn/entities-schema';
|
|||
import { SetupRouteOptions } from '../types';
|
||||
import { findEntityDefinitions } from '../../lib/entities/find_entity_definition';
|
||||
|
||||
/**
|
||||
* @openapi
|
||||
* /internal/entities/definition:
|
||||
* get:
|
||||
* description: Get all installed entity definitions.
|
||||
* tags:
|
||||
* - definitions
|
||||
* parameters:
|
||||
* - in: query
|
||||
* name: page
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/getEntityDefinitionQuerySchema/properties/page'
|
||||
* - in: query
|
||||
* name: perPage
|
||||
* schema:
|
||||
* $ref: '#/components/schemas/getEntityDefinitionQuerySchema/properties/perPage'
|
||||
* responses:
|
||||
* 200:
|
||||
* description: OK
|
||||
* content:
|
||||
* application/json:
|
||||
* schema:
|
||||
* type: object
|
||||
* properties:
|
||||
* definitions:
|
||||
* type: array
|
||||
* items:
|
||||
* allOf:
|
||||
* - $ref: '#/components/schemas/entityDefinitionSchema'
|
||||
* - type: object
|
||||
* properties:
|
||||
* state:
|
||||
* type: object
|
||||
* properties:
|
||||
* installed:
|
||||
* type: boolean
|
||||
* running:
|
||||
* type: boolean
|
||||
*/
|
||||
export function getEntityDefinitionRoute<T extends RequestHandlerContext>({
|
||||
router,
|
||||
}: SetupRouteOptions<T>) {
|
||||
|
|
82
yarn.lock
82
yarn.lock
|
@ -55,7 +55,7 @@
|
|||
resolved "https://registry.yarnpkg.com/@apidevtools/swagger-methods/-/swagger-methods-3.0.2.tgz#b789a362e055b0340d04712eafe7027ddc1ac267"
|
||||
integrity sha512-QAkD5kK2b1WfjDS/UQn/qQkbwF31uqRjPTrsCs5ZG9BQGAkjwvqGFjjPqAuzac/IYzpPtRzjCP1WrTuAIjMrXg==
|
||||
|
||||
"@apidevtools/swagger-parser@^10.0.3":
|
||||
"@apidevtools/swagger-parser@10.0.3", "@apidevtools/swagger-parser@^10.0.3":
|
||||
version "10.0.3"
|
||||
resolved "https://registry.yarnpkg.com/@apidevtools/swagger-parser/-/swagger-parser-10.0.3.tgz#32057ae99487872c4dd96b314a1ab4b95d89eaf5"
|
||||
integrity sha512-sNiLY51vZOmSPFZA5TF35KZ2HbgYklQnTSDnkghamzLb3EkNtcQnrBQEj5AOCxHpTtXpqMCRM1CrmV2rG6nw4g==
|
||||
|
@ -14581,6 +14581,11 @@ commander@2, commander@^2.19.0, commander@^2.20.0, commander@^2.7.1:
|
|||
resolved "https://registry.yarnpkg.com/commander/-/commander-2.20.3.tgz#fd485e84c03eb4881c20722ba48035e8531aeb33"
|
||||
integrity sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==
|
||||
|
||||
commander@6.2.0:
|
||||
version "6.2.0"
|
||||
resolved "https://registry.yarnpkg.com/commander/-/commander-6.2.0.tgz#b990bfb8ac030aedc6d11bc04d1488ffef56db75"
|
||||
integrity sha512-zP4jEKbe8SHzKJYQmq8Y9gYjtO/POJLgIdKgV7B9qNmABVFVc+ctqSX6iXh4mCpJfRBOabiZ2YKPg8ciDw6C+Q==
|
||||
|
||||
commander@7, commander@^7.0.0, commander@^7.2.0:
|
||||
version "7.2.0"
|
||||
resolved "https://registry.yarnpkg.com/commander/-/commander-7.2.0.tgz#a36cb57d0b501ce108e4d20559a150a391d97ab7"
|
||||
|
@ -16303,6 +16308,13 @@ dns-packet@^5.2.2:
|
|||
dependencies:
|
||||
"@leichtgewicht/ip-codec" "^2.0.1"
|
||||
|
||||
doctrine@3.0.0, doctrine@^3.0.0:
|
||||
version "3.0.0"
|
||||
resolved "https://registry.yarnpkg.com/doctrine/-/doctrine-3.0.0.tgz#addebead72a6574db783639dc87a121773973961"
|
||||
integrity sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==
|
||||
dependencies:
|
||||
esutils "^2.0.2"
|
||||
|
||||
doctrine@^2.1.0:
|
||||
version "2.1.0"
|
||||
resolved "https://registry.yarnpkg.com/doctrine/-/doctrine-2.1.0.tgz#5cd01fc101621b42c4cd7f5d1a66243716d3f39d"
|
||||
|
@ -16310,13 +16322,6 @@ doctrine@^2.1.0:
|
|||
dependencies:
|
||||
esutils "^2.0.2"
|
||||
|
||||
doctrine@^3.0.0:
|
||||
version "3.0.0"
|
||||
resolved "https://registry.yarnpkg.com/doctrine/-/doctrine-3.0.0.tgz#addebead72a6574db783639dc87a121773973961"
|
||||
integrity sha512-yS+Q5i3hBf7GBkd4KG8a7eBNNWNGLTaEwwYWUijIYM7zrlYDM0BFXHjjPWlWZ1Rg7UaddZeIDmi9jF3HmqiQ2w==
|
||||
dependencies:
|
||||
esutils "^2.0.2"
|
||||
|
||||
dom-accessibility-api@^0.5.6, dom-accessibility-api@^0.5.9:
|
||||
version "0.5.13"
|
||||
resolved "https://registry.yarnpkg.com/dom-accessibility-api/-/dom-accessibility-api-0.5.13.tgz#102ee5f25eacce09bdf1cfa5a298f86da473be4b"
|
||||
|
@ -17757,7 +17762,7 @@ expr-eval@^2.0.2:
|
|||
resolved "https://registry.yarnpkg.com/expr-eval/-/expr-eval-2.0.2.tgz#fa6f044a7b0c93fde830954eb9c5b0f7fbc7e201"
|
||||
integrity sha512-4EMSHGOPSwAfBiibw3ndnP0AvjDWLsMvGOvWEZ2F96IGk0bIVdjQisOHxReSkE13mHcfbuCiXw+G4y0zv6N8Eg==
|
||||
|
||||
express@^4.17.1, express@^4.17.3, express@^4.18.2:
|
||||
express@^4.17.1, express@^4.17.3, express@^4.18.2, express@^4.19.2:
|
||||
version "4.19.2"
|
||||
resolved "https://registry.yarnpkg.com/express/-/express-4.19.2.tgz#e25437827a3aa7f2a827bc8171bbbb664a356465"
|
||||
integrity sha512-5T6nhjsT+EOMzuck8JjBHARTHfMht0POzlA60WV2pMD3gyXw2LZnZ+ueGdNxG+0calOJcWKbpFcuzLZ91YWq9Q==
|
||||
|
@ -18918,6 +18923,18 @@ glob-to-regexp@^0.4.0, glob-to-regexp@^0.4.1:
|
|||
resolved "https://registry.yarnpkg.com/glob-to-regexp/-/glob-to-regexp-0.4.1.tgz#c75297087c851b9a578bd217dd59a92f59fe546e"
|
||||
integrity sha512-lkX1HJXwyMcprw/5YUZc2s7DrpAiHB21/V+E1rHUrVNokkvB6bqMzT0VfV6/86ZNabt1k14YOIaT7nDvOX3Iiw==
|
||||
|
||||
glob@7.1.6:
|
||||
version "7.1.6"
|
||||
resolved "https://registry.yarnpkg.com/glob/-/glob-7.1.6.tgz#141f33b81a7c2492e125594307480c46679278a6"
|
||||
integrity sha512-LwaxwyZ72Lk7vZINtNNrywX0ZuLyStrdDtabefZKAY5ZGJhVtgdznluResxNmPitE0SAO+O26sWTHeKSI2wMBA==
|
||||
dependencies:
|
||||
fs.realpath "^1.0.0"
|
||||
inflight "^1.0.4"
|
||||
inherits "2"
|
||||
minimatch "^3.0.4"
|
||||
once "^1.3.0"
|
||||
path-is-absolute "^1.0.0"
|
||||
|
||||
glob@7.2.0:
|
||||
version "7.2.0"
|
||||
resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.0.tgz#d15535af7732e02e948f4c41628bd910293f6023"
|
||||
|
@ -22464,6 +22481,11 @@ lodash.merge@4.6.2, lodash.merge@^4.6.2:
|
|||
resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a"
|
||||
integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==
|
||||
|
||||
lodash.mergewith@^4.6.2:
|
||||
version "4.6.2"
|
||||
resolved "https://registry.yarnpkg.com/lodash.mergewith/-/lodash.mergewith-4.6.2.tgz#617121f89ac55f59047c7aec1ccd6654c6590f55"
|
||||
integrity sha512-GK3g5RPZWTRSeLSpgP8Xhra+pnjBC56q9FZYe1d5RN3TJ35dbkGy3YqBSMbyCrlbi+CM9Z3Jk5yTL7RCsqboyQ==
|
||||
|
||||
lodash.once@^4.0.0, lodash.once@^4.1.1:
|
||||
version "4.1.1"
|
||||
resolved "https://registry.yarnpkg.com/lodash.once/-/lodash.once-4.1.1.tgz#0dd3971213c7c56df880977d504c88fb471a97ac"
|
||||
|
@ -29965,6 +29987,37 @@ svgo@^2.7.0, svgo@^2.8.0:
|
|||
picocolors "^1.0.0"
|
||||
stable "^0.1.8"
|
||||
|
||||
swagger-jsdoc@^6.2.8:
|
||||
version "6.2.8"
|
||||
resolved "https://registry.yarnpkg.com/swagger-jsdoc/-/swagger-jsdoc-6.2.8.tgz#6d33d9fb07ff4a7c1564379c52c08989ec7d0256"
|
||||
integrity sha512-VPvil1+JRpmJ55CgAtn8DIcpBs0bL5L3q5bVQvF4tAW/k/9JYSj7dCpaYCAv5rufe0vcCbBRQXGvzpkWjvLklQ==
|
||||
dependencies:
|
||||
commander "6.2.0"
|
||||
doctrine "3.0.0"
|
||||
glob "7.1.6"
|
||||
lodash.mergewith "^4.6.2"
|
||||
swagger-parser "^10.0.3"
|
||||
yaml "2.0.0-1"
|
||||
|
||||
swagger-parser@^10.0.3:
|
||||
version "10.0.3"
|
||||
resolved "https://registry.yarnpkg.com/swagger-parser/-/swagger-parser-10.0.3.tgz#04cb01c18c3ac192b41161c77f81e79309135d03"
|
||||
integrity sha512-nF7oMeL4KypldrQhac8RyHerJeGPD1p2xDh900GPvc+Nk7nWP6jX2FcC7WmkinMoAmoO774+AFXcWsW8gMWEIg==
|
||||
dependencies:
|
||||
"@apidevtools/swagger-parser" "10.0.3"
|
||||
|
||||
swagger-ui-dist@>=5.0.0:
|
||||
version "5.17.14"
|
||||
resolved "https://registry.yarnpkg.com/swagger-ui-dist/-/swagger-ui-dist-5.17.14.tgz#e2c222e5bf9e15ccf80ec4bc08b4aaac09792fd6"
|
||||
integrity sha512-CVbSfaLpstV65OnSjbXfVd6Sta3q3F7Cj/yYuvHMp1P90LztOLs6PfUnKEVAeiIVQt9u2SaPwv0LiH/OyMjHRw==
|
||||
|
||||
swagger-ui-express@^5.0.1:
|
||||
version "5.0.1"
|
||||
resolved "https://registry.yarnpkg.com/swagger-ui-express/-/swagger-ui-express-5.0.1.tgz#fb8c1b781d2793a6bd2f8a205a3f4bd6fa020dd8"
|
||||
integrity sha512-SrNU3RiBGTLLmFU8GIJdOdanJTl4TOmT27tt3bWWHppqYmAZ6IDuEuBvMU6nZq0zLEe6b/1rACXCgLZqO6ZfrA==
|
||||
dependencies:
|
||||
swagger-ui-dist ">=5.0.0"
|
||||
|
||||
swagger2openapi@^7.0.8:
|
||||
version "7.0.8"
|
||||
resolved "https://registry.yarnpkg.com/swagger2openapi/-/swagger2openapi-7.0.8.tgz#12c88d5de776cb1cbba758994930f40ad0afac59"
|
||||
|
@ -32750,6 +32803,11 @@ yaml-ast-parser@0.0.43:
|
|||
resolved "https://registry.yarnpkg.com/yaml-ast-parser/-/yaml-ast-parser-0.0.43.tgz#e8a23e6fb4c38076ab92995c5dca33f3d3d7c9bb"
|
||||
integrity sha512-2PTINUwsRqSd+s8XxKaJWQlUuEMHJQyEuh2edBbW8KNJz0SJPwUSD2zRWqezFEdN7IzAgeuYHFUCF7o8zRdZ0A==
|
||||
|
||||
yaml@2.0.0-1:
|
||||
version "2.0.0-1"
|
||||
resolved "https://registry.yarnpkg.com/yaml/-/yaml-2.0.0-1.tgz#8c3029b3ee2028306d5bcf396980623115ff8d18"
|
||||
integrity sha512-W7h5dEhywMKenDJh2iX/LABkbFnBxasD27oyXWDS/feDsxiw0dD5ncXdYXgkvAsXIY2MpW/ZKkr9IU30DBdMNQ==
|
||||
|
||||
yaml@^1.10.0, yaml@^1.10.2, yaml@^1.7.2:
|
||||
version "1.10.2"
|
||||
resolved "https://registry.yarnpkg.com/yaml/-/yaml-1.10.2.tgz#2301c5ffbf12b467de8da2333a459e29e7920e4b"
|
||||
|
@ -32926,9 +32984,9 @@ zip-stream@^4.1.0:
|
|||
readable-stream "^3.6.0"
|
||||
|
||||
zod-to-json-schema@^3.22.3, zod-to-json-schema@^3.22.4, zod-to-json-schema@^3.22.5, zod-to-json-schema@^3.23.0:
|
||||
version "3.23.0"
|
||||
resolved "https://registry.yarnpkg.com/zod-to-json-schema/-/zod-to-json-schema-3.23.0.tgz#4fc60e88d3c709eedbfaae3f92f8a7bf786469f2"
|
||||
integrity sha512-az0uJ243PxsRIa2x1WmNE/pnuA05gUq/JB8Lwe1EDCCL/Fz9MgjYQ0fPlyc2Tcv6aF2ZA7WM5TWaRZVEFaAIag==
|
||||
version "3.23.2"
|
||||
resolved "https://registry.yarnpkg.com/zod-to-json-schema/-/zod-to-json-schema-3.23.2.tgz#bc7e379c8050462538383e382964c03d8fe008f9"
|
||||
integrity sha512-uSt90Gzc/tUfyNqxnjlfBs8W6WSGpNBv0rVsNxP/BVSMHMKGdthPYff4xtCHYloJGM0CFxFsb3NbC0eqPhfImw==
|
||||
|
||||
zod@3.23.8, zod@^3.22.3, zod@^3.22.4, zod@^3.23.8:
|
||||
version "3.23.8"
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue