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.

Table 7.1. Dynamic Group Properties

Type Supported Attributes
Related to the resource itself
resource
id
name
version
parent
grandparent
children
Related to the resource type
resourceType
plug-in
name
category (platform, server, service)
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.
Resources and Parents

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