How to set up RBAC for Monitors

Docs > Monitors > Monitor Guides > How to set up RBAC for Monitors

Overview

Monitors alert your teams to potential issues with your systems. Making sure only authorized users can edit your monitors prevents accidental changes in your monitors’ configurations.

Safely manage your monitors by restricting edit permissions for each individual monitor to specific roles.

Set up roles

For more information about default and custom roles, how to create custom roles, assign permissions to roles, and assign roles to users, see Role Based Access Control.

Restrict access to monitors

Navigate to the monitor editing page by creating a new monitor or editing an existing one.
At the bottom of the form, specify which roles, in addition to the creator, are allowed to edit the monitor.

For more information, see Monitors Permissions.

Use the List Roles API endpoint to get the list of roles and their ids.

curl --request GET 'https://api.datadoghq.com/api/v2/roles' \
--header 'DD-API-KEY: <DD-API-KEY>' \
--header 'DD-APPLICATION-KEY: <DD-APPLICATION-KEY>'

{
    "meta": {
        "page": {
            "total_filtered_count": 4,
            "total_count": 4
        }
    },
    "data": [
        {
            "type": "roles",
            "id": "89f5dh86-e470-11f8-e26f-4h656a27d9cc",
            "attributes": {
                "name": "Corp IT Eng - User Onboarding",
                "created_at": "2018-11-05T21:19:54.105604+00:00",
                "modified_at": "2018-11-05T21:19:54.105604+00:00",
                "user_count": 4
            },
            "relationships": {
                "permissions": {
                    "data": [
                        {
                            "type": "permissions",
                            "id": "984d2rt4-d5b4-13e8-a5yf-a7f560d33029"
                        },
                        ...
                    ]
                }
            }
        },
        ...
    ]
}

Use the Create or Edit a monitor API endpoint and the restricted_roles parameter to restrict monitor editing to a specific set of roles and to the monitor’s creator.

Note: You can specify one or multiple role UUIDs. Setting restricted_roles to null allows monitor editing for all users with Monitor Write permissions.

curl --location --request POST 'https://api.datadoghq.com/api/v1/monitor' \
--header 'Content-Type: application/json' \
--header 'DD-API-KEY: <DD-API-KEY>' \
--header 'DD-APPLICATION-KEY: <DD-APPLICATION-KEY>' \
--data-raw '{
  "message": "You may need to add web hosts if this is consistently high.",
  "name": "Bytes received on host0",
  "options": {
    "no_data_timeframe": 20,
    "notify_no_data": true
  },
  "query": "avg(last_5m):sum:system.net.bytes_rcvd{host:host0} \u003e 100",
  "tags": [
    "app:webserver",
    "frontend"
  ],
  "type": "query alert",
  "restricted_roles": ["89f5dh86-e470-11f8-e26f-4h656a27d9cc"]
}'

For more information, see Roles and Monitors API Reference .

Migrate monitors from locked to restricted roles

Before Datadog released the feature allowing restriction of monitor editing to specific roles, monitors could be locked. Only the creator and users with the Datadog Admin Role can edit a locked monitor.

Locked monitors are deprecated and are no longer supported. Instead, use the role restriction option, which gives you more flexibility to define which users are allowed to edit monitors.

The sections below describe how to migrate from the locked mechanism to restricted roles, depending on the way you manage your monitors.

API

The locked parameter corresponding to the above mentioned locking mechanism is no longer supported. This means you must update the definition of your monitors managed through API or Terraform to stop using locked and start using restricted_roles (parameter attached with the new role restriction option).

For more information on how to update your monitors’ definitions, see Edit a monitor API endpoint and Monitor API Options.

UI

All new monitors created from the UI use the restricted_roles parameter. All monitors also display the role restriction option regardless of the underlying mechanism:

Datadog updates existing monitor definitions from the old locked mechanism to the new role restriction one whenever a monitor is saved.

Below are some instructions to help you determine how to proceed in case you need to save a monitor that is using the locked mechanism.

Locked monitors (`locked:true`) edited by creator or user with Datadog Admin Role

You are a user with the Datadog Admin Role or are the creator of the monitor. You edit a locked monitor and see the following warning:

This monitor is using the locked attribute: only its creator and admins can edit it. locked is deprecated in favor of restricted_roles. On save, the monitor will be automatically updated to use a restricted_roles attribute set to all roles with Admin permissions. 
If there is no specific change you want to apply to this monitor's permissions, click Save. If you want to update this monitor's permissions, read this doc.

On save, your monitor’s definition will be updated to all roles with Admin permissions. You have different ways to handle this warning depending on the changes you are willing to make to your monitor:

1. You do not want to change anything about your monitor permissions

Save the monitor. Datadog automatically migrates the monitor from the locked mechanism to restricted roles. Any other updates you made to your monitor, such as threshold update or message, are saved at the same time.

Clicking Save without making any changes also performs the update for your monitor.

2. You want to allow all users to edit this monitor

Save the monitor, causing Datadog to migrate it to restricted roles. Reopen the editing page. In the Restrict editing of this monitor to dropdown menu, remove all roles. Click Save a second time.

3. You want your monitor to be restricted to some roles, but not to all roles with Admin permissions

In the Restrict editing of this monitor to dropdown menu, select the roles that can modify this monitor. Save the monitor. Monitor is restricted only to the roles you selected.

Locked monitors (`locked:true`) edited by non creator or user without Datadog Admin Role

You are a user without the Datadog Admin Role and are not the creator of the monitor. You edit a locked monitor and see the following warning:

This monitor is locked: only its creator and admins can edit it. Read more here.

This monitor is locked. Reach out to a user with the Datadog Admin Role or to the creator of the monitor and ask them to add one of your roles to the monitor role restrictions. Your admin will have to follow steps two or three above for locked monitors.

Note: The discrepancy you see between the warning and the option is expected. The warning reflects the current state of the monitor that is using the locked parameter. The option reflects the role restriction option your monitor will be updated to once a user with the Datadog Admin Role or the monitor’s creator edits and saves it. Once the monitor is saved, the warning disappears and the appropriate restricted roles populate the dropdown.

Non locked monitors (`locked:false`, `locked:null`, undefined `locked`)

You edit a non locked monitor and see the following option:

You have different ways to handle this option depending on the changes you are willing to make on your monitor:

1. You do not want to change anything about your monitor permissions

Clicking Save without making any changes also performs the update for your monitor.

2. You want to restrict your monitor to some roles

In the Restrict editing of this monitor to dropdown menu, select the roles that can modify this monitor. Save the monitor. Monitor is restricted to the roles you selected.