Workload group rules - OpenSearch Documentation
Workload group rules | OpenSearch Documentation
OpenSearch
About
Releases
Roadmap
FAQ
Platform
Observability
Security Analytics
Vector Database
Playground Demo
Performance Benchmarks
Community
Forum
Slack
Events
Solutions Providers
Projects
Members
Documentation
OpenSearch and Dashboards
Data Prepper
Clients
Benchmark
Migration Assistant
Blog
Documentation
Workload group rules
Workload group rules allow you to automatically assign workload group IDs to incoming queries. When a query matches the attributes specified in a rule, OpenSearch tags the query with the corresponding workload group ID. This eliminates the need for clients to manually include the workload group ID in each request. For more information about auto-tagging requests, see
Rule-based auto-tagging
Creating a rule
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:
PUT
_rules/workload_group
"description"
"description for rule"
"index_pattern"
"test*"
],
"principal"
"username"
"admin"
},
"workload_group"
"wfbdJoDAS0mYiLbEAjd1sA"
copy
The response contains the rule ID:
"id"
"176fd554-43e7-39eb-92cc-56615d287eae"
"description"
"description for rule"
"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 contains the following parameters.
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
To update a rule, provide its ID in the path parameter and the updated fields in the request body. When you update a rule, only the parameters you specify are changed; all others stay the same. The following request updates a rule description and index pattern for the rule with the ID
176fd554-43e7-39eb-92cc-56615d287eae
PUT
_rules/workload_group/
176
fd
554-43e7-39
eb
-92
cc
-56615
287
eae
"description"
"updated description for rule"
"index_pattern"
"log*"
"event*"
copy
The response shows the updated fields:
"id"
"176fd554-43e7-39eb-92cc-56615d287eae"
"description"
"updated description for rule"
"index_pattern"
"log*"
"event*"
],
"workload_group"
"wfbdJoDAS0mYiLbEAjd1sA"
"updated_at"
"2025-08-06T15:14:09.935879339Z"
Retrieving a rule
You can retrieve rules by rule ID or attribute filters. You can paginate through the list of returned rules.
The following request retrieves all rules for the
workload_group
feature type:
GET
/_rules/workload_group
copy
The following request retrieves a rule by ID for the
workload_group
feature type:
GET
/_rules/workload_group/
rule_id
copy
The following request retrieves all
workload_group
rules matching the specified
index_pattern
and
principal.username
GET
/_rules/workload_group?index_pattern=log*,event*&principal.username=admin
copy
If the response contains more results than can fit on a single page, OpenSearch paginates the results and includes a
search_after
value in the response:
"rules"
"id"
"z1MJApUB0zgMcDmz-UQq"
"description"
"Rule for tagging workload_group_id to index123"
"index_pattern"
"index123"
],
"workload_group"
"workload_group_id"
"updated_at"
"2025-02-14T01:19:22.589Z"
},
...
],
"search_after"
"z1MJApUB0zgMcDmz-UQq"
To retrieve the next page, send another request to the same endpoint using the same filters and include the
search_after
value from the previous response as a query parameter.
The following request provides the next page of rules from the same workload group:
GET
/_rules/workload_group?index_pattern=log*,event*&search_after=z
MJApUB
zgMcDmz-UQq
copy
Deleting a rule
To delete a rule, provide the rule’s ID:
DELETE
/_rules/workload_group/
rule_id
copy
Creating a rule
Attributes
Parameters
Updating a rule
Retrieving a rule
Deleting a rule
WAS THIS PAGE HELPFUL?
✔ Yes
✖ No
Tell us why
350 characters left
Thank you for your feedback!
Have a question?
Ask us on the OpenSearch forum
Want to contribute?
Edit this page
or
create an issue
OpenSearch Links
Get Involved
Code of Conduct
Forum
GitHub
Slack
Resources
About
Release Schedule
Maintenance Policy
FAQ
Testimonials
Trademark and Brand Policy
Connect
Meetup
Copyright © OpenSearch Project a Series of LF Projects, LLC
For web site terms of use, trademark policy and other project policies please see