Add principal attributes description to Rule-based Auto-tagging documentation (#11158)

* add security attributes description to auto tagging documentation
Signed-off-by: Ruirui Zhang <[email protected]>

* Doc review

Signed-off-by: Fanit Kolchina <[email protected]>

* Apply suggestions from code review

Signed-off-by: Nathan Bower <[email protected]>

---------

Signed-off-by: Fanit Kolchina <[email protected]>
Signed-off-by: Nathan Bower <[email protected]>
Co-authored-by: Fanit Kolchina <[email protected]>
Co-authored-by: Nathan Bower <[email protected]>

Author: 3 people

_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/autotagging.md

@@ -29,7 +29,7 @@ Rule-based auto-tagging provides a flexible framework for implementing feature-s
 Before reviewing the rule configuration and behavior, it's important to understand the following key components of rule-based auto-tagging:
 
 * **Rule**: Defines matching criteria (attributes) and the value to assign.
-* **Attributes**: Key-value pairs used to match rules (such as index patterns, user roles, or request types).
+* **Attributes**: Key-value pairs used to match rules (such as index patterns, username, user roles, or request types).
 * **Feature-specific value**: The value assigned when a rule matches.
 * **Pattern matching**: The matching behavior (exact or pattern based) for attribute values.
 
@@ -44,7 +44,11 @@ The following rule schema includes matching attributes and a feature-specific va
 ```json
 {
   "_id": "fwehf8302582mglfio349==",  
-  "index_pattern": ["logs-prod-*"],  
+  "index_pattern": ["logs-prod-*"],
+  "principal": {
+    "username": ["admin"],
+    "role": ["all_access"]
+  },
   "other_attribute": ["value1", "value2"],
   "workload_group": "production_workload_id",
   "updated_at": 1683256789000
@@ -92,7 +96,38 @@ OpenSearch evaluates incoming requests using the following process:
 3. The most specific matching rule's value is assigned.
 4. If no rules match, no value is assigned.
 
-## Examples
+### Rule matching examples
+
+The following examples demonstrate how OpenSearch matches attributes and resolves ties between rules.
+
+In these examples, the `username` attribute has higher priority than the `index_pattern` attribute (priority order depends on the feature and feature type).
+
+1. **Example 1**
+   A request matches three rules:
+
+   * Rule 1: `index_pattern = log`
+   * Rule 2: `username = admin`
+   * Rule 3: `index_pattern = log123`
+
+   **Result**: Rule 2 applies because the `username` attribute has higher priority.
+
+2. **Example 2**
+   A request matches two rules:
+
+   * Rule 1: `index_pattern = logs-prod-*`
+   * Rule 2: `index_pattern = logs-*`
+
+   **Result**: Rule 1 applies because `logs-prod-*` is more specific than `logs-*`.
+
+3. **Example 3**
+   A request matches two rules:
+
+   * Rule 1: `index_pattern = log` and `username = admin`
+   * Rule 2: `username = admin`
+
+   **Result**: Rule 1 applies because it includes both the `index_pattern` and `username` attributes, making it a more specific match.
+
+## Workload management examples
 
 These examples demonstrate how rule-based auto-tagging works in workload management, which uses index patterns as its primary attribute.
 
@@ -167,7 +202,7 @@ When creating rules, the following issues can occur:
 
 * **Unexpected value**: This can happen when multiple rules are defined with overlapping or conflicting conditions.  
   For example, consider the following rules:
-  1. `{ "username": ["dev*"], "index_pattern": ["logs*"] }`
+  1. `{ principal: {"username": ["dev*"]}, "index_pattern": ["logs*"] }`
   2. `{ "index_pattern": ["logs*", "events*"] }`
 
   If a user with the username `dev_john` sends a search request to `logs_q1_25`, it will match the first rule based on the `username` and `index_pattern` attributes. The request will not match the second rule, even though the `index_pattern` also qualifies.

_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/rule-lifecycle-api.md

@@ -17,7 +17,7 @@ The following sections describe the API endpoints available for managing rules a
 
 ### Create a rule
 
-Use the followiing endpoint to add a new rule for a specific feature type:
+Use the following endpoint to add a new rule for a specific feature type:
 
 ```json
 PUT /_rules/{feature_type}
@@ -85,13 +85,17 @@ The following example demonstrates how to use the Rules API to create a rule.
 
 ### Create a rule
 
-The following request creates a rule that assigns a `workload_group` value based on matching `index_pattern` attributes:
+The following request creates a rule that assigns a `workload_group` value based on matching `index_pattern` and principal attributes:
 
 ```json
 PUT _rules/workload_group
 {
   "description": "description for rule",
   "index_pattern": ["log*", "event*"],
+  "principal": {
+    "username": ["admin"],
+    "role": ["all_access"]
+  },
   "workload_group": "EITBzjFkQ6CA-semNWGtRQ"
 }
 ```
@@ -106,6 +110,10 @@ PUT _rules/workload_group/0A6RULxkQ9yLqn4r8LPrIg
 {
   "description": "updated_description for rule",
   "index_pattern": ["log*"],
+  "principal": {
+    "username": ["admin"],
+    "role": ["all_access"]
+  },
   "workload_group": "EITBzjFkQ6CA-semNWGtRQ"
 }
 ```
@@ -130,10 +138,10 @@ GET /_rules/{feature_type}
 ```
 {% include copy-curl.html %}
 
-The following request returns all rules of the feature type `workload_group` that contain the attribute `index_pattern` with values `a` or `b`:
+The following request returns all rules of the `workload_group` feature type that contain an `index_pattern` attribute with values `a` or `b` and `principal.username` set to `admin`:
 
 ```json
-GET /_rules/workload_group?index_pattern=a,b
+GET /_rules/workload_group?index_pattern=a,b&principal.username=admin
 ```
 {% include copy-curl.html %}
 
@@ -160,6 +168,10 @@ GET /_rules/workload_group?index_pattern=a,b&search_after=z1MJApUB0zgMcDmz-UQq
   "id": "wi6VApYBoX5wstmtU_8l",
   "description": "description for rule",
   "index_pattern": ["log*", "event*"],
+  "principal": {
+    "username": ["admin"],
+    "role": ["all_access"]
+  },
   "workload_group": "EITBzjFkQ6CA-semNWGtRQ",
   "updated_at": "2025-04-04T20:54:22.406Z"
 }
@@ -181,6 +193,10 @@ GET /_rules/workload_group?index_pattern=a,b&search_after=z1MJApUB0zgMcDmz-UQq
       "id": "z1MJApUB0zgMcDmz-UQq",
       "description": "Rule for tagging workload_group_id to index123",
       "index_pattern": ["index123"],
+      "principal": {
+        "username": ["admin"],
+        "role": ["all_access"]
+      },
       "workload_group": "workload_group_id",
       "updated_at": "2025-02-14T01:19:22.589Z"
     },

_tuning-your-cluster/availability-and-recovery/workload-management/workload-group-rules.md

@@ -14,13 +14,16 @@ Workload group rules allow you to automatically assign workload group IDs to inc
 
 ## Creating a rule
 
-To create a rule for a workload group, provide the workload group ID in the `workload_group` parameter. The following request creates a rule that assigns the specified workload group to requests for the matching `index_pattern`:
+To create a rule for a workload group, provide the workload group ID in the `workload_group` parameter. The following example creates a rule that assigns the given workload group to requests matching both the `index_pattern` and `principal.username` attributes:
 
 ```json
 PUT _rules/workload_group
 {
   "description": "description for rule",
   "index_pattern": ["test*"],
+  "principal": {
+    "username": ["admin"]
+  },
   "workload_group": "wfbdJoDAS0mYiLbEAjd1sA"
 }
 ```
@@ -32,23 +35,36 @@ The response contains the rule ID:
 {
   "id": "176fd554-43e7-39eb-92cc-56615d287eae",
   "description": "description for rule",
-  "index_pattern": [
-    "test*"
-  ],
+  "index_pattern": ["test*"],
+  "principal": {
+    "username": ["admin"]
+  },
   "workload_group": "wfbdJoDAS0mYiLbEAjd1sA",
   "updated_at": "2025-08-06T15:12:44.791Z"
 }
 ```
 
+## Attributes
+
+The `workload_group` feature type contains the following attributes. Each rule must contain at least one of these attributes.
+
+The table lists the attributes in order of priority, from highest to lowest. This priority is predefined and cannot be changed by the user. When multiple rules match a request, the rule containing the highest-priority attribute is applied.
+
+| Attribute            | Data type | Description                                                                                                                                                                                                                   |
+|:---------------------|:----------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `principal.username` | List      | A list of usernames to be matched to this rule. This attribute is available only when the Security plugin is enabled on the domain. The attribute supports exact matching only.                                 |
+| `principal.role`     | List      | A list of roles to be matched to this rule. This attribute is available only when the Security plugin is enabled on the domain. The attribute supports exact matching only.                                     |
+| `index_pattern`      | List      | A list of target indexes for incoming queries. Each element can be a full index name or a prefix ending in `*` to support wildcard matching (for example, `logs*`).                                |
+
 ## Parameters
 
-The `workload_group` feature type requires the following parameters.
+The `workload_group` feature type contains the following parameters.
 
-| Attribute  | Data type | Description  |
-| :--- | :--- | :--- |
-| `index_pattern` | List      | A list of strings used to match the target indexes of incoming queries. Each string can be an exact index name or a prefix ending in `*` to support wildcard matching, for example, `logs*`. |
-| `description` | String      | A description of the rule. |
-| `workload_group` | String      | The workload group ID to apply to the requests matching this rule. |
+| Parameter        | Data type | Description                                                                                             |
+|:-----------------|:----------|:--------------------------------------------------------------------------------------------------------|
+| attribute        | Object    | A rule must contain at least one attribute (`index_pattern`, `principal.username`, or `principal.role`). |
+| `description`    | String    | A description of the rule.                                                                              |
+| `workload_group` | String    | The workload group ID to apply to the requests matching this rule.                                      |
 
 ## Updating a rule
 
@@ -96,10 +112,10 @@ GET /_rules/workload_group/{rule_id}
 ```
 {% include copy-curl.html %}
 
-The following request retrieves all `workload_group` rules matching the specified `index_pattern`:
+The following request retrieves all `workload_group` rules matching the specified `index_pattern` and `principal.username`:
 
 ```json
-GET /_rules/workload_group?index_pattern=log*,event*
+GET /_rules/workload_group?index_pattern=log*,event*&principal.username=admin
 ```
 {% include copy-curl.html %}
 

_tuning-your-cluster/availability-and-recovery/workload-management/workload-groups.md

@@ -96,7 +96,7 @@ GET /_wlm/workload_group/{name}
 To delete a workload group, specify its name as a path parameter:
 
 ```json
-DELETE /_wlm/query_group/{name}
+DELETE /_wlm/workload_group/{name}
 ```
 {% include copy-curl.html %}