github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-24 09:48:58 -04:00
Code Issues Projects Releases Packages Wiki Activity

[8.8][DOCS] Clarify API key authorization for alerting (#161717) (#162077)

Browse source 
# Backport

This will backport the following commits from `main` to `8.8`:
- [[DOCS] Clarify API key authorization for alerting
(#161717)](https://github.com/elastic/kibana/pull/161717)

It also backports part of the changes from
https://github.com/elastic/kibana/pull/159186, in particular, the
addition of the path for the randomly-generated rule identifier.
This commit is contained in:
Lisa Cawley 2023-07-17 14:10:09 -07:00 • committed by GitHub
parent bd98322092
commit a548cbde7b
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
10 changed files with 811 additions and 425 deletions
Download patch file Download diff file Expand all files Collapse all files

249
docs/api-generated/rules/rule-apis-passthru.asciidoc
View file

@ -18,7 +18,8 @@ Any modifications made to this file will be overwritten.
<div class="method-summary"></div>
<h4><a href="#Alerting">Alerting</a></h4>
<ul>
<li><a href="#createRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></a></li>
<li><a href="#createRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule</code></a></li>
<li><a href="#createRuleId"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></a></li>
<li><a href="#deleteRule"><code><span class="http-method">delete</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></a></li>
<li><a href="#disableRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}/_disable</code></a></li>
<li><a href="#enableRule"><code><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}/_enable</code></a></li>
@ -48,11 +49,247 @@ Any modifications made to this file will be overwritten.
<h1><a name="Alerting">Alerting</a></h1>
<div class="method"><a name="createRule"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="post"><code class="huge"><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule</code></pre></div>
<div class="method-summary">Creates a rule with a randomly generated rule identifier. (<span class="nickname">createRule</span>)</div>
<div class="method-notes">To create a rule, you must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're creating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">
<div class="param">spaceId (required)</div>
<div class="param-desc"><span class="param-type">Path Parameter</span> &mdash; An identifier for the space. If <code>/s/</code> and the identifier are omitted from the path, the default space is used. default: null </div>
</div> <!-- field-items -->
<h3 class="field-label">Consumes</h3>
This API call consumes the following media types via the <span class="header">Content-Type</span> request header:
<ul>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Request body</h3>
<div class="field-items">
<div class="param">create_rule_request <a href="#create_rule_request">create_rule_request</a> (required)</div>
<div class="param-desc"><span class="param-type">Body Parameter</span> &mdash; </div>
</div> <!-- field-items -->
<h3 class="field-label">Request headers</h3>
<div class="field-items">
<div class="param">kbn-xsrf (required)</div>
<div class="param-desc"><span class="param-type">Header Parameter</span> &mdash; Cross-site request forgery protection default: null </div>
</div> <!-- field-items -->
<h3 class="field-label">Return type</h3>
<div class="return-type">
<a href="#rule_response_properties">rule_response_properties</a>
</div>
<!--Todo: process Response Object and its headers, schema, examples -->
<h3 class="field-label">Example data</h3>
<div class="example-data-content-type">Content-Type: application/json</div>
<pre class="example"><code>{
"throttle" : "10m",
"created_at" : "2022-12-05T23:36:58.284Z",
"api_key_created_by_user" : false,
"enabled" : true,
"running" : true,
"notify_when" : "notify_when",
"next_run" : "2022-12-06T00:14:43.818Z",
"updated_at" : "2022-12-05T23:36:58.284Z",
"execution_status" : {
"last_execution_date" : "2022-12-06T00:13:43.89Z",
"last_duration" : 55,
"status" : "ok"
},
"scheduled_task_id" : "b530fed0-74f5-11ed-9801-35303b735aef",
"id" : "b530fed0-74f5-11ed-9801-35303b735aef",
"consumer" : "alerts",
"last_run" : {
"alerts_count" : {
"ignored" : 6,
"new" : 1,
"recovered" : 5,
"active" : 0
},
"outcome_msg" : [ "outcome_msg", "outcome_msg" ],
"outcome_order" : 5,
"warning" : "warning",
"outcome" : "succeeded"
},
"params" : {
"key" : ""
},
"created_by" : "elastic",
"muted_alert_ids" : [ "muted_alert_ids", "muted_alert_ids" ],
"rule_type_id" : "monitoring_alert_cluster_health",
"revision" : 2,
"tags" : [ "tags", "tags" ],
"api_key_owner" : "elastic",
"schedule" : {
"interval" : "1m"
},
"name" : "cluster_health_rule",
"updated_by" : "elastic",
"mute_all" : false,
"actions" : [ {
"alerts_filter" : {
"timeframe" : {
"hours" : {
"start" : "08:00",
"end" : "17:00"
},
"timezone" : "Europe/Madrid",
"days" : [ 1, 2, 3, 4, 5 ]
},
"query" : {
"kql" : "kql",
"filters" : [ {
"$state" : "{}",
"meta" : {
"field" : "field",
"controlledBy" : "controlledBy",
"negate" : true,
"alias" : "alias",
"index" : "index",
"disabled" : true,
"params" : "{}",
"type" : "type",
"value" : "value",
"isMultiIndex" : true,
"key" : "key",
"group" : "group"
},
"query" : "{}"
}, {
"$state" : "{}",
"meta" : {
"field" : "field",
"controlledBy" : "controlledBy",
"negate" : true,
"alias" : "alias",
"index" : "index",
"disabled" : true,
"params" : "{}",
"type" : "type",
"value" : "value",
"isMultiIndex" : true,
"key" : "key",
"group" : "group"
},
"query" : "{}"
} ]
}
},
"id" : "9dca3e00-74f5-11ed-9801-35303b735aef",
"params" : {
"key" : ""
},
"uuid" : "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
"connector_type_id" : ".server-log",
"frequency" : {
"summary" : true,
"throttle" : "10m",
"notify_when" : "onActiveAlert"
},
"group" : "default"
}, {
"alerts_filter" : {
"timeframe" : {
"hours" : {
"start" : "08:00",
"end" : "17:00"
},
"timezone" : "Europe/Madrid",
"days" : [ 1, 2, 3, 4, 5 ]
},
"query" : {
"kql" : "kql",
"filters" : [ {
"$state" : "{}",
"meta" : {
"field" : "field",
"controlledBy" : "controlledBy",
"negate" : true,
"alias" : "alias",
"index" : "index",
"disabled" : true,
"params" : "{}",
"type" : "type",
"value" : "value",
"isMultiIndex" : true,
"key" : "key",
"group" : "group"
},
"query" : "{}"
}, {
"$state" : "{}",
"meta" : {
"field" : "field",
"controlledBy" : "controlledBy",
"negate" : true,
"alias" : "alias",
"index" : "index",
"disabled" : true,
"params" : "{}",
"type" : "type",
"value" : "value",
"isMultiIndex" : true,
"key" : "key",
"group" : "group"
},
"query" : "{}"
} ]
}
},
"id" : "9dca3e00-74f5-11ed-9801-35303b735aef",
"params" : {
"key" : ""
},
"uuid" : "1c7a1280-f28c-4e06-96b2-e4e5f05d1d61",
"connector_type_id" : ".server-log",
"frequency" : {
"summary" : true,
"throttle" : "10m",
"notify_when" : "onActiveAlert"
},
"group" : "default"
} ]
}</code></pre>
<h3 class="field-label">Produces</h3>
This API call produces the following media types according to the <span class="header">Accept</span> request header;
the media type will be conveyed by the <span class="header">Content-Type</span> response header.
<ul>
<li><code>application/json</code></li>
</ul>
<h3 class="field-label">Responses</h3>
<h4 class="field-label">200</h4>
Indicates a successful call.
<a href="#rule_response_properties">rule_response_properties</a>
<h4 class="field-label">401</h4>
Authorization information is missing or invalid.
<a href="#401_response">401_response</a>
<h4 class="field-label">404</h4>
Object is not found.
<a href="#404_response">404_response</a>
</div> <!-- method -->
<hr/>
<div class="method"><a name="createRuleId"/>
<div class="method-path">
<a class="up" href="#__Methods">Up</a>
<pre class="post"><code class="huge"><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></pre></div>
<div class="method-summary">Creates a rule. (<span class="nickname">createRule</span>)</div>
<div class="method-notes">You must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're creating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.</div>
<div class="method-summary">Creates a rule. (<span class="nickname">createRuleId</span>)</div>
<div class="method-notes">To create a rule, you must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're creating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">
@ -290,7 +527,7 @@ Any modifications made to this file will be overwritten.
<a class="up" href="#__Methods">Up</a>
<pre class="delete"><code class="huge"><span class="http-method">delete</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></pre></div>
<div class="method-summary">Deletes a rule. (<span class="nickname">deleteRule</span>)</div>
<div class="method-notes">You must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're deleting. For example, the <strong>Management</strong> &gt; <strong>Stack Rules</strong> feature, <strong>Analytics</strong> &gt; <strong>Discover</strong> or <strong>Machine Learning</strong> features, <strong>Observability</strong>, or <strong>Security</strong> features. WARNING: After you delete a rule, you cannot recover it.</div>
<div class="method-notes">To delete a rule, you must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're deleting. For example, the <strong>Management</strong> &gt; <strong>Stack Rules</strong> feature, <strong>Analytics</strong> &gt; <strong>Discover</strong> or <strong>Machine Learning</strong> features, <strong>Observability</strong>, or <strong>Security</strong> features. WARNING: After you delete a rule, you cannot recover it. If the API key that is used by the rule was created automatically, it is deleted.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">
@ -392,7 +629,7 @@ Any modifications made to this file will be overwritten.
<a class="up" href="#__Methods">Up</a>
<pre class="post"><code class="huge"><span class="http-method">post</span> /s/{spaceId}/api/alerting/rule/{ruleId}/_enable</code></pre></div>
<div class="method-summary">Enables a rule. (<span class="nickname">enableRule</span>)</div>
<div class="method-notes">This API supports token-based authentication only. You must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule. For example, the <strong>Management &gt; Stack Rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong>, and <strong>Security</strong> features.</div>
<div class="method-notes">To enable a rule, you must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule. For example, the <strong>Management &gt; Stack Rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong>, and <strong>Security</strong> features. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">
@ -2357,7 +2594,7 @@ Any modifications made to this file will be overwritten.
<a class="up" href="#__Methods">Up</a>
<pre class="put"><code class="huge"><span class="http-method">put</span> /s/{spaceId}/api/alerting/rule/{ruleId}</code></pre></div>
<div class="method-summary">Updates the attributes for a rule. (<span class="nickname">updateRule</span>)</div>
<div class="method-notes">You must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're updating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. NOTE: This API supports only token-based authentication. When you update a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If you have different privileges than the user that created or most recently updated the rule, you might change its behavior. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.</div>
<div class="method-notes">To update a rule, you must have <code>all</code> privileges for the appropriate Kibana features, depending on the <code>consumer</code> and <code>rule_type_id</code> of the rule you're updating. For example, you must have privileges for the <strong>Management &gt; Stack rules</strong> feature, <strong>Analytics &gt; Discover</strong> and <strong>Machine Learning</strong> features, <strong>Observability</strong> features, or <strong>Security</strong> features. If the rule has actions, you must also have <code>read</code> privileges for the <strong>Management &gt; Actions and Connectors</strong> feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs. NOTE: If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.</div>
<h3 class="field-label">Path parameters</h3>
<div class="field-items">

11
docs/api/alerting/create_rule.asciidoc
View file

@ -30,17 +30,6 @@ you must also have `read` privileges for the *Management* >
*{connectors-feature}* feature. For more details, refer to
<<kibana-feature-privileges>>.
=== {api-description-title}
[WARNING]
====
* This API supports only
<<token-api-authentication,token-based authentication>>.
* When you create a rule, it identifies which roles you have at that point in time.
Thereafter, when the rule performs queries, it uses those security privileges.
If a user with different privileges updates the rule, its behavior might change.
====
[[create-rule-api-path-params]]
=== {api-path-parms-title}

15
docs/api/alerting/update_rule.asciidoc
View file

@ -29,21 +29,6 @@ features, *{observability}*, or *Security* features. If the rule has
*{connectors-feature}* feature. For more details, refer to
<<kibana-feature-privileges>>.
=== {api-description-title}
[WARNING]
====
* This API supports only
<<token-api-authentication,token-based authentication>>.
* When you update a rule, it identifies which roles you have at that point in time.
Thereafter, when the rule performs queries, it uses those security privileges.
If you have different privileges than the user that created or most recently
updated the rule, you might change its behavior.
* Though some properties are optional, when you update the rule the existing
property values are overwritten with default values. Therefore, it is
recommended to explicitly set all property values.
====
[[update-rule-api-path-params]]
=== {api-path-parms-title}

30
docs/user/alerting/alerting-setup.asciidoc
View file

@ -4,6 +4,11 @@
<titleabbrev>Set up</titleabbrev>
++++
:frontmatter-description: Prerequisites and production considerations for using {kib} {alert-features}.
:frontmatter-tags-products: [alerting]
:frontmatter-tags-content-type: [other]
:frontmatter-tags-user-goals: [configure]
{kib} {alert-features} are automatically enabled, but might require some additional
configuration.
@ -77,27 +82,26 @@ A rule or connector created in one space will not be visible in another.
Rules are authorized using an API key.
Its credentials are used to run all background tasks associated with the rule, including condition checks like {es} queries and triggered actions.
You can create API keys and use them in the header of your API calls as described in <<api-keys>>.
If you create or edit a rule in {kib}, an API key is created that captures a snapshot of your privileges at the time of the edit. The following actions regenerate the API key in {kib}:
If you create or edit a rule in {kib}, an API key is created that captures a snapshot of your privileges at the time of the edit.
The following actions regenerate the API key in {kib}:
* Creating a rule
* Updating a rule
When you disable a rule, it retains the associated API key which is reused when
the rule is enabled. If the API key is missing when you enable the rule (for
example, in the case of imported rules), it generates a new key that has your
security privileges.
When you disable a rule, it retains the associated API key which is reused when the rule is enabled.
If the API key is missing when you enable the rule (for example, in the case of imported rules), it generates a new key that has your security privileges.
You can update an API key manually in
**{stack-manage-app} > {rules-ui}** or in the rule details page by selecting
**Update API key** in the actions menu.
You can update an API key manually in **{stack-manage-app} > {rules-ui}** or in the rule details page by selecting **Update API key** in the actions menu.
If you manage your rules by using {kib} APIs, they support support both key- and token-based authentication as described in <<api-authentication>>.
To use key-based authentication, create API keys and use them in the header of your API calls as described in <<api-keys>>.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently associated with the rule and used when it runs.
[IMPORTANT]
==============================================
If a rule requires certain privileges, such as index privileges, to run and a
user without those privileges updates the rule, the rule will no longer
function. Conversely, if a user with greater or administrator privileges
modifies the rule, it will begin running with increased privileges.
If a rule requires certain privileges, such as index privileges, to run and a user without those privileges updates the rule, the rule will no longer function.
Conversely, if a user with greater or administrator privileges modifies the rule, it will begin running with increased privileges.
The same behavior occurs when you change the API key in the header of your API calls.
==============================================

452
x-pack/plugins/alerting/docs/openapi/bundled.json
View file

@ -25,6 +25,86 @@
}
],
"paths": {
"/s/{spaceId}/api/alerting/rule": {
"post": {
"summary": "Creates a rule with a randomly generated rule identifier.",
"operationId": "createRule",
"description": "To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.\n",
"tags": [
"alerting"
],
"parameters": [
{
"$ref": "#/components/parameters/kbn_xsrf"
},
{
"$ref": "#/components/parameters/space_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create_rule_request"
},
"examples": {
"createRuleRequest": {
"$ref": "#/components/examples/create_rule_request"
}
}
}
}
},
"responses": {
"200": {
"description": "Indicates a successful call.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/rule_response_properties"
},
"examples": {
"createRuleResponse": {
"$ref": "#/components/examples/create_rule_response"
}
}
}
}
},
"401": {
"description": "Authorization information is missing or invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/401_response"
}
}
}
},
"404": {
"description": "Object is not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/404_response"
}
}
}
}
},
"servers": [
{
"url": "https://localhost:5601"
}
]
},
"servers": [
{
"url": "https://localhost:5601"
}
]
},
"/s/{spaceId}/api/alerting/rule/{ruleId}": {
"get": {
"summary": "Retrieves a rule by its identifier.",
@ -87,7 +167,7 @@
"delete": {
"summary": "Deletes a rule.",
"operationId": "deleteRule",
"description": "You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're deleting. For example, the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or **Machine Learning** features, **Observability**, or **Security** features. WARNING: After you delete a rule, you cannot recover it.\n",
"description": "To delete a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're deleting. For example, the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or **Machine Learning** features, **Observability**, or **Security** features. WARNING: After you delete a rule, you cannot recover it. If the API key that is used by the rule was created automatically, it is deleted.\n",
"tags": [
"alerting"
],
@ -135,8 +215,8 @@
},
"post": {
"summary": "Creates a rule.",
"operationId": "createRule",
"description": "You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.\n",
"operationId": "createRuleId",
"description": "To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.\n",
"tags": [
"alerting"
],
@ -166,7 +246,7 @@
"$ref": "#/components/schemas/create_rule_request"
},
"examples": {
"createCaseRequest": {
"createRuleIdRequest": {
"$ref": "#/components/examples/create_rule_request"
}
}
@ -182,7 +262,7 @@
"$ref": "#/components/schemas/rule_response_properties"
},
"examples": {
"createRuleResponse": {
"createRuleIdResponse": {
"$ref": "#/components/examples/create_rule_response"
}
}
@ -219,7 +299,7 @@
"put": {
"summary": "Updates the attributes for a rule.",
"operationId": "updateRule",
"description": "You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're updating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you update a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If you have different privileges than the user that created or most recently updated the rule, you might change its behavior. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.\n",
"description": "To update a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're updating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs. NOTE: If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.\n",
"tags": [
"alerting"
],
@ -242,7 +322,7 @@
"$ref": "#/components/schemas/update_rule_request"
},
"examples": {
"updateCaseRequest": {
"updateRuleRequest": {
"$ref": "#/components/examples/update_rule_request"
}
}
@ -358,7 +438,7 @@
"post": {
"summary": "Enables a rule.",
"operationId": "enableRule",
"description": "This API supports token-based authentication only. You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule. For example, the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability**, and **Security** features.\n",
"description": "To enable a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule. For example, the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability**, and **Security** features. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.\n",
"tags": [
"alerting"
],
@ -2409,15 +2489,14 @@
}
},
"parameters": {
"rule_id": {
"in": "path",
"name": "ruleId",
"description": "An identifier for the rule.",
"required": true,
"kbn_xsrf": {
"schema": {
"type": "string",
"example": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74"
}
"type": "string"
},
"in": "header",
"name": "kbn-xsrf",
"description": "Cross-site request forgery protection",
"required": true
},
"space_id": {
"in": "path",
@ -2429,14 +2508,15 @@
"example": "default"
}
},
"kbn_xsrf": {
"rule_id": {
"in": "path",
"name": "ruleId",
"description": "An identifier for the rule.",
"required": true,
"schema": {
"type": "string"
},
"in": "header",
"name": "kbn-xsrf",
"description": "Cross-site request forgery protection",
"required": true
"type": "string",
"example": "ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74"
}
},
"alert_id": {
"in": "path",
@ -2660,6 +2740,57 @@
},
"default": []
},
"create_rule_request": {
"title": "Create rule request",
"description": "The create rule API request body varies depending on the type of rule and actions.",
"type": "object",
"required": [
"consumer",
"name",
"params",
"rule_type_id",
"schedule"
],
"properties": {
"actions": {
"$ref": "#/components/schemas/actions"
},
"consumer": {
"type": "string",
"description": "The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.\n"
},
"enabled": {
"type": "boolean",
"description": "Indicates whether you want to run the rule on an interval basis after it is created."
},
"name": {
"type": "string",
"description": "The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.",
"example": "cluster_health_rule"
},
"notify_when": {
"$ref": "#/components/schemas/notify_when"
},
"params": {
"type": "object",
"description": "The parameters for the rule.",
"additionalProperties": true
},
"rule_type_id": {
"type": "string",
"description": "The ID of the rule type that you want to call when the rule is scheduled to run. For example, `.es-query`, `.index-threshold`, `logs.alert.document.count`, `monitoring_alert_cluster_health`, `siem.thresholdRule`, or `xpack.ml.anomaly_detection_alert`.\n"
},
"schedule": {
"$ref": "#/components/schemas/schedule"
},
"tags": {
"$ref": "#/components/schemas/tags"
},
"throttle": {
"$ref": "#/components/schemas/throttle"
}
}
},
"rule_response_properties": {
"title": "Rule response properties",
"type": "object",
@ -2938,57 +3069,6 @@
}
}
},
"create_rule_request": {
"title": "Create rule request",
"description": "The create rule API request body varies depending on the type of rule and actions.",
"type": "object",
"required": [
"consumer",
"name",
"params",
"rule_type_id",
"schedule"
],
"properties": {
"actions": {
"$ref": "#/components/schemas/actions"
},
"consumer": {
"type": "string",
"description": "The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.\n"
},
"enabled": {
"type": "boolean",
"description": "Indicates whether you want to run the rule on an interval basis after it is created."
},
"name": {
"type": "string",
"description": "The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.",
"example": "cluster_health_rule"
},
"notify_when": {
"$ref": "#/components/schemas/notify_when"
},
"params": {
"type": "object",
"description": "The parameters for the rule.",
"additionalProperties": true
},
"rule_type_id": {
"type": "string",
"description": "The ID of the rule type that you want to call when the rule is scheduled to run. For example, `.es-query`, `.index-threshold`, `logs.alert.document.count`, `monitoring_alert_cluster_health`, `siem.thresholdRule`, or `xpack.ml.anomaly_detection_alert`.\n"
},
"schedule": {
"$ref": "#/components/schemas/schedule"
},
"tags": {
"$ref": "#/components/schemas/tags"
},
"throttle": {
"$ref": "#/components/schemas/throttle"
}
}
},
"alert_response_properties": {
"title": "Legacy alert response properties",
"type": "object",
@ -3103,6 +3183,118 @@
}
},
"examples": {
"create_rule_request": {
"summary": "Create an index threshold rule.",
"value": {
"actions": [
{
"id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
"frequency": {
"notify_when": "onActionGroupChange",
"summary": false
},
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
}
}
],
"consumer": "alerts",
"name": "my rule",
"params": {
"aggType": "avg",
"termSize": 6,
"thresholdComparator": ">",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"groupBy": "top",
"threshold": [
1000
],
"index": [
".test-index"
],
"timeField": "@timestamp",
"aggField": "sheet.version",
"termField": "name.keyword"
},
"rule_type_id": ".index-threshold",
"schedule": {
"interval": "1m"
},
"tags": [
"cpu"
]
}
},
"create_rule_response": {
"summary": "The create rule API returns a JSON object that contains details about the rule.",
"value": {
"actions": [
{
"group": "threshold met",
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
"uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
"connector_type_id": ".server-log",
"frequency": {
"notify_when": "onActionGroupChange",
"summary": false,
"throttle": null
},
"params": {
"level": "info",
"message": "Rule {{rule.name}} is active for group {{context.group} :\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
}
}
],
"api_key_created_by_user": false,
"api_key_owner": "elastic",
"consumer": "alerts",
"created_at": "2022-06-08T17:20:31.632Z",
"created_by": "elastic",
"enabled": true,
"execution_status": {
"last_execution_date": "2022-06-08T17:20:31.632Z",
"status": "pending"
},
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
"muted_alert_ids": [],
"mute_all": false,
"name": "my rule",
"notify_when": null,
"params": {
"aggType": "avg",
"termSize": 6,
"thresholdComparator": ">",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"groupBy": "top",
"threshold": [
1000
],
"index": [
".test-index"
],
"timeField": "@timestamp",
"aggField": "sheet.version",
"termField": "name.keyword"
},
"revision": 0,
"rule_type_id": ".index-threshold",
"running": false,
"schedule": {
"interval": "1m"
},
"scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
"tags": [
"cpu"
],
"throttle": null,
"updated_at": "2022-06-08T17:20:31.632Z",
"updated_by": "elastic"
}
},
"get_rule_response": {
"summary": "The get rule API returns a JSON object that contains details about the rule.",
"value": {
@ -3302,118 +3494,6 @@
"api_key_created_by_user": false
}
},
"create_rule_request": {
"summary": "Create an index threshold rule.",
"value": {
"actions": [
{
"id": "48de3460-f401-11ed-9f8e-399c75a2deeb",
"frequency": {
"notify_when": "onActionGroupChange",
"summary": false
},
"group": "threshold met",
"params": {
"level": "info",
"message": "Rule '{{rule.name}}' is active for group '{{context.group}}':\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
}
}
],
"consumer": "alerts",
"name": "my rule",
"params": {
"aggType": "avg",
"termSize": 6,
"thresholdComparator": ">",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"groupBy": "top",
"threshold": [
1000
],
"index": [
".test-index"
],
"timeField": "@timestamp",
"aggField": "sheet.version",
"termField": "name.keyword"
},
"rule_type_id": ".index-threshold",
"schedule": {
"interval": "1m"
},
"tags": [
"cpu"
]
}
},
"create_rule_response": {
"summary": "The create rule API returns a JSON object that contains details about the rule.",
"value": {
"actions": [
{
"group": "threshold met",
"id": "dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2",
"uuid": "07aef2a0-9eed-4ef9-94ec-39ba58eb609d",
"connector_type_id": ".server-log",
"frequency": {
"notify_when": "onActionGroupChange",
"summary": false,
"throttle": null
},
"params": {
"level": "info",
"message": "Rule {{rule.name}} is active for group {{context.group} :\n\n- Value: {{context.value}}\n- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}\n- Timestamp: {{context.date}}"
}
}
],
"api_key_created_by_user": false,
"api_key_owner": "elastic",
"consumer": "alerts",
"created_at": "2022-06-08T17:20:31.632Z",
"created_by": "elastic",
"enabled": true,
"execution_status": {
"last_execution_date": "2022-06-08T17:20:31.632Z",
"status": "pending"
},
"id": "41893910-6bca-11eb-9e0d-85d233e3ee35",
"muted_alert_ids": [],
"mute_all": false,
"name": "my rule",
"notify_when": null,
"params": {
"aggType": "avg",
"termSize": 6,
"thresholdComparator": ">",
"timeWindowSize": 5,
"timeWindowUnit": "m",
"groupBy": "top",
"threshold": [
1000
],
"index": [
".test-index"
],
"timeField": "@timestamp",
"aggField": "sheet.version",
"termField": "name.keyword"
},
"revision": 0,
"rule_type_id": ".index-threshold",
"running": false,
"schedule": {
"interval": "1m"
},
"scheduled_task_id": "425b0800-6bca-11eb-9e0d-85d233e3ee35",
"tags": [
"cpu"
],
"throttle": null,
"updated_at": "2022-06-08T17:20:31.632Z",
"updated_by": "elastic"
}
},
"find_rules_response": {
"summary": "Retrieve information about a rule.",
"value": {

358
x-pack/plugins/alerting/docs/openapi/bundled.yaml
View file

@ -15,6 +15,52 @@ servers:
- url: http://localhost:5601
description: local
paths:
/s/{spaceId}/api/alerting/rule:
post:
summary: Creates a rule with a randomly generated rule identifier.
operationId: createRule
description: |
To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters:
- $ref: '#/components/parameters/kbn_xsrf'
- $ref: '#/components/parameters/space_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/create_rule_request'
examples:
createRuleRequest:
$ref: '#/components/examples/create_rule_request'
responses:
'200':
description: Indicates a successful call.
content:
application/json:
schema:
$ref: '#/components/schemas/rule_response_properties'
examples:
createRuleResponse:
$ref: '#/components/examples/create_rule_response'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/401_response'
'404':
description: Object is not found.
content:
application/json:
schema:
$ref: '#/components/schemas/404_response'
servers:
- url: https://localhost:5601
servers:
- url: https://localhost:5601
/s/{spaceId}/api/alerting/rule/{ruleId}:
get:
summary: Retrieves a rule by its identifier.
@ -54,7 +100,7 @@ paths:
summary: Deletes a rule.
operationId: deleteRule
description: |
You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're deleting. For example, the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or **Machine Learning** features, **Observability**, or **Security** features. WARNING: After you delete a rule, you cannot recover it.
To delete a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're deleting. For example, the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or **Machine Learning** features, **Observability**, or **Security** features. WARNING: After you delete a rule, you cannot recover it. If the API key that is used by the rule was created automatically, it is deleted.
tags:
- alerting
parameters:
@ -80,9 +126,9 @@ paths:
- url: https://localhost:5601
post:
summary: Creates a rule.
operationId: createRule
operationId: createRuleId
description: |
You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you create a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If a user with different privileges updates the rule, its behavior might change.
To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters:
@ -103,7 +149,7 @@ paths:
schema:
$ref: '#/components/schemas/create_rule_request'
examples:
createCaseRequest:
createRuleIdRequest:
$ref: '#/components/examples/create_rule_request'
responses:
'200':
@ -113,7 +159,7 @@ paths:
schema:
$ref: '#/components/schemas/rule_response_properties'
examples:
createRuleResponse:
createRuleIdResponse:
$ref: '#/components/examples/create_rule_response'
'401':
description: Authorization information is missing or invalid.
@ -133,7 +179,7 @@ paths:
summary: Updates the attributes for a rule.
operationId: updateRule
description: |
You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're updating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. NOTE: This API supports only token-based authentication. When you update a rule, it identifies which roles you have at that point in time. Thereafter, when the rule performs queries, it uses those security privileges. If you have different privileges than the user that created or most recently updated the rule, you might change its behavior. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.
To update a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're updating. For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features. If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs. NOTE: If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change. Though some properties are optional, when you update the rule the existing property values are overwritten with default values. Therefore, it is recommended to explicitly set all property values.
tags:
- alerting
parameters:
@ -147,7 +193,7 @@ paths:
schema:
$ref: '#/components/schemas/update_rule_request'
examples:
updateCaseRequest:
updateRuleRequest:
$ref: '#/components/examples/update_rule_request'
responses:
'200':
@ -211,7 +257,7 @@ paths:
summary: Enables a rule.
operationId: enableRule
description: |
This API supports token-based authentication only. You must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule. For example, the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability**, and **Security** features.
To enable a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule. For example, the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability**, and **Security** features. This API supports both key- and token-based authentication. To use key-based authentication, create an API key in Kibana and use it in the header of the API call. To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically. In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters:
@ -1515,14 +1561,13 @@ components:
in: header
name: ApiKey
parameters:
rule_id:
in: path
name: ruleId
description: An identifier for the rule.
required: true
kbn_xsrf:
schema:
type: string
example: ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
in: header
name: kbn-xsrf
description: Cross-site request forgery protection
required: true
space_id:
in: path
name: spaceId
@ -1531,13 +1576,14 @@ components:
schema:
type: string
example: default
kbn_xsrf:
rule_id:
in: path
name: ruleId
description: An identifier for the rule.
required: true
schema:
type: string
in: header
name: kbn-xsrf
description: Cross-site request forgery protection
required: true
example: ac4e6b90-6be7-11eb-ba0d-9b1c1f912d74
alert_id:
in: path
name: alertId
@ -1706,6 +1752,46 @@ components:
items:
type: string
default: []
create_rule_request:
title: Create rule request
description: The create rule API request body varies depending on the type of rule and actions.
type: object
required:
- consumer
- name
- params
- rule_type_id
- schedule
properties:
actions:
$ref: '#/components/schemas/actions'
consumer:
type: string
description: |
The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.
enabled:
type: boolean
description: Indicates whether you want to run the rule on an interval basis after it is created.
name:
type: string
description: The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
example: cluster_health_rule
notify_when:
$ref: '#/components/schemas/notify_when'
params:
type: object
description: The parameters for the rule.
additionalProperties: true
rule_type_id:
type: string
description: |
The ID of the rule type that you want to call when the rule is scheduled to run. For example, `.es-query`, `.index-threshold`, `logs.alert.document.count`, `monitoring_alert_cluster_health`, `siem.thresholdRule`, or `xpack.ml.anomaly_detection_alert`.
schedule:
$ref: '#/components/schemas/schedule'
tags:
$ref: '#/components/schemas/tags'
throttle:
$ref: '#/components/schemas/throttle'
rule_response_properties:
title: Rule response properties
type: object
@ -1918,46 +2004,6 @@ components:
$ref: '#/components/schemas/tags'
throttle:
$ref: '#/components/schemas/throttle'
create_rule_request:
title: Create rule request
description: The create rule API request body varies depending on the type of rule and actions.
type: object
required:
- consumer
- name
- params
- rule_type_id
- schedule
properties:
actions:
$ref: '#/components/schemas/actions'
consumer:
type: string
description: |
The name of the application or feature that owns the rule. For example: `alerts`, `apm`, `discover`, `infrastructure`, `logs`, `metrics`, `ml`, `monitoring`, `securitySolution`, `siem`, `stackAlerts`, or `uptime`.
enabled:
type: boolean
description: Indicates whether you want to run the rule on an interval basis after it is created.
name:
type: string
description: The name of the rule. While this name does not have to be unique, a distinctive name can help you identify a rule.
example: cluster_health_rule
notify_when:
$ref: '#/components/schemas/notify_when'
params:
type: object
description: The parameters for the rule.
additionalProperties: true
rule_type_id:
type: string
description: |
The ID of the rule type that you want to call when the rule is scheduled to run. For example, `.es-query`, `.index-threshold`, `logs.alert.document.count`, `monitoring_alert_cluster_health`, `siem.thresholdRule`, or `xpack.ml.anomaly_detection_alert`.
schedule:
$ref: '#/components/schemas/schedule'
tags:
$ref: '#/components/schemas/tags'
throttle:
$ref: '#/components/schemas/throttle'
alert_response_properties:
title: Legacy alert response properties
type: object
@ -2042,6 +2088,103 @@ components:
nullable: true
example: elastic
examples:
create_rule_request:
summary: Create an index threshold rule.
value:
actions:
- id: 48de3460-f401-11ed-9f8e-399c75a2deeb
frequency:
notify_when: onActionGroupChange
summary: false
group: threshold met
params:
level: info
message: |-
Rule '{{rule.name}}' is active for group '{{context.group}}':
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}
consumer: alerts
name: my rule
params:
aggType: avg
termSize: 6
thresholdComparator: '>'
timeWindowSize: 5
timeWindowUnit: m
groupBy: top
threshold:
- 1000
index:
- .test-index
timeField: '@timestamp'
aggField: sheet.version
termField: name.keyword
rule_type_id: .index-threshold
schedule:
interval: 1m
tags:
- cpu
create_rule_response:
summary: The create rule API returns a JSON object that contains details about the rule.
value:
actions:
- group: threshold met
id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
uuid: 07aef2a0-9eed-4ef9-94ec-39ba58eb609d
connector_type_id: .server-log
frequency:
notify_when: onActionGroupChange
summary: false
throttle: null
params:
level: info
message: |-
Rule {{rule.name}} is active for group {{context.group} :
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}
api_key_created_by_user: false
api_key_owner: elastic
consumer: alerts
created_at: '2022-06-08T17:20:31.632Z'
created_by: elastic
enabled: true
execution_status:
last_execution_date: '2022-06-08T17:20:31.632Z'
status: pending
id: 41893910-6bca-11eb-9e0d-85d233e3ee35
muted_alert_ids: []
mute_all: false
name: my rule
notify_when: null
params:
aggType: avg
termSize: 6
thresholdComparator: '>'
timeWindowSize: 5
timeWindowUnit: m
groupBy: top
threshold:
- 1000
index:
- .test-index
timeField: '@timestamp'
aggField: sheet.version
termField: name.keyword
revision: 0
rule_type_id: .index-threshold
running: false
schedule:
interval: 1m
scheduled_task_id: 425b0800-6bca-11eb-9e0d-85d233e3ee35
tags:
- cpu
throttle: null
updated_at: '2022-06-08T17:20:31.632Z'
updated_by: elastic
get_rule_response:
summary: The get rule API returns a JSON object that contains details about the rule.
value:
@ -2216,103 +2359,6 @@ components:
outcome: succeeded
next_run: '2023-01-31T23:49:42.432Z'
api_key_created_by_user: false
create_rule_request:
summary: Create an index threshold rule.
value:
actions:
- id: 48de3460-f401-11ed-9f8e-399c75a2deeb
frequency:
notify_when: onActionGroupChange
summary: false
group: threshold met
params:
level: info
message: |-
Rule '{{rule.name}}' is active for group '{{context.group}}':
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}
consumer: alerts
name: my rule
params:
aggType: avg
termSize: 6
thresholdComparator: '>'
timeWindowSize: 5
timeWindowUnit: m
groupBy: top
threshold:
- 1000
index:
- .test-index
timeField: '@timestamp'
aggField: sheet.version
termField: name.keyword
rule_type_id: .index-threshold
schedule:
interval: 1m
tags:
- cpu
create_rule_response:
summary: The create rule API returns a JSON object that contains details about the rule.
value:
actions:
- group: threshold met
id: dceeb5d0-6b41-11eb-802b-85b0c1bc8ba2
uuid: 07aef2a0-9eed-4ef9-94ec-39ba58eb609d
connector_type_id: .server-log
frequency:
notify_when: onActionGroupChange
summary: false
throttle: null
params:
level: info
message: |-
Rule {{rule.name}} is active for group {{context.group} :
- Value: {{context.value}}
- Conditions Met: {{context.conditions}} over {{rule.params.timeWindowSize}}{{rule.params.timeWindowUnit}}
- Timestamp: {{context.date}}
api_key_created_by_user: false
api_key_owner: elastic
consumer: alerts
created_at: '2022-06-08T17:20:31.632Z'
created_by: elastic
enabled: true
execution_status:
last_execution_date: '2022-06-08T17:20:31.632Z'
status: pending
id: 41893910-6bca-11eb-9e0d-85d233e3ee35
muted_alert_ids: []
mute_all: false
name: my rule
notify_when: null
params:
aggType: avg
termSize: 6
thresholdComparator: '>'
timeWindowSize: 5
timeWindowUnit: m
groupBy: top
threshold:
- 1000
index:
- .test-index
timeField: '@timestamp'
aggField: sheet.version
termField: name.keyword
revision: 0
rule_type_id: .index-threshold
running: false
schedule:
interval: 1m
scheduled_task_id: 425b0800-6bca-11eb-9e0d-85d233e3ee35
tags:
- cpu
throttle: null
updated_at: '2022-06-08T17:20:31.632Z'
updated_by: elastic
find_rules_response:
summary: Retrieve information about a rule.
value:

2
x-pack/plugins/alerting/docs/openapi/entrypoint.yaml
View file

@ -15,6 +15,8 @@ servers:
- url: 'http://localhost:5601'
description: local
paths:
'/s/{spaceId}/api/alerting/rule':
$ref: 'paths/s@{spaceid}@api@alerting@rule.yaml'
'/s/{spaceId}/api/alerting/rule/{ruleId}':
$ref: 'paths/s@{spaceid}@api@alerting@rule@{ruleid}.yaml'
'/s/{spaceId}/api/alerting/rule/{ruleId}/_disable':

51
x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule.yaml Normal file
View file

@ -0,0 +1,51 @@
post:
summary: Creates a rule with a randomly generated rule identifier.
operationId: createRule
description: >
To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating.
For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features.
If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature.
This API supports both key- and token-based authentication.
To use key-based authentication, create an API key in Kibana and use it in the header of the API call.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters:
- $ref: ../components/headers/kbn_xsrf.yaml
- $ref: '../components/parameters/space_id.yaml'
requestBody:
required: true
content:
application/json:
schema:
$ref: '../components/schemas/create_rule_request.yaml'
examples:
createRuleRequest:
$ref: '../components/examples/create_rule_request.yaml'
responses:
'200':
description: Indicates a successful call.
content:
application/json:
schema:
$ref: '../components/schemas/rule_response_properties.yaml'
examples:
createRuleResponse:
$ref: '../components/examples/create_rule_response.yaml'
'401':
description: Authorization information is missing or invalid.
content:
application/json:
schema:
$ref: '../components/schemas/401_response.yaml'
'404':
description: Object is not found.
content:
application/json:
schema:
$ref: '../components/schemas/404_response.yaml'
servers:
- url: https://localhost:5601
servers:
- url: https://localhost:5601

57
x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule@{ruleid}.yaml
View file

@ -42,11 +42,10 @@ delete:
summary: Deletes a rule.
operationId: deleteRule
description: >
You must have `all` privileges for the appropriate Kibana features, depending
on the `consumer` and `rule_type_id` of the rule you're deleting. For example,
the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or
**Machine Learning** features, **Observability**, or **Security** features.
To delete a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're deleting.
For example, the **Management** > **Stack Rules** feature, **Analytics** > **Discover** or **Machine Learning** features, **Observability**, or **Security** features.
WARNING: After you delete a rule, you cannot recover it.
If the API key that is used by the rule was created automatically, it is deleted.
tags:
- alerting
parameters:
@ -73,19 +72,15 @@ delete:
post:
summary: Creates a rule.
operationId: createRule
operationId: createRuleId
description: >
You must have `all` privileges for the appropriate Kibana features,
depending on the `consumer` and `rule_type_id` of the rule you're creating.
For example, you must have privileges for the **Management > Stack rules**
feature, **Analytics > Discover** and **Machine Learning** features,
**Observability** features, or **Security** features. If the rule has
actions, you must also have `read` privileges for the
**Management > Actions and Connectors** feature. NOTE: This API supports
only token-based authentication. When you create a rule, it identifies which
roles you have at that point in time. Thereafter, when the rule performs
queries, it uses those security privileges. If a user with different
privileges updates the rule, its behavior might change.
To create a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're creating.
For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features.
If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature.
This API supports both key- and token-based authentication.
To use key-based authentication, create an API key in Kibana and use it in the header of the API call.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters:
@ -105,9 +100,9 @@ post:
content:
application/json:
schema:
$ref: '../components/schemas/create_rule_request.yaml'
$ref: '../components/schemas/create_rule_request.yaml'
examples:
createCaseRequest:
createRuleIdRequest:
$ref: '../components/examples/create_rule_request.yaml'
responses:
'200':
@ -117,7 +112,7 @@ post:
schema:
$ref: '../components/schemas/rule_response_properties.yaml'
examples:
createRuleResponse:
createRuleIdResponse:
$ref: '../components/examples/create_rule_response.yaml'
'401':
description: Authorization information is missing or invalid.
@ -138,19 +133,15 @@ put:
summary: Updates the attributes for a rule.
operationId: updateRule
description: >
You must have `all` privileges for the appropriate Kibana features,
depending on the `consumer` and `rule_type_id` of the rule you're updating.
For example, you must have privileges for the **Management > Stack rules**
feature, **Analytics > Discover** and **Machine Learning** features,
**Observability** features, or **Security** features. If the rule has
actions, you must also have `read` privileges for the
**Management > Actions and Connectors** feature. NOTE: This API supports
only token-based authentication. When you update a rule, it identifies which
roles you have at that point in time. Thereafter, when the rule performs
queries, it uses those security privileges. If you have different privileges
than the user that created or most recently updated the rule, you might
change its behavior. Though some properties are optional, when you update
the rule the existing property values are overwritten with default values.
To update a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule you're updating.
For example, you must have privileges for the **Management > Stack rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability** features, or **Security** features.
If the rule has actions, you must also have `read` privileges for the **Management > Actions and Connectors** feature.
This API supports both key- and token-based authentication.
To use key-based authentication, create an API key in Kibana and use it in the header of the API call.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently used for authorization when the rule runs.
NOTE: If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change.
Though some properties are optional, when you update the rule the existing property values are overwritten with default values.
Therefore, it is recommended to explicitly set all property values.
tags:
- alerting
@ -165,7 +156,7 @@ put:
schema:
$ref: '../components/schemas/update_rule_request.yaml'
examples:
updateCaseRequest:
updateRuleRequest:
$ref: '../components/examples/update_rule_request.yaml'
responses:
'200':

11
x-pack/plugins/alerting/docs/openapi/paths/s@{spaceid}@api@alerting@rule@{ruleid}@_enable.yaml
View file

@ -2,11 +2,12 @@ post:
summary: Enables a rule.
operationId: enableRule
description: >
This API supports token-based authentication only.
You must have `all` privileges for the appropriate Kibana features,
depending on the `consumer` and `rule_type_id` of the rule. For example, the
**Management > Stack Rules** feature, **Analytics > Discover** and
**Machine Learning** features, **Observability**, and **Security** features.
To enable a rule, you must have `all` privileges for the appropriate Kibana features, depending on the `consumer` and `rule_type_id` of the rule.
For example, the **Management > Stack Rules** feature, **Analytics > Discover** and **Machine Learning** features, **Observability**, and **Security** features.
This API supports both key- and token-based authentication.
To use key-based authentication, create an API key in Kibana and use it in the header of the API call.
To use token-based authentication, provide a username and password; an API key that matches the current privileges of the user is created automatically.
In both cases, the API key is subsequently used for authorization when the rule runs.
tags:
- alerting
parameters: