From ced5497ba1b8eb2bd019e863eb1c8752ee66e807 Mon Sep 17 00:00:00 2001 From: Yuri Tseretyan Date: Tue, 15 Oct 2024 10:16:15 -0400 Subject: [PATCH] Docs: Update alerting notifications documentation (#93944) * add new permissions and fixed roles * Apply suggestions from code review Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> * address comments * add actions to complete list * fmt --------- Co-authored-by: brendamuir <100768211+brendamuir@users.noreply.github.com> --- .../custom-role-actions-scopes/index.md | 20 +++++++++++++ .../alerting/set-up/configure-rbac/_index.md | 28 +++++++++++++++++++ .../configure-rbac/access-roles/index.md | 16 +++++++++++ .../alerting/set-up/configure-roles/index.md | 27 ++++++++++++++++++ 4 files changed, 91 insertions(+) diff --git a/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md b/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md index 7f3f60f1c96..1276f049da2 100644 --- a/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md +++ b/docs/sources/administration/roles-and-permissions/access-control/custom-role-actions-scopes/index.md @@ -199,6 +199,26 @@ The following list contains role-based access control actions used by Grafana Ad | `grafana‑adaptive‑metrics‑app.exemptions:read` | None | Read recommendation exemptions. | | `grafana‑adaptive‑metrics‑app.exemptions:write` | None | Create, update, and delete recommendation exemptions. | +### Grafana Alerting Notification action definitions + +To enable these permissions, enable the `alertingApiServer` feature toggle. + +| Action | Applicable scopes | Description | +| -------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------- | +| `alert.notifications.receivers:read` | `receivers:*`
`receivers:uid:*` | Read contact points. None | +| `alert.notifications.receivers.secrets:read` | `receivers:*`
`receivers:uid:*` | Export contact points with decrypted secrets.None | +| `alert.notifications.receivers:create` | None | Create a new contact points. The creator is automatically granted full access to the created contact point.None | +| `alert.notifications.receivers:write` | `receivers:*`
`receivers:uid:*` | Update existing contact points.None | +| `alert.notifications.receivers:delete` | `receivers:*`
`receivers:uid:*` | Update and delete existing contact points.None | +| `receivers.permissions:read` | `receivers:*`
`receivers:uid:*` | Read permissions for contact points.None | +| `receivers.permissions:write` | `receivers:*`
`receivers:uid:*` | Manage permissions for contact points.None | +| `alert.notifications.time-intervals:read` | None | Read mute time intervals.None | +| `alert.notifications.time-intervals:write` | None | Create new or update existing mute time intervals.None | +| `alert.notifications.time-intervals:delete` | None | Delete existing time intervals.None | +| `alert.notifications.templates:read` | None | Read templates. | +| `alert.notifications.templates:write` | None | Create new or update existing templates.None | +| `alert.notifications.templates:delete` | None | Delete existing templates.None | + ## Scope definitions The following list contains role-based access control scopes. diff --git a/docs/sources/alerting/set-up/configure-rbac/_index.md b/docs/sources/alerting/set-up/configure-rbac/_index.md index 567b9dd9fab..6a15d86e724 100644 --- a/docs/sources/alerting/set-up/configure-rbac/_index.md +++ b/docs/sources/alerting/set-up/configure-rbac/_index.md @@ -52,4 +52,32 @@ Grafana Alerting has the following permissions. | `alert.provisioning:write` | n/a | Update all Grafana alert rules, notification policies, etc via provisioning API. Permissions to folders and data source are not required. | | `alert.provisioning.provenance:write` | n/a | Set provisioning status for alerting resources. Cannot be used alone. Requires user to have permissions to access resources | +Contact point permissions. To enable these permissions, enable the `alertingApiServer` feature toggle. + +| Action | Applicable scope | Description | +| -------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| `alert.notifications.receivers:read` | `receivers:*`
`receivers:uid:*` | Read contact points. | +| `alert.notifications.receivers.secrets:read` | `receivers:*`
`receivers:uid:*` | Export contact points with decrypted secrets. | +| `alert.notifications.receivers:create` | n/a | Create a new contact points. The creator is automatically granted full access to the created contact point. | +| `alert.notifications.receivers:write` | `receivers:*`
`receivers:uid:*` | Update existing contact points. | +| `alert.notifications.receivers:delete` | `receivers:*`
`receivers:uid:*` | Update and delete existing contact points. | +| `receivers.permissions:read` | `receivers:*`
`receivers:uid:*` | Read permissions for contact points. | +| `receivers.permissions:write` | `receivers:*`
`receivers:uid:*` | Manage permissions for contact points. | + +Mute time interval permissions. To enable these permissions, enable the `alertingApiServer` feature toggle. + +| Action | Applicable scope | Description | +| ------------------------------------------- | ---------------- | -------------------------------------------------- | +| `alert.notifications.time-intervals:read` | n/a | Read mute time intervals. | +| `alert.notifications.time-intervals:write` | n/a | Create new or update existing mute time intervals. | +| `alert.notifications.time-intervals:delete` | n/a | Delete existing time intervals. | + +Notification template permissions. To enable these permissions, enable the `alertingApiServer` feature toggle. + +| Action | Applicable scope | Description | +| -------------------------------------- | ---------------- | ---------------------------------------- | +| `alert.notifications.templates:read` | n/a | Read templates. | +| `alert.notifications.templates:write` | n/a | Create new or update existing templates. | +| `alert.notifications.templates:delete` | n/a | Delete existing templates. | + To help plan your RBAC rollout strategy, refer to [Plan your RBAC rollout strategy](https://grafana.com/docs/grafana/next/administration/roles-and-permissions/access-control/plan-rbac-rollout-strategy/). diff --git a/docs/sources/alerting/set-up/configure-rbac/access-roles/index.md b/docs/sources/alerting/set-up/configure-rbac/access-roles/index.md index 0b06882eb3d..2c9f3efa4db 100644 --- a/docs/sources/alerting/set-up/configure-rbac/access-roles/index.md +++ b/docs/sources/alerting/set-up/configure-rbac/access-roles/index.md @@ -57,12 +57,28 @@ Details of the fixed roles and the access they provide for Grafana Alerting are | Access to alert rules provisioning API: `fixed:alerting.provisioning:writer` | `alert.provisioning:read` and `alert.provisioning:write` | Manage all alert rules, notification policies, contact points, templates, in the organization using the provisioning API. | | Set provisioning status: `fixed:alerting.provisioning.status:writer` | `alert.provisioning.provenance:write` | Set provisioning rules for Alerting resources. Should be used together with other regular roles (Notifications Writer and/or Rules Writer.) | +If you have enabled the `alertingApiServer` feature toggle, an additional set of fixed roles is available. + +| Display name in UI / Fixed role | Permissions | Description | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Contact Point Reader: `fixed:alerting.receivers:reader` | `alert.notifications.receivers:read` for scope `receivers:*` | Read all contact points. | +| Contact Point Creator: `fixed:alerting.receivers:creator` | `alert.notifications.receivers:create` | Create a new contact point. The user is automatically granted full access to the created contact point. | +| Contact Point Writer: `fixed:alerting.receivers:writer` | `alert.notifications.receivers:read`, `alert.notifications.receivers:write`, `alert.notifications.receivers:delete` for scope `receivers:*` and
`alert.notifications.receivers:create` | Create a new contact point and manage all existing contact points. | +| Templates Reader: `fixed:alerting.templates:reader` | `alert.notifications.templates:read` | Read all notification templates. | +| Templates Writer: `fixed:alerting.templates:writer` | `alert.notifications.templates:read`, `alert.notifications.templates:write`, `alert.notifications.templates:delete` | Create new and manage existing notification templates. | +| Time Intervals Reader: `fixed:alerting.time-intervals:reader` | `alert.notifications.time-intervals:read` | Read all time intervals. | +| Time Intervals Writer: `fixed:alerting.time-intervals:writer` | `alert.notifications.time-intervals:read`, `alert.notifications.time-intervals:write`, `alert.notifications.time-intervals:delete` | Create new and manage existing time intervals. | + ## Create custom roles Create custom roles of your own to manage permissions. Custom roles contain unique combinations of permissions, actions and scopes. Create a custom role when basic roles and fixed roles do not meet your permissions requirements. For more information on creating custom roles, refer to [Create custom roles](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/manage-rbac-roles/#create-custom-roles). +{{< admonition type="note" >}} +It is not recommended to create custom roles that include `alerting.notifications.receiver` actions with a scope other than `receivers:*`. The UID used in the scope is not stable and changes whenever a contact point is renamed. +{{< /admonition >}} + ### Examples The following examples give you an idea of how you can combine permissions for Grafana Alerting. diff --git a/docs/sources/alerting/set-up/configure-roles/index.md b/docs/sources/alerting/set-up/configure-roles/index.md index 6acb0734bb2..2d4470018de 100644 --- a/docs/sources/alerting/set-up/configure-roles/index.md +++ b/docs/sources/alerting/set-up/configure-roles/index.md @@ -64,3 +64,30 @@ To manage folder permissions, complete the following steps. 1. Hover your mouse cursor over a folder and click **Go to folder**. 1. Click **Manage permissions** from the Folder actions menu. 1. Update or add permissions as required. + +## Manage access using contact point permissions + +### Before you begin + +- Enable the `alertingApiServer` feature toggle. + +Extend or limit the access provided by a role to contact points by assigning permissions to individual contact point. + +This allows different users, teams, or service accounts to have customized access to read or modify specific contact points. + +Refer to the following table for details on the additional access provided by contact point permissions. + +| Folder permission | Additional Access | +| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| View | View and export contact point as well as select it on the Alert rule edit page | +| Edit | Update or delete the contact point | +| Admin | Same additional access as Edit and manage permissions for the contact point. User should have additional permissions to read users and teams. | + +### Steps + +To contact point permissions, complete the following steps. + +1. In the left-side menu, click **Contact points**. +1. Hover your mouse cursor over a contact point and click **More**. +1. Click **Manage permissions** from the actions menu. +1. Update or add permissions as required.