[Alerting V2][Serverless & 9.5][M2] Setup changes from July 2 (#7181)

## Summary

Updates `setup-alerting.md` and `alerting-privileges.md` for the
experimental alerting system with the confirmed M2 enablement procedure
and RBAC privilege requirements. Following the tech preview principle of
accuracy over comprehensiveness, additions focus on stable behavior —
how to turn the feature on, what the setting controls, what happens when
it's turned off, and which privilege controls which action.

---

## Content changes

### RBAC privilege requirements (closes #6043)

Kibana PRs #270574 and #272440 introduced four standalone privileges
under the **Alerting** category in Kibana role management: **Rules**,
**Alerts**, **Action Policies**, and **Execution history**. Each
privilege is independent; holding one does not grant another.

**`alerting-privileges.md`** — Replaced all four `[CONTENT NEEDED]`
placeholders with full privilege documentation:

* **Manage rules** — privilege table (All: create, edit, delete, enable,
and disable rules; Read: view rules) with guidance on when each level
applies.
* **Manage action policies** — privilege table (All: create, update,
delete, snooze, and unsnooze; Read: view) with an explicit callout that
**Rules: All** does not include action policy management.
* **Manage alerts** — privilege table (All: acknowledge, snooze, assign,
tag, activate, and deactivate alert episodes; Read: view) with triage
use case.
* **View execution history** — new section documenting that both All and
Read grant identical read-only access. There is no write surface for
execution history.
* **Query alert data in Discover** — Kibana **Discover: Read** access
plus `read` index privilege on `.rule-events` and `.alert-actions`, with
a note to use a custom role for hidden system data streams.

Also updated the opening paragraph from "control which users can" to
"control what you can do with" to use second-person voice, consistent
with the style applied across the other sections.

What was omitted: role management UI steps (subject to change before
GA), specific custom role configuration procedures, and any
serverless-specific privilege differences not yet confirmed.

---

### Enable the experimental alerting system (closes
elastic/docs-content-internal#1113)

Kibana PR #272365 consolidated experimental alerting feature flags under
a single `alerting:v2:enabled` advanced setting.

**`setup-alerting.md`** — Replaced the "CONTENT NEEDED" placeholder in
the **Enable the experimental alerting system** section with the
confirmed M2 enablement procedure:

* **Stack path**: Stack Management → Advanced Settings → Global settings
→ toggle on **alerting:v2:enabled**.
* **Serverless path**: No Global Advanced Settings UI exists in
serverless. Documents the `POST kbn:/internal/kibana/global_settings`
Dev Tools call with a note that the endpoint is internal and has no
public equivalent.
* **Disabled-state behavior**: When the setting is off, rule and
dispatcher execution stops, the APIs and UIs are hidden, and existing
rules and action policies are paused. Turning it back on resumes
execution. Disabling does not delete any data.

What was omitted: the `kibana.yml` prerequisite (configured by default;
no action needed), non-YAML UI steps for serverless (no UI exists), and
the internal Kibana issue tracking the default enablement
(elastic/rna-program#606).

### Stale CONTENT NEEDED comment removed

**`setup-alerting.md`** — Removed the "CONTENT NEEDED" comment from the
**Where rule events are stored** section. The comment flagged
uncertainty about whether `.rule-events` and `.alert-actions` would be
the intended query surface for end users. This is now confirmed: both
data streams are the documented query surface, as reflected in the
[Query alert history in
Discover](https://docs-v3-preview.elastic.dev/elastic/docs-content/pull/6527/explore-analyze/alerting/kibana-alerting-experimental/alerts/query-alerts-and-signals-in-discover)
page in PR #6527.

### Stale TODO paths fixed

**`setup-alerting.md`** — Fixed two broken cross-reference paths in the
commented-out **Next steps** links:

* `rules/author-rules.md` → `rules/create-a-rule.md`. The
`author-rules.md` page was deleted in PR #6523; `create-a-rule.md` is
the new entry point to the rules section.
* `notifications/create-configure-action-policy.md` →
`action-policies/create-configure-action-policy.md`. The directory
structure for action policies changed in PR #6525.
* Updated "Detect or Alert mode" → "Signal or Alert mode" to match the
renamed rule kind label from PR #6523.

### Opening intro updated

Removed the "Set up is part of the experimental alerting system in
Kibana" anchor sentence and split the opening paragraph in two for
scannability. Updated "need to be enabled" to "must be enabled" for
imperative clarity.

---

## Generative AI disclosure

1. Did you use a generative AI (GenAI) tool to assist in creating this
contribution?
* Yes — Cursor + Claude
* No

Author: nastasha-solomon

docset.yml

@@ -125,6 +125,8 @@ subs:
   maint-windows-cap:   "Maintenance windows"
   alerting-v2:   "experimental alerting features"
   alerting-v2-cap:   "Experimental alerting features"
+  alerting-v2-system:   "experimental alerting system"
+  alerting-v2-system-cap:   "Experimental alerting system"
   custom-roles-app:   "Custom Roles"
   data-source:   "data view"
   data-sources:   "data views"

explore-analyze/alerting/kibana-alerting-experimental/alerting-privileges.md

@@ -0,0 +1,18 @@
+---
+navigation_title: Get started
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+  - id: cloud-serverless
+description: "Enable the experimental alerting system in Kibana, configure role access, and create your first rule."
+---
+
+# 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.

explore-analyze/alerting/kibana-alerting-experimental/get-started.md

@@ -0,0 +1,124 @@
+---
+navigation_title: Configure access
+applies_to:
+  stack: experimental 9.5+
+  serverless: experimental
+products:
+  - id: kibana
+  - id: cloud-serverless
+description: "Privilege requirements for Kibana experimental alerting features: which Kibana feature privileges and Elasticsearch index privileges each role needs to manage rules, action policies, alerts, and query rule events and alert actions."
+---
+
+# Configure access to the {{alerting-v2-system}} [alerting-privileges]
+
+To use the {{alerting-v2-system}}, your role needs specific {{kib}} feature privileges and, if you're querying alerting data in Discover, {{es}} index privileges. [Create or update a role](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) and add the privileges that match the tasks your team performs.
+
+This page is organized by user activity. Most privileges are set under the **Alerting** category in {{kib}} role management. Exceptions are noted in each section.
+
+:::{note}
+This page covers access to the {{alerting-v2-system}} features and data. Depending on how your rules and notifications are configured, your role might also need `read` index privileges on the indices their rules query and **Actions and Connectors: All** (under **Management**) to create or edit workflow connectors. Refer to [{{kib}} role management](/deploy-manage/users-roles/cluster-or-deployment-auth/kibana-role-management.md) for guidance on building roles that combine privileges across features.
+:::
+
+## Quick reference [alerting-quick-reference]
+
+The following table shows the minimum privileges required for each activity. Higher privilege levels include the access shown here. Refer to the following sections for the full breakdown.
+
+| To... | Minimum required |
+|---|---|
+| Author and manage rules | **Rules: All** (under **Alerting**) |
+| 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 |
+
+## Author and monitor rules [alerting-authoring-monitoring-privileges]
+
+These privileges control who can create rules and review their execution history.
+
+### Rules [alerting-manage-rules-privileges]
+
+The **Rules** privilege controls who can create and manage rules.
+
+| Level | What you can do |
+|---|---|
+| **All** | Create, edit, delete, enable, and turn off rules |
+| **Read** | View rules and their configuration |
+
+:::{note}
+**Rules: All** also grants access to the **Alerts** menu in Discover, which routes rule creation to the {{alerting-v2-system}} rule form when the system is enabled in your space.
+:::
+
+### View rule execution history [alerting-execution-history-privileges]
+
+The **Execution history** privilege controls who can view rule execution history. Execution history is read-only; both **All** and **Read** grant the same access. There is no write surface for execution history.
+
+| Level | What you can do |
+|---|---|
+| **All** | View rule execution history |
+| **Read** | View rule execution history |
+
+## Triaging alerts [alerting-triage-privileges]
+
+The **Alerts** privilege controls who can take triage actions on alert episodes.
+
+| Level | What you can do |
+|---|---|
+| **All** | Acknowledge, snooze, assign, tag, activate, and deactivate alert episodes |
+| **Read** | View alert episodes |
+
+## Configure notifications [alerting-notifications-privileges]
+
+These privileges control who can set up the action policies and workflows that route alert episode notifications.
+
+### Action policies [action-policy-management]
+
+The **Action Policies** privilege controls who can manage the policies that route alert episode notifications.
+
+| Level | What you can do |
+|---|---|
+| **All** | Create, update, delete, snooze, and unsnooze action policies |
+| **Read** | View action policies |
+
+:::{note}
+Having **Action Policies: All** does not include the ability to create or edit rules. Add **Rules: All** if rule management is also required.
+:::
+
+### Workflows [alerting-workflows-access]
+
+Action policies route notifications through workflows. The **Workflows** privilege is set under **Analytics > Workflows** in {{kib}} role management. To create or manage action policies, your role also needs access to the workflows they reference.
+
+| Level | What you can do |
+|---|---|
+| **All** | Create and edit workflows; view and select existing workflows in action policies |
+| **Read** | View and select existing workflows in action policies |
+
+## Query rule output and episode data [alerting-data-investigation-privileges]
+
+The {{alerting-v2-system}} writes rule output and episode data to three queryable data sources. To query them in Discover using {{esql}}, your role needs {{kib}} feature access and {{es}} index access.
+
+### {{kib}} feature access
+
+Set Discover privileges under **Analytics > Discover** in {{kib}} role management.
+
+| Level | What you can do |
+|---|---|
+| **All** | Run {{esql}} queries against rule events, alert actions, and execution history in Discover |
+| **Read** | Run {{esql}} queries against rule events, alert actions, and execution history in Discover |
+
+Both levels grant the same query access. There is no write surface for any of these data sources in Discover.
+
+### {{es}} index access
+
+Each data source requires a separate `read` index privilege:
+
+| Data source | What it stores | Required privilege |
+|---|---|---|
+| `.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` |
+
+Because `.rule-events` and `.alert-actions` are hidden system data streams, request access through a custom role with the appropriate index privileges.
+
+<!-- TODO: Uncomment when PR #6527 (alerts) is merged, and add as a link in the note under the Rules section:
+For step-by-step instructions, refer to [Create a rule from Discover](../alerts/query-alerts-and-signals-in-discover.md).
+-->