Chapter 7. Using Dynamic Groups
A dynamic groups specifies a search term to use to search the inventory and identify matching resources to belong to the group. Since the search results change automatically as results are added and removed from the inventory, the group membership is always changing and always current. Using dynamic groups helps automate management tasks for large inventories.
Note
Dynamic groups are also referred to by the nickname dynagroups.
Enterprise resources can be grouped by cluster identifier, broadcast group, logical service layer, geographical location, security domain, or any other logical grouping.
Individual resources can potentially belong to multiple groups, in large inventories it is important to know how different group definitions will affect the enterprises resources.
7.1. About Dynamic Groups Syntax
Dynamic groups are configured through group definitions. A group definition uses expressions which define searches for resources, along with other information about the group like the recalculation interval.
Dynamic groups have an expression syntax very similar to the one used for dynamic searches (Section 2.2, “About the Dynamic Search Syntax”).
7.1.1. General Expression Syntax
The expression is a search condition that is centered around a specific resource attribute, either by a specific value of an attribute or simply by the presence of an attribute.
An expression defines a way to group resources:
- By a specific resource attribute or value (a simple expression)
- By the resource type (a pivoted expression)
- By membership in another group (a narrowing expression)
A single group definition can have multiple expressions. The order of expressions in the group definition does not matter; for example, both of these expressions are interpreted exactly the same when calculating the group members:
expression 1 exprA1 exprA2 groupby exprB1 groupby exprB2 expression 2 exprA2 exprA1 groupby exprB2 groupby exprB1
Note
When multiple expressions are used in a group definition, they are treated as logical AND expressions, and a resource must match all the criteria to belong to the group.
Any empty lines between expressions in a dynagroup definition are ignored.
The possible resource properties cover resource information like the resource name, type, plug-in, version, configuration property, and inventory ID number.
| Type | Supported Attributes | ||||||
|---|---|---|---|---|---|---|---|
| Related to the resource itself | |||||||
|
resource
|
| ||||||
| Related to the resource type | |||||||
|
resourceType
|
| ||||||
| Related to the resource configuration | |||||||
|
plug-inConfiguration
|
Any plugin configuration property
| ||||||
|
resourceConfiguration
|
Any resource configuration property
| ||||||
| Related to the resource monitoring data | |||||||
|
traits
|
Any monitoring trait
| ||||||
|
availability
|
The current state, either UP or DOWN
| ||||||
If an expression has the structure
resource.attribute, then it applies to the resource which will be a member of the group. However, it is possible to use an attribute in an ancestor or child entry to identify a group member recursively.
For example, to add a resource as member which as an inventory ID of 10001, the expression is:
resource.id = 10001
To add all of the children of a resource with an ID of 10001 as group members, use the prefix
resource.parent:
resource.parent.id = 10001
There are four possible prefixes for all of the resource attributes in Table 7.1, “Dynamic Group Properties”:
- resource
- resource.child
- resource.parent
- resource.grandParent
If a definition is so restrictive that no resources match the filters, no group is created. JBoss ON will actually suppress a group from being created by a group definition if it would result in an empty group. Because there are no empty groups, there are no extraneous groups listed in the inventory, which makes managing inventories easier and better reflects your real infrastructure.
7.1.2. Simple Expressions: Looking for a Value
A simple expression uses an attribute-value pair or triad in this format:
resource.attribute[string-expression] = value
For example:
resource.parent.type.category = Platform
Not every resource attribute has an additional string-expression; a string-expression is basically a sub-attribute. For example,
resource.trait is the generic resource attribute, and a sub-attribute like partitionName identifies the actual parameter.
Simple expressions usually search for resources based on an explicit value, but resources may have attributes present with null values, and those null values would be not returned with a simple expression. The
empty keyword searches for resources which have a specific attribute with a null value:
empty resource.attribute[string-expression]
If the
empty keyword is used, then there is no value given with the expression.
Simple expressions can also use a
not empty keyword, which looks for every resource with that attribute, regardless of the attribute value, as long as it is not null. As with the empty keyword, there is no reason to give a value with the expression, since every value matches the expression.
not empty resource.attribute[string-expression]
7.1.3. Pivot Expressions: Grouping by an Attribute
Simple expressions create a single group, because they are based on the specific results of the search. Alternatively, a pivot expression creates multiple groups because it identifies resources which belong to the group solely based on whether an attribute exists; it creates subgroups based on the values. A pivot expression uses the
groupby keyword:
groupby resource.attribute
Pivoted expressions create groups based on unique occurrences of an attribute value. For example, the
parent.name attribute creates a unique group based on every parent resource.
groupby resource.parent.name
For the resources in Figure 7.1, “Resources and Parents”, the pivot expression creates groups for the three parents within the resource hierarchy: ResourceParentA, ResourceParentB, and ChildA2.
Figure 7.1. Resources and Parents
If the overall group definition includes resources with null values, then the pivot expression creates a special subgroup that contains those resources.
7.1.4. Narrowing Expressions: Members of a Group
Expressions are generally evaluated across the entire inventory. For example, setting a pivot expression for the JBoss AS 7 Server resource type checks the inventory for every EAP 6 or AS 7 instance.
In some occasions, particularly if trying to create fine-grained groups for access control or bundle management, it is simpler to define an expression to run against the members of an existing group, rather than trying to devise a complex expression to get a subset of the same type of resource.
This is done by specifying the memberof keyword. This specifies a group name (compatible group, mixed group, autogroups, recursive group, even another dynagroup), and only members of that group are evaluated for other matching expressions.
Note
The
memberof keyword specifies a group name. If the group is a recursive group, then all of the recursive members are included as part of the group for evaluation.
For example, an administrator creates different groups for application development related resources for development, QE, and production teams. These are mixed groups of platforms, Postgre databases, EAP 6 servers, and web contexts. When new resources are deployed, a CLI script is run to import the resources and automatically update the resource groups. Access control rules and roles need to use both the main groups — such as Dev Stack Resource Group, a mixed group — and subgroups within that group, based on resource types. Rather than creating and updating multiple groups and roles every time resources are deployed or removed, the administrator creates a dynagroup expression which first narrows the scope of the expression to the given team resource group, and then pivots by resource type. The dynagroup definition only needs to be set once, and it is dynamically updated with inventory changes every time the group is recalculated.
memberof = "Dev Resource Group" groupby resource.type.name
Note
The group membership, as with other expressions, is only updated with
memberof changes when the dynagroup is recalculated.
Multiple
memberof expressions are allowed in the group definition, with each memberof expression referencing a single group. If multiple memberof expressions are used, they are treated as AND expressions; any matching resource must be a member of all specified groups.
7.1.5. Compound Expressions
Multiple expressions can be used in a single dynagroup definition; these are compound expressions.
When multiple expressions are used in a group definition, they are treated as logical AND expressions, and a resource must match all the criteria to belong to the group. (Any empty lines between expressions in a dynagroup definition are ignored.)
For example, this basic expression searches for every resource which has the platform as its parent:
resource.parent.type.category = Platform
That could return a very long list of servers and services. That initial list can be further filtered by adding another simple expression, which filters by name:
resource.parent.type.category = Platform resource.name.contains = JBossAS
Only resources with the platform as the parent and with the string JBossAS in their name will be added to the group.
Pivoted expressions can also be used in compound expressions. Every line must have the groupby keyword, not only the first line.
groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
A compound expression can contain both simple and pivoted expressions. This creates a compatible group for every unique server type on the platform.
resource.type.category = server groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
Lastly, compound expressions can include the empty and not empty keywords. For example, simple expressions can be used to identify JBoss servers based on the resource type and name. Then, to identify which JBoss servers are unsecured, the expression can filter for JBoss servers with a principal connection property with an empty value.
resource.type.plugin = JBossAS resource.type.name = JBossAS Server empty resource.pluginConfiguration[principal]
7.1.6. Unsupported Expressions
There are restrictions on how multiple expressions can be used together.
All expressions must be in the same configuration area.
All given configuration properties in an expression must be only from the resource configuration or only from the plug-in configuration. Expressions cannot be taken from both.
Each property must only be used once.
A property can only be used once in a dynagroup definition.
valid resource.trait[x] = foo not valid resource.trait[x] = foo resource.trait[y] = bar
For example, a
resource.trait expression can only occur once in a definition:
resource.grandParent.trait[Trait.hostname].contains = stage resource.parent.type.plugin = JBossAS5 resource.type.name = Web Application (WAR)
If it is used a second (or more) time, then the subsequent use fails and causes the definition not to be parsed.
resource.grandParent.trait[Trait.hostname].contains = stage resource.parent.type.plugin = JBossAS5 resource.type.name = Web Application (WAR) resource.trait[contextRoot] = jmx-console
This results in calculation errors:
There was a problem calculating the results: java.lang.IllegalArgumentException: org.hibernate.QueryParameterException: could not locate named parameter [arg2]
The [arg2] error is a sign that multiple expressions of the same type were used and that the second and subsequent expressions caused a calculation failure.
This is true even if the property type is used with different resource contexts.
resource.parent.trait[x] = foo resource.grandParent.trait[y] = bar
In the previous example, one trait applied to the grandparent resource and one trait applied to the resource itself. This still failed because the trait property was used twice, even though it was for different resources.
7.1.7. Dynagroup Expression Examples
A single group definition can have multiple expressions, even mixing simple and pivoted expressions in a single definition. Many of these examples require multiple expressions to complete the definition.
Example 7.1. JBoss Clusters
resource.type.plugin = JBossAS resource.type.name = JBossAS Server groupby resource.trait[partitionName]
Example 7.2. A Group for Each Platform Type
resource.type.plugin = Platforms resource.type.category = PLATFORM groupby resource.type.name
Example 7.3. Autogroups
groupby resource.type.plugin groupby resource.type.name groupby resource.parent.name
Note
This could create a large number of groups in large inventories.
Example 7.4. Raw Measurement Tables
resource.type.plugin= Postgres resource.type.name = Table resource.parent.name = rhq Database resource.name.contains = rhq_meas_data_num_
Example 7.5. Only Agents with Multicast Detection
resource.type.plugin= RHQAgent resource.type.name = RHQ Agent resource.resourceConfiguration[rhq.communications.multicast-detector.enabled] = true
Example 7.6. Only Windows Platforms with Event Tracking
resource.type.plugin= Platforms resource.type.name = Windows resource.pluginConfiguration[eventTrackingEnabled] = true
Example 7.7. JBoss AS Servers by Machine
groupby resource.parent.trait[Trait.hostname] resource.type.plugin = JBossAS resource.type.name = JBossAS Server
