PMM-9146 Documentation update for LBAC

documentation/docs/admin/roles/access-control/assign_roles.md

@@ -1,11 +1,12 @@
-# Assign roles to users
+# Assign access roles to users
 
 To assign access roles to users:
 {.power-number}
 
-1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option.
+1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option.
 2. Go to **Administration > Users and access > Users**.
+3. Click on the user you want to assign roles to.
+4. From the **Roles** drop-down select the appropriate roles.
+5. Verify the assigned roles appear in the **Access Role** column.
 
-3. Select the **User** you want to assign to a role from the dropdown. You can assign several roles to a user.
-
-    ![!](../../../images/PMM_access_control_select_role.png)
+![PMM Access Control - Assign role](../../../images/lbac/PMM_access_control_select_role.png)

documentation/docs/admin/roles/access-control/create_roles.md

@@ -1,28 +1,34 @@
 
 # Create access roles
 
-Roles are a vital part of Access control. Roles provide users with access to specific, role-based metrics.
+Roles are essential components of PMM's access control system. They allow you to limit users' access to specific metrics based on their responsibilities and permissions.
 
-To create access roles in PMM, do the following:
+## Before you begin
+
+- You must have administrator privileges to create roles. For more information, see [Manage users](../../manage-users/index.md).
+- Access control must be enabled in PMM settings
+
+## Create a new role
+
+To create access roles in PMM:
 {.power-number}
 
-1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option.
+1. From the [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access control** option.
 2. Go to **Administration > Users and access > Access Roles**.
 
-    ![!](../../../images/PMM_access_control_create_role.png)
+    ![PMM Access Control - Create role](../../../images/lbac/PMM_access_control_create_role.png)
 
 3. Click **Create**.
 4. On the **Create role** page, enter the Role name and Role description.
-5. Select the following from the drop-downs for metrics access:
-    - Label
-    - Operator
-    - Value of the label
+5. Configure metrics access by setting label selectors:
+    - select a Label (e.g., "service_name", "environment")
+    - choose an Operator (e.g., "=", "!=", "=~")
+    - enter the Value for the selected label
 
     If you want to add more than one label for a role, click *+* and select the values from the drop-down.
 
     For information on how the Prometheus selectors work, see [Prometheus selectors](https://prometheus.io/docs/prometheus/latest/querying/basics/#time-series-selectors).
 
-6. Click **Create** role.
+6. Review your selections, then click **Create** to finalize the role.
+
 
-!!! note alert alert-primary "Note"
-    To create roles, you must have admin privileges. For more information, see [Manage users](../../manage-users/index.md).

documentation/docs/admin/roles/access-control/enable_access_control.md

@@ -0,0 +1,51 @@
+# Enable access control
+
+Access control in PMM lets you restrict user access to specific metrics and Query Analytics data based on their roles. 
+Choose your preferred method to enable this feature:
+
+=== "Via Docker"
+
+    When deploying PMM Server with Docker, enable access control by passing an environment variable:
+
+    ```sh
+    docker run -d \
+      --name pmm-server \
+      -p 443:8443 \
+      -e PMM_ENABLE_ACCESS_CONTROL=1 \
+      percona/pmm-server:latest
+    ```
+
+=== "Via Docker Compose"
+
+    For Docker Compose deployments, add the environment variable to your `docker-compose.yml` file:
+
+    ```yaml
+    services:
+      pmm-server:
+        image: percona/pmm-server:latest
+        ports:
+          - "443:8443"
+        environment:
+          - PMM_ENABLE_ACCESS_CONTROL=1
+        volumes:
+          - pmm-data:/srv
+    ```
+
+=== "Via user interface"
+
+    To enable access control from the PMM web interface:
+    {.power-number}
+
+    1. Log in to PMM with an administrator account.
+    2. From the main menu, go to **PMM Configuration > Settings > Advanced Settings > Access Control**.
+    3. Toggle the <i class="uil uil-toggle-off"></i> toggle.
+    4. Click **Apply changes** to save your settings.
+
+## After enabling access control
+
+Once access control is enabled:
+
+- All existing users will have full access until you assign specific roles.
+- [Create access roles](../access-control/create_roles.md) for different user types.
+- [Assign the new roles](../index.md) to your PMM users.
+- Test that restrictions work as expected.

documentation/docs/admin/roles/access-control/intro.md

@@ -1,13 +1,49 @@
-# About access control in PMM
+# About label based access control (LBAC) in PMM
 
-!!! caution alert alert-warning "Caution"
-    PMM Access Control is currently in [technical preview](../../../reference/glossary.md#technical-preview) and is subject to change. We recommend that early adopters use this feature for testing purposes only.
+Access control in PMM allows you to manage access to data. By using access control you can restrict access to monitoring metrics and Query Analytics data. 
 
-Access control in PMM allows you to manage who has access to individual Prometheus (Victoria Metrics)  metrics based on **labels**. Thus, access management provides a standardized way of granting, changing, and revoking access to metrics based on the role assigned to the users.
+This is particularly important in environments where sensitive data is involved, and it helps ensure that only authorized users can access specific information, which is crucial for maintaining security and compliance.
 
-The following topics are covered as part of access control:
+## How LBAC works
+PMM uses Prometheus label selectors to control access to metrics and Query Analytics data. 
 
-- [Configure access control](config_access_cntrl.md)
-- [Labels for access control](labels.md)
-- [Create access roles](create_roles.md)
-- [Use case](usecase.md)
+Here's how LBAC works:
+{.power-number}
+
+1. Create roles with label selectors. For example `environment=prod` for a specific environment or `service_type=mysql` for specific databases.
+2. Assign roles to users based on their responsibilities.
+3. Users see only the metrics and (Query Analytics) QAN data that match their role's label selectors.
+
+## Key benefits
+
+- Granular permissions: Restrict access to specific services, environments, or regions.
+- Enhanced security: Prevent unauthorized access to sensitive database metrics and query data.
+- Compliance support: Meet regulatory requirements for data access control.
+- Team-specific views: Allow teams to focus only on their relevant systems and queries.
+- Simplified management: Manage access through roles instead of individual user permissions.
+
+## Example scenarios
+
+| User type | Possible role configuration | What they can see |
+|-----------|---------------------------|------------------|
+| DBA team lead | All services across environments | Complete monitoring data for all databases and queries |
+| MySQL administrators | `service_type=mysql` | Only MySQL-related metrics and queries |
+| Production support | `environment=production` | Only production environment metrics and queries |
+| Regional team | `region=us-east` | Only metrics and queries from a specific region |
+
+## Getting started with LBAC
+
+To implement label-based access control in PMM:
+{.power-number}
+
+1. [Enable access control](enable_access_control.md) in your PMM settings
+2. Learn about the [labels available for filtering](labels.md)
+3. [Create access roles](create_roles.md) based on your organizational needs
+4. Review common [use cases and examples](use_cases.md) for inspiration
+
+!!! tip "Best practice"
+    Start with broader access controls and refine them over time as you understand your organization's specific needs. Test LBAC behavior in both dashboards and QAN to ensure proper access control.
+
+## Related topics
+
+- [Manage PMM users](../../manage-users/index.md)

documentation/docs/admin/roles/access-control/labels.md

@@ -1,41 +1,68 @@
 # Labels for access control
+Label-based access control in PMM allows you to precisely manage which monitoring data users can access based on their roles and responsibilities. 
 
+This feature is essential for organizations with multiple teams, compliance requirements, or where different users need different levels of visibility.
 
-Label-based access control in PMM allows you to manage who has access to metrics based on labels. By creating roles, you can specify which data can be queried based on specific label criteria, for instance, allowing the QA team to view data related to test environments. 
-
-With Label-based access control, you can associate multiple labels with a role, ensuring only data from series that match your defined labels is returned. 
+## How LBAC works
+Access control in PMM uses Prometheus label selectors to filter metrics and Query Analytics data.
 
+Here's how it works: 
+{.power-number}
+
+1. Create roles with specific label selectors. For example, you might allow the QA team to access only metrics related to test environments by assigning them a role with the `environment=test` label or limit visibility to metrics related only to MySQL services with the `service_type=mysql` label.
+2. Assign roles to users based on their responsibilities. Each role can include multiple labels, and only data series matching all associated labels will be visible to users with that role. This ensures precise, fine-grained access control to your data.
+3. Users see only the metrics and data that match their role's label selectors
 
 ## Standard vs custom labels
 
-PMM supports standard as well as custom labels. PMM automatically assigns standard labels. You can also set standard labels when an object (Node, Service, or Agent) is created. Custom labels are assigned and updated only by a user.
+PMM supports two types of labels for access control. When a user adds a service to monitoring, PMM automatically assigns standard labels based on the service type, such as `service_type`, `agent_type`, and `node_name`. Additional labels like `service_id` and `node_id` are also auto-generated by PMM.
+
+You can override some standard labels when creating objects such as Nodes, Services, or Agents. You can also define and assign custom labels. Unlike standard labels, custom labels are user-defined and can only be added or updated manually.
+
+Both standard and custom labels are propagated to the relevant metrics collected by the PMM Client. These labels are preserved during metric collection and can be used in PromQL queries.
 
 **Examples**
 
+| **Label Type**| **Object**| **Label name** | **Example** |                                                                                                
+|---------------|-----------|-----------------|--------------------------------------|
+| **Standard**  | Node      | node_id         | 5bdfb1b4-c6c4-4086-83a2-e8daa0b84d4b |                                          
+| **Standard**  | Service   | service_type    | mysql, mongodb, postgresql etc.      |
+| **Custom**    | Node, Service, Agent | Any string matching the regular expression: <br /> [a-zA-Z_][a-zA-Z0-9_]*. <br /> Also, it cannot start with two underscores.| owner="joe"<br/> _rack="12345"|
 
-| **Label Type**| **Object**| **Label name **| **Example** |                                                                                                
-|----------|--------|-------|------------------------------|
-| **Standard**  | Node   | node_id |123|                                          
-|          | Service|service_type   |   - mysql, mongodb, postgresql etc.                                     
-| **Custom**| Node, Service, Agent| Any string matching regular expression: <br /> [a-zA-Z_][a-zA-Z0-9_]*. <br /> Also, it cannot start with two underscores.| owner="joe"<br/> _rack="12345"|
+## Adding labels when creating services
 
-## Adding labels
+You can add standard or custom labels while adding a service to monitoring in PMM.
 
-You can add custom or standard labels in PMM while adding a service for monitoring in PMM.
+=== "Using the PMM UI"
+    To set the labels via the user interface:
+    {.power-number}
 
-### Using PMM UI
+    1. From the **Main** menu, go to **PMM Configuration > PMM Services > Add Service**.
 
-To set the labels using the user interface:
-{.power-number}
+    2. Select the service you want to monitor.
+
+    3. Complete the required connection details. 
+
+    4. Enter standard labels via the input section `Labels`.
+
+    5. Enter custom labels via section `Custom labels`.
+
+    ![PMM Inventory - Add Service](../../../images/lbac/PMM_access_control_add_labels_services.png)
+
+=== "Using pmm-admin"
 
-1. From the **Main** menu, go to **PMM Configuration > PMM Services > Add Service**.
+    You can also add standard and custom labels using [pmm-admin](../../../use/commands/pmm-admin.md).
 
-2. Select the service you want to add to PMM for monitoring. The page to add the service opens.
+## Modifying existing labels
+PMM allows modifying certain standard labels after a service is created:
 
-3. Enter the details such as *Hostname, Service name, Port, Username, Password,* etc., along with Label or Custom labels.
+- `environment`
+- `cluster`
+-  `replication_set`
+- `external_group`
 
- ![!](../../../images/PMM_access_control_add_labels_services.png)
+For other standard labels that cannot be modified directly, you must remove the service and re-add it with the desired labels.
 
-### Using pmm-admin
+This can be done either via PMM UI or via an [API endpoint](https://percona-pmm.readme.io/reference/changeservice).
 
- You can also assign labels using [pmm-admin](../../../use/commands/pmm-admin.md).
+Modifying the custom labels can be done as well via PMM UI of via the same [API endpoint](https://percona-pmm.readme.io/reference/changeservice).

documentation/docs/admin/roles/access-control/manage_roles.md

@@ -8,11 +8,12 @@ To edit access roles:
 {.power-number}
 
 1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option.
+
 2. Go to **Administration > Users and access > Access Roles**.
 
 3. On the role you want to edit, click the **ellipsis (three vertical dots) > edit role** in the **Options** column. The **Edit** role page opens.
 
-    ![!](../../../images/PMM_access_control_edit_role.png)
+    ![PMM Access Control - Edit role](../../../images/lbac/PMM_access_control_edit_role.png)
 
 4. Make the required changes to the role.
 
@@ -26,7 +27,9 @@ To set a role as default, do the following:
 {.power-number}
 
 1. From [main menu](../../../reference/ui/ui_components.md), go to **PMM Configuration > Settings > Advanced Settings** and enable the **Access Roles** option.
+
 2. Go to **Administration > Users and access > Access Roles**.
+
 3. On the role you want to set as default, click the **ellipsis (three vertical dots) → set as default** in the **Options** column.
 
 

documentation/docs/admin/roles/access-control/use_cases.md

@@ -0,0 +1,39 @@
+# Implementing LBAC: practical scenarios
+
+Here are a few practical examples of how label-based access control can be implemented in PMM to meet specific organizational needs.
+
+## Infrastructure overview
+The diagram below shows a sample infrastructure monitored by PMM. Notice how the metrics stored in VictoriaMetrics include labels like **environment** and **region** that can be used for access control.
+
+  <!-- source: https://miro.com/app/board/uXjVPfHchvM=/ -->
+  ![PMM Access Control - Metrics collection](../../../images/lbac/pmm-lbac-collect-metrics.jpg)
+
+## Use case 1: Simple selectors
+
+This scenario demonstrates how to create three distinct roles with different levels of access:
+
+![PMM Access Control - Basic Roles](../../../images/lbac/pmm-lbac-query-metrics-1.jpg)
+
+| Role | Access needs | Label selectors | Effect |
+|------|--------------|-----------------|--------|
+| **Admin** | Complete visibility across all environments | `environment=prod` OR `environment=qa` | Full access to all metrics in both production and QA environments across all regions |
+| **DBA** | Production database management | `environment=prod` | Access to all production metrics across all regions, but no visibility into QA |
+| **QA** | Testing environment monitoring | `environment=qa` | Access to all QA metrics across all regions, but no visibility into production |
+
+This approach allows for a clear separation of responsibilities while ensuring each team has access to exactly what they need.
+
+## Use case 2 - Compound selectors
+
+This advanced use case demonstrates how compound selectors create more granular access control by combining multiple label conditions using logical operators (AND, OR). 
+
+By requiring matches on multiple labels simultaneously, you can implement sophisticated access patterns that reflect real-world organizational structures and security requirements.
+
+<!-- source: https://miro.com/app/board/uXjVPfHchvM=/ -->
+![PMM Access Control - Roles](../../../images/lbac/pmm-lbac-query-metrics-2.jpg)
+
+
+| Role | Access needs | Label selectors | Effect |
+|------|--------------|-----------------|--------|
+| **Admin** | Complete visibility across all environments and regions | `environment=prod` OR `environment=qa` | Full access to all metrics in both production and QA environments across all regions |
+| **DBA** | Production database management in EMEA region | `environment=prod` AND `region=emea` | Access only to production metrics in the EMEA region |
+| **QA** | Testing environment monitoring in US-East region | `environment=qa` AND `region=us-east` | Access only to QA metrics in the US-East region |