From 35791b2e1bdfea2658d23d62094bc7c568f29c39 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Sun, 5 Jul 2026 19:26:08 -0400 Subject: [PATCH 1/2] RBAC and tutorial --- .../get-started.md | 8 +- .../get-started/configure-access.md | 32 +++- .../get-started/create-your-first-rule.md | 161 +++++++++++------- .../get-started/setup.md | 29 ++-- 4 files changed, 141 insertions(+), 89 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/get-started.md b/explore-analyze/alerting/kibana-alerting-experimental/get-started.md index b87fdfed6c..1dd2d740d5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/get-started.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/get-started.md @@ -6,13 +6,13 @@ applies_to: products: - id: kibana - id: cloud-serverless -description: "Enable the experimental alerting system in Kibana, configure role access, and create your first rule." +description: "Get started with the experimental alerting system in Kibana: review requirements, enable the system, configure role access, and follow a tutorial to create a rule and observe the alert lifecycle." --- # Get started with the {{alerting-v2-system}} [alerting-v2-get-started] Use these guides to get the {{alerting-v2-system}} running in your space, set up role access for your team, and create your first rule. -- [Turn on the {{alerting-v2-system-cap}}](get-started/setup.md): Enable the `alerting:v2:enabled` advanced setting and confirm the system is accessible in your space. -- [Configure access](get-started/configure-access.md): Set up a role with the {{kib}} feature privileges and {{es}} index privileges needed to create rules and query alert data. -- [Create your first rule](get-started/create-your-first-rule.md): A hands-on tutorial that walks you through loading sample data, creating a rule, and watching the alert lifecycle play out from breach to recovery. +- [Set up the {{alerting-v2-system-cap}}](get-started/setup.md): Review requirements, enable the `alerting:v2:enabled` advanced setting, and confirm the system is accessible in your space. +- [Configure access](get-started/configure-access.md): Set up a role with the {{kib}} feature privileges needed to create rules, triage alerts, and query alert data. +- [Create your first rule](get-started/create-your-first-rule.md): A hands-on tutorial that walks you through loading sample data, creating a rule, and observing the alert lifecycle from breach through automatic recovery. diff --git a/explore-analyze/alerting/kibana-alerting-experimental/get-started/configure-access.md b/explore-analyze/alerting/kibana-alerting-experimental/get-started/configure-access.md index 7bcfa75653..0b7a6fe8d5 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/get-started/configure-access.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/get-started/configure-access.md @@ -29,7 +29,8 @@ The following table shows the minimum privileges required for each activity. Hig | Monitor rule execution | **Execution history: Read** (under **Alerting**) | | Triage alert episodes | **Alerts: All** (under **Alerting**) | | Configure notifications | **Action Policies: All** (under **Alerting**) + **Workflows: Read** (under **Analytics > Workflows**) | -| Query rule and episode data in Discover | **Discover: Read** (under **Analytics > Discover**) + `read` index privilege on the relevant data stream | +| Query `.rule-events` and `.alert-actions` in Discover | **Discover: Read** (under **Analytics > Discover**) + **Alerts: Read** (Elasticsearch `read` access is bundled automatically) | +| Query `.kibana-event-log-*` in Discover | **Discover: Read** (under **Analytics > Discover**) + custom role with `read` index privilege on `.kibana-event-log-*` | ## Author and monitor rules [alerting-authoring-monitoring-privileges] @@ -66,6 +67,10 @@ The **Alerts** privilege controls who can take triage actions on alert episodes. | **All** | Acknowledge, snooze, assign, tag, activate, and deactivate alert episodes | | **Read** | View alert episodes | +:::{note} +Granting **Alerts: All** or **Alerts: Read** also gives the role direct Elasticsearch `read` access to `.rule-events` and `.alert-actions`, scoped to that role's spaces. This is bundled into the privilege — no separate custom role or index privilege is needed to query these data streams in Discover. +::: + ## Configure notifications [alerting-notifications-privileges] These privileges control who can set up the action policies and workflows that route alert episode notifications. @@ -109,16 +114,25 @@ Both levels grant the same query access. There is no write surface for any of th ### {{es}} index access -Each data source requires a separate `read` index privilege: +For `.rule-events` and `.alert-actions`, Elasticsearch `read` access is bundled into the **Alerts** Kibana privilege — nothing extra to configure. For `.kibana-event-log-*`, a custom role is still required. -| Data source | What it stores | Required privilege | +| Data source | What it stores | How to grant access | |---|---|---| -| `.rule-events` | A record for every rule evaluation — one document per result row per run | `read` | -| `.alert-actions` | Episode action records: acknowledge, snooze, resolve, assign, and other triage operations | `read` | -| `.kibana-event-log-*` | Action policy dispatch outcomes written by the dispatcher: `dispatched`, `throttled`, and `unmatched` | `read` | +| `.rule-events` | A record for every rule evaluation; one document per result row per run | Automatic with **Alerts: All** or **Alerts: Read**. If access is missing, grant `read` using a custom role as a fallback. | +| `.alert-actions` | Episode action records: acknowledge, snooze, resolve, assign, and other triage operations | Automatic with **Alerts: All** or **Alerts: Read**. If access is missing, grant `read` using a custom role as a fallback. | +| `.kibana-event-log-*` | Action policy dispatch outcomes written by the dispatcher: `dispatched`, `throttled`, and `unmatched` | Custom role with `read` index privilege. Not covered by the automatic grant. | + +## Next steps [alerting-access-next-steps] -Because `.rule-events` and `.alert-actions` are hidden system data streams, request access through a custom role with the appropriate index privileges. +With access configured, you're ready to start using the {{alerting-v2-system}}: - + + diff --git a/explore-analyze/alerting/kibana-alerting-experimental/get-started/create-your-first-rule.md b/explore-analyze/alerting/kibana-alerting-experimental/get-started/create-your-first-rule.md index 9fae4794f3..71d418bef7 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/get-started/create-your-first-rule.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/get-started/create-your-first-rule.md @@ -6,21 +6,46 @@ applies_to: products: - id: kibana - id: cloud-serverless -description: "Step-by-step tutorial for creating your first rule in Kibana's experimental alerting system: load sample latency data, write an ES|QL detection query, configure the rule, and observe the alert episode lifecycle from breach to automatic recovery." +description: "Tutorial for creating an ES|QL rule in Kibana's experimental alerting system. Covers how alert delay controls when an episode opens, how .rule-events records each evaluation, and how default recovery closes an episode automatically when no breach is detected." --- -# Create your first rule [alerting-quick-start] +# Tutorial: Create a rule and observe the alert lifecycle [alerting-quick-start] -In this tutorial, you'll create an index of synthetic latency data, build a rule that detects when P95 latency for a service exceeds 2 seconds, and watch the episode lifecycle move from breach detection through automatic recovery. Along the way, you'll learn how the {{alerting-v2-system}} tracks conditions over time. +In this tutorial, you'll use the {{alerting-v2-system}} to detect a real-world performance problem and watch what happens next. You'll see how the system decides when a condition is serious enough to open an alert, how it tracks that alert over time, and how it closes automatically when things return to normal, without any manual intervention. -## Prerequisites [alerting-quick-start-prerequisites] +Here's what you'll do: -- **Enable the {{alerting-v2-system}}:** The feature must be turned on in your space before you can create rules or view the UI. Refer to [Set up the {{alerting-v2-system}}](setup.md) for instructions. -- **Configure access:** Your role must include the following privileges to complete this tutorial. Refer to [{{kib}} role management](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) for instructions on creating or updating a role. - - **Rules: All** (under **Alerting** in {{kib}} role management) to create and manage rules - - **Discover: Read** and `read` index privilege on `.rule-events` to query rule output in Discover +1. **Load sample data.** Create an index and populate it with synthetic latency data that moves through healthy, degraded, and recovered phases. This gives you a realistic dataset to work with without needing a live service. +2. **Write a detection query.** Use the query sandbox to build and preview an {{esql}} query that computes P95 latency and flags breaches. The sandbox lets you verify the logic before the rule ever runs. +3. **Configure the rule.** Set the alert condition, schedule, lookback window, and recovery behavior. You'll see how each setting shapes the alert lifecycle. +4. **Watch the episode open.** Query `.rule-events` in Discover to see the rule evaluating on schedule and the episode moving from `pending` to `active` as the breach persists. +5. **Watch it recover.** See the episode close automatically once the degraded data falls outside the lookback window, with no manual step required. -## Tutorial [alerting-quick-start-tutorial] +## Requirements [alerting-quick-start-requirements] + +Before you start, make sure you have the following. + +- **A serverless project**: This tutorial uses an {{serverless-full}} project. [Create a serverless project](/deploy-manage/deploy/elastic-cloud/serverless.md) if you don't have one. + + + +- **The {{alerting-v2-system}} enabled**: The feature must be turned on in your space before you can create rules or view the UI. Refer to [Set up the {{alerting-v2-system}}](setup.md) for instructions. + +- **The required access**: Your [role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) must give you access to: + + | Task | Required privilege | + |---|---| + | Create and manage rules | **Rules: All** (under **Alerting**) | + | Triage and query alert data in Discover | **Alerts: Read** (under **Alerting**); automatically grants {{es}} `read` access to `.rule-events`, no separate index privilege needed | + | Run queries in Discover | **Discover: Read** (under **Analytics**) | + | Create the tutorial index and load sample data | `create_index` and `write` index privileges on `checkout-service-logs` | + +## Prepare your environment [alerting-quick-start-prepare] + +Before creating the rule, set up the index and load the sample data it will query. :::::{stepper} @@ -48,16 +73,16 @@ Confirm the response shows `"acknowledged": true` before proceeding. ::::{step} Load the sample data -Expand the drop-down below (at the end of this step) to copy the full bulk request, then run it in Dev Tools. It populates the index with ~40 minutes of synthetic latency data for a `checkout` service covering three phases: +Expand the drop-down below to copy the full bulk request, then run it in Dev Tools. It populates the index with synthetic latency data for a `checkout` service covering three phases: -- **Healthy** (first ~16 minutes): P95 well under 2 seconds -- **Degraded** (next ~15 minutes): P95 well over 2 seconds, spanning 3 consecutive 5-minute windows -- **Recovered** (final ~10 minutes): P95 returns to healthy levels +- **Healthy** (`21:57`–`22:12`): P95 well under 2 seconds +- **Degraded** (`22:13`–`22:27`): P95 well over 2 seconds across 3 consecutive 5-minute windows +- **Recovered** (`22:28`–`22:37`): P95 returns to healthy levels -The response should show `errors: false` for all documents. The dataset gives you: healthy through `22:12`, degraded `22:13`–`22:27` (spanning 3 consecutive 5-minute windows), recovered from `22:28` onward. +The response should show `errors: false` for all documents. :::{note} -The timestamps in this request are fixed to `2026-07-02`. For the full episode lifecycle to play out as described, load this data and create the rule within 60 minutes, or adjust the timestamps to a recent window before running. For example, open the request in a text editor and use find-and-replace to substitute `2026-07-02` with today's date in `YYYY-MM-DD` format, keeping the time portion (`T21:57` through `T22:37`) intact so the degraded window (`T22:13`–`T22:27`) falls within the past 60 minutes in UTC. +The timestamps are fixed to `2026-07-02`, which is in the past. Before running this request, open it in a text editor and replace `2026-07-02` with today's date in `YYYY-MM-DD` format, keeping the time values unchanged. Once you load the data, complete the tutorial within 2 hours to see the full episode lifecycle. ::: ::::{dropdown} Bulk request: 80 synthetic latency events (healthy → degraded → recovered) @@ -230,14 +255,25 @@ POST checkout-service-logs/_bulk ``` :::: - :::: -::::{step} Create the rule +::::: + +## Create the rule [alerting-quick-start-tutorial] + +You'll build a rule that detects when P95 latency for a service exceeds 2 seconds. The rule queries the synthetic data you just loaded, so you can see the breach and recovery cycle play out in real time. + +:::::{stepper} + +::::{step} Open the rule editor Go to **Alerting V2 Preview** using the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). From the rules list, select the option to create a new rule. When the rule creation panel opens, select **Create ES|QL rule** to open the rule authoring flyout. -1. Paste the following {{esql}} query into the **Query sandbox**. The query computes P95 latency per service, assigns a severity tier (`critical`, `high`, or `low`) based on the result, and returns only rows where P95 exceeds 2000 ms. An empty result means no breach. +:::: + +::::{step} Write and test the detection query + +1. Paste the following {{esql}} query into the **Query sandbox**. It computes the 95th percentile latency per service, assigns a severity label based on the result, and filters to show only services where P95 exceeds 2 seconds. Each pipe (`|`) passes the output of one step to the next. ```esql FROM checkout-service-logs @@ -251,46 +287,68 @@ Go to **Alerting V2 Preview** using the [global search field](/explore-analyze/f ``` :::{note} - Do not add a `WHERE @timestamp` clause to this query. Both the query sandbox and the rule executor automatically inject the time-window filter based on the date range you select in the sandbox or the rule's schedule and lookback once it's running. + You don't need to add a `WHERE @timestamp` clause to this query. Both the query sandbox and the rule executor automatically inject the time-window filter based on the date range you select in the sandbox or the rule's schedule and lookback once it's running. ::: -2. Set the sandbox date range to **Last 1 hour** and run the query. This preset gives comfortable coverage of the full dataset without being wide enough to pull in data from a previous run-through. +2. Set the sandbox date range to **Last 1 hour** and run the query. This preset gives comfortable coverage of the full dataset without pulling in data from a previous run. + +3. Confirm the query results. You should see one row for `service.name: checkout` with `p95_latency_ms` above 2000 and `severity: high` or `critical`. -3. Confirm the query results. You should see one row for `service.name: checkout` with `p95_latency_ms` above 2000 and `severity: high` or `critical`. When you narrow the range to cover only the healthy periods before or after the degraded window, the row disappears. P95 drops below the threshold, which is the `no_breach` recovery condition. + You can also use the sandbox to preview what recovery looks like. If you narrow the range to a healthy window (before `22:13` or after `22:28`), the row disappears. No rows means no breach, and when a scheduled evaluation returns the same, the episode closes. You'll configure this behavior in the **Recovery Condition** step. -4. When the results look correct, select **Apply changes** to populate the rule form, then select **Next**. +4. Select **Apply changes** to populate the rule form, then select **Next**. :::{note} The sandbox time controls set the preview range only. They don't carry over to the rule's schedule or lookback window once the rule is running. ::: -5. Complete the **Alert Condition** step (pane 1 of 4). The query you applied from the sandbox auto-fills **Mode**, **Time field**, and **Group fields**. Set the remaining fields, then select **Next**: +:::: + +::::{step} Configure the alert condition - - Under **Alert delay**, select **Breaches** and set the count to `2`. This requires the breach to persist across 2 consecutive evaluations before the episode moves to `active`. - - Set **Schedule** to every `5` minutes. - - Set **Lookback Window** to the last `2` hours. This ensures the rule can reach the pre-loaded sample data regardless of when you complete the tutorial. A shorter lookback would only work if the data timestamps fell within the last few minutes. +The query you applied from the sandbox auto-fills **Mode**, **Time field**, and **Group fields**. Set the remaining fields, then select **Next**: -6. On the **Recovery Condition** step, confirm the defaults, then select **Next**: +- Set **Alert delay** to **Breaches: 2**. The breach must persist across 2 consecutive evaluations before the episode moves to `active`. +- Set **Schedule** to every `5` minutes. +- Set **Lookback Window** to the last `2` hours. This ensures the rule can reach the pre-loaded sample data regardless of when you complete the tutorial. - - **Recovery**: `Default recovery` - - **Recovery delay**: `Immediate` (No delay, recovers on first non-breach) +:::: + +::::{step} Configure the recovery condition + +Confirm the defaults, then select **Next**: - These defaults produce the automatic recovery behavior this tutorial demonstrates: the episode closes as soon as a scheduled run returns no breaching rows. +- **Recovery**: `Default recovery` +- **Recovery delay**: `Immediate` (no delay, recovers on first non-breach) + +These defaults produce the automatic recovery behavior this tutorial demonstrates: the episode closes as soon as a scheduled run returns no breaching rows. + +:::: -7. On the **Details & Artifacts** step, enter the following, then select **Next**: +::::{step} Name and save the rule + +1. On the **Details & Artifacts** step, enter the following, then select **Next**: - **Name**: Checkout Service Latency - - **Description**: `Detects when P95 latency for the checkout service exceeds 2 seconds. Groups by service name and assigns severity: critical at 4000 ms, high at 2000 ms.` + - **Description**: `Detects when P95 latency for the checkout service exceeds 2 seconds. Groups by service name and assigns severity: critical at 4 seconds, high at 2 seconds.` -8. On the **Actions** step, do not create an action policy (rules can run without notifications or actions setup). Select **Create rule** to create and enable the rule. +2. On the **Actions** step, do not create an action policy (rules can run without notifications or actions setup). Select **Create rule** to create and enable the rule. :::: -::::{step} Confirm the rule is evaluating +::::: + +## Confirm the rule is evaluating [alerting-quick-start-confirm] + +The sandbox showed that your query *can* find a breach. This step checks that the rule is actually running on schedule and recording results. Every evaluation, whether it finds a breach or not, writes a document to `.rule-events`, giving you a queryable audit trail of what the rule found and how the episode is progressing. + +:::{note} +The key thing to watch here is `episode.status`. Because you set **Alert delay** to 2 consecutive breaches, the episode starts in `pending` and only moves to `active` once the breach persists across a second evaluation. You can't see this in the sandbox, which only reflects a single run. +::: 1. Open Discover and switch to {{esql}} mode. -2. Set the date range to **Today** or **Last 1 hour**. The default "Last 15 minutes" is often too narrow to catch the first evaluation. +2. Set the date range to **Today** or **Last 1 hour**. The default **Last 15 minutes** is often too narrow to catch the first evaluation. 3. Wait one schedule interval (5 minutes), then run the following query. Replace `` with the ID from the rule's detail page URL. @@ -312,16 +370,16 @@ Go to **Alerting V2 Preview** using the [global search field](/explore-analyze/f | `@timestamp` | A recent timestamp confirming the rule has run | | `status` | `breached` when the query found rows above the threshold; `no_breach` when it found none | | `episode.status` | `pending` for the first two consecutive breaching runs; `active` once the breach persists | - | `data.service.name` | `checkout` — confirms the grouping field was captured | + | `data.service.name` | `checkout`, confirming the grouping field was captured | | `data.severity` | `high` or `critical` depending on the P95 value in the evaluated window | -:::: +## Observe the episode lifecycle [alerting-quick-start-lifecycle] -::::{step} Observe the episode lifecycle +With the rule running, you'll watch the full alert lifecycle play out: the episode opens once the breach persists across consecutive evaluations, stays active while the degraded data is in the lookback window, and closes automatically when no breaching data remains in the lookback window. -1. As the rule continues to run every 5 minutes, its lookback window slides forward in time. Once the degraded data at `22:13`–`22:27` is no longer within the 2-hour window, the rule returns no breach and the episode recovers automatically. +As the rule runs every 5 minutes, its lookback window advances. Once no breaching data falls within the 2-hour window, the rule returns no breach and the episode recovers automatically. -2. Run the following in Discover to track the episode: +1. Run the following in Discover to track the episode. It groups results by episode ID, status, and service name, and returns the most recent timestamp for each — giving you a snapshot of where each episode currently stands. ```esql FROM .rule-events @@ -330,27 +388,12 @@ Go to **Alerting V2 Preview** using the [global search field](/explore-analyze/f | SORT latest DESC ``` -3. Confirm the episode moves from `active` to `inactive` without any manual intervention. This is the `no_breach` recovery strategy in action. +2. Confirm the episode moves from `active` to `inactive` without any manual intervention. This is the `no_breach` recovery strategy in action. -:::: - -::::: +## Key concepts [alerting-quick-start-concepts] -## Key concepts demonstrated - -- **Rules**: Run an {{esql}} query on a schedule and detect when the results meet a condition. Each run computes P95 latency over the lookback window and finds a breach when the result exceeds 2000 ms. -- **Severity tiers**: The `CASE()` expression assigns `high` or `critical` based on the P95 value. These values are stored in `.rule-events` as `data.severity` and are queryable from Discover. +- **Rules**: Run an {{esql}} query on a schedule and detect when the results meet a condition. Each run computes P95 latency over the lookback window and finds a breach when the result exceeds 2000 ms (2 seconds). +- **Severity tiers**: The `CASE()` expression assigns `high` or `critical` based on the P95 value (`high` at 2 seconds, `critical` at 4 seconds). These values are stored in `.rule-events` as `data.severity` and are queryable from Discover. - **Episode lifecycle**: Episodes don't open on the first breach. With **Alert delay** set to **Breaches: 2**, the condition must persist for two consecutive evaluations before the episode moves to `active`. This filters out transient spikes. - **Automatic recovery**: With **Recovery** set to **Default recovery**, the episode closes as soon as a scheduled run returns no breaching rows. No separate recovery query or manual step was required. - **Rule events**: Every evaluation writes a document to `.rule-events`, giving you a full queryable history of what the rule found, when the episode opened, and when it recovered. - - - - diff --git a/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md b/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md index d886efa787..9591132516 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md @@ -6,12 +6,19 @@ applies_to: products: - id: kibana - id: cloud-serverless -description: "Enable and disable the experimental alerting system in Kibana: turn on the alerting:v2:enabled advanced setting, confirm the system is accessible, and understand what happens when the setting is turned off." +description: "What you need before using the experimental alerting system in Kibana: license requirements, connectors, data, and space selection. Also covers how to turn the system on and off using the alerting:v2:enabled advanced setting." --- # Set up the {{alerting-v2-system}} [alerting-setup] -This page explains how to enable the {{alerting-v2-system}} in your space, confirm it's accessible, and turn it off when needed. Enabling and turning off the system requires a {{kib}} administrator. Confirming accessibility can be done by any user with space access. +This page covers what you need before using the {{alerting-v2-system}}, and how to turn it on and off in your space. + +## Requirements [alerting-setup-requirements] + +- **Data in Elasticsearch**: Rules can only detect conditions in data that already exists. Make sure the indices or data streams your rules will query are populated before creating rules. +- **A space selected**: Rules, action policies, and the privileges that control them are all space-scoped. Decide which space you'll work in before setting things up. +- **Connectors configured** (required for notifications): Action policies send notifications through workflows, which require at least one [connector](/deploy-manage/manage-connectors.md), for example, Slack, email, or PagerDuty. +- **Enterprise license** (Stack deployments only, required for notifications): Workflows-based notifications require an Enterprise license. Rules and alert episodes work on any tier. {{serverless-short}} has no license restriction. ## Turn on the system [alerting-setup-turn-on] @@ -21,9 +28,7 @@ The {{alerting-v2-system}} is controlled by the `alerting:v2:enabled` advanced s :::{tab-item} {{stack}} :sync: stack -**Requirement:** Turning on this setting requires the `kibana_admin` role or equivalent {{stack-manage-app}} access. - -**Steps:** +**Requirement:** `kibana_admin` role or equivalent {{stack-manage-app}} access. 1. Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). 2. Under **Global settings**, toggle on **alerting:v2:enabled**. @@ -32,9 +37,7 @@ The {{alerting-v2-system}} is controlled by the `alerting:v2:enabled` advanced s :::{tab-item} {{serverless-short}} :sync: serverless -**Requirement:** Turning on this setting requires the `admin` project role. - -**Steps:** +**Requirement:** `admin` project role. {{serverless-short}} has no Global Advanced Settings UI. Use Dev Tools to call the global settings API: @@ -81,12 +84,4 @@ Turning the setting back on resumes execution. Turning it off does not delete an After turning on the system, configure role access so your team can use it: -- **[Configure access](configure-access.md):** Create or update a role with access to the {{alerting-v2-system}} features and the data streams they write to. Users need at minimum **Rules: All** to create rules and `read` index access on `.rule-events` to query rule output in Discover. - - - +- **[Configure access](configure-access.md):** Create or update a role with access to the {{alerting-v2-system}} features and the data streams they write to. Users need at minimum **Rules: All** to create rules. Granting **Alerts: Read** gives a role Kibana triage access and automatic Elasticsearch `read` access to `.rule-events` and `.alert-actions`, with no separate index privilege needed. \ No newline at end of file From 44c567e663625e28a594e554fd47026387d689f6 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon Date: Sun, 5 Jul 2026 19:49:10 -0400 Subject: [PATCH 2/2] add applies to --- .../get-started/setup.md | 52 +++++++++++++------ 1 file changed, 36 insertions(+), 16 deletions(-) diff --git a/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md b/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md index 9591132516..2946b77a9a 100644 --- a/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md +++ b/explore-analyze/alerting/kibana-alerting-experimental/get-started/setup.md @@ -18,28 +18,34 @@ This page covers what you need before using the {{alerting-v2-system}}, and how - **Data in Elasticsearch**: Rules can only detect conditions in data that already exists. Make sure the indices or data streams your rules will query are populated before creating rules. - **A space selected**: Rules, action policies, and the privileges that control them are all space-scoped. Decide which space you'll work in before setting things up. - **Connectors configured** (required for notifications): Action policies send notifications through workflows, which require at least one [connector](/deploy-manage/manage-connectors.md), for example, Slack, email, or PagerDuty. -- **Enterprise license** (Stack deployments only, required for notifications): Workflows-based notifications require an Enterprise license. Rules and alert episodes work on any tier. {{serverless-short}} has no license restriction. +- **Enterprise license** (Stack deployments only, required for notifications): Workflows-based notifications require an Enterprise license. Rules and alert episodes work on any tier.{applies_to}`stack: ga 9.5+` ## Turn on the system [alerting-setup-turn-on] The {{alerting-v2-system}} is controlled by the `alerting:v2:enabled` advanced setting in {{kib}}. This setting is off by default. Turn it on to make the UIs for {{alerting-v2-system}} features available in your space. -::::{tab-set} -:::{tab-item} {{stack}} -:sync: stack +::::{applies-switch} +:::{applies-item} stack: experimental 9.5+ -**Requirement:** `kibana_admin` role or equivalent {{stack-manage-app}} access. +**Role requirements** + +You must have the `kibana_admin` role or equivalent {{stack-manage-app}} access to turn on this setting. + +**Steps** 1. Go to the **Advanced Settings** menu using the navigation menu or the [global search field](/explore-analyze/find-and-organize/find-apps-and-objects.md). 2. Under **Global settings**, toggle on **alerting:v2:enabled**. ::: -:::{tab-item} {{serverless-short}} -:sync: serverless +:::{applies-item} serverless: experimental + +**Role requirements** -**Requirement:** `admin` project role. +You must have the `admin` project role to turn on this setting. -{{serverless-short}} has no Global Advanced Settings UI. Use Dev Tools to call the global settings API: +**Step** + +{{serverless-short}} has no Global Advanced Settings UI, so use Dev Tools to call the global settings API: ```json POST kbn:/internal/kibana/global_settings @@ -67,16 +73,30 @@ If the menu item doesn't appear immediately, refresh the page and search again. ## Turn off the system [alerting-setup-turn-off] -To turn off the {{alerting-v2-system}}, set `alerting:v2:enabled` to `false`: +To turn off the {{alerting-v2-system}}, set `alerting:v2:enabled` to `false`. -- **{{stack}}:** Go to the same **Advanced Settings** page and toggle off **alerting:v2:enabled**. -- **{{serverless-short}}:** Call the global settings API with `"alerting:v2:enabled": false`. +::::{applies-switch} +:::{applies-item} stack: experimental 9.5+ -When the setting is off: +Go to the **Advanced Settings** page and toggle off **alerting:v2:enabled**. +::: + +:::{applies-item} serverless: experimental + +Use Dev Tools to call the global settings API: + +```json +POST kbn:/internal/kibana/global_settings +{ + "changes": { + "alerting:v2:enabled": false + } +} +``` +::: +:::: -- Rule and action policy execution stops. -- The APIs and UI are hidden. -- Existing rules and action policies are paused. +When the setting is off, rule and action policy execution stops, the APIs and UI are hidden, and existing rules and action policies are paused. Turning the setting back on resumes execution. Turning it off does not delete any data. Your rules and action policies remain as {{kib}} saved objects, and existing documents in `.rule-events` and `.alert-actions` are preserved.