diff --git a/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/autotagging.md b/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/autotagging.md index 27bf2d83f7c..5690c346470 100644 --- a/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/autotagging.md +++ b/_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. diff --git a/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/rule-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/rule-lifecycle-api.md index b48c2d52e34..b702f1e3ed8 100644 --- a/_tuning-your-cluster/availability-and-recovery/rule-based-autotagging/rule-lifecycle-api.md +++ b/_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" }, diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/workload-group-rules.md b/_tuning-your-cluster/availability-and-recovery/workload-management/workload-group-rules.md index f4e18040663..6d495ac3d9e 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/workload-group-rules.md +++ b/_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 %} diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/workload-groups.md b/_tuning-your-cluster/availability-and-recovery/workload-management/workload-groups.md index 60e5bac4d14..45e9496005f 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/workload-groups.md +++ b/_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 %}