iControl 101 - #13 - Data Groups

Data Groups can be useful when writing iRules.  A data group is simply a group of related elements, such as a set of IP addresses, URI paths, or document extensions. When used in conjuction with the matchclass or findclass commands, you eliminate the need to list multiple values as arguments in an iRule expression.  This article will discuss how to use the methods in the LocalLB::Class interface to manage the Data Groups for use within iRules.

Terminology

You will first notice a mixing up of terms.  A "Class" and a "Data Group" can be used interchangeably.  Class was the original development term and the marketing folks came up with Data Group later on so you will see "Class" embedded in the core configuration and iControl methods, thus the LocalLB::Class interface, and "Data Groups" will most often be how they are referenced in the administration GUI.

Data Groups come in 4 flavors: Address, Integer, String, and External.  Address Data Groups consist of a list of IP Addresses with optional netmasks and are useful for applying a policy based on a originating subnet.  Integer Data Groups hold numeric integers and, to add more confusion, are referred as "value" types in the API.  String Data Groups can hold a valid ascii-based string.  All of the Data Group types have methods specific to their type (ie get_string_class_list(), add_address_class_member(), find_value_class_member()).  External Data Groups are special in that they have one of the previous types but there are no direct accessor methods to add/remove elements from the file.  The configuration consists of a file path and name, along with the type (Address, Integer, String).  You will have to use the ConfigSync file transfer APIs to remotely manipulate External Data Groups.  External Data Groups are meant for very large lists of lists that change frequently.

This article will focus on String Data Groups, but the usage for Address and Integer classes will be similar in nature.

Initialization

This article uses PowerShell and the iControl Cmdlets for PowerShell as the client environment for querying the data.  The following setup will be required for the examples contained in this article.

PS> Add-PSSnapIn iControlSnapIn
PS> Initialize-F5.iControl -Hostname bigip_address -Username bigip_user -Password bigip_pass
PS> $Class = (Get-F5.iControl).LocalLBClass

Listing data groups

The first thing you'll want to do is determine which Data Groups exist.  The get_string_class_list() method will return a array of strings containing the names of all of the existing String based Data Groups.

PS> $Class.get_string_class_list()
test_list
test_class
carp
images

Creating a Data Group

You have to start from somewhere, so most likely you'll be creating a new Data Group to do your bidding.  This example will create a data group of image extensions for use in a URI based filtering iRule.  The create_string_class() takes as input an array of LocalLB::Class::StringClass structures, each containing the class name and an array of members.  In this example, the string class "img_extensions" is created with the values ".jpg", ".gif", and ".png".  Then the get_string_class_list() method is called to make sure the class was created and the get_string_class() method is called to return the values passed in the create method.

PS> $StringClass = New-Object -typename iControl.LocalLBClassStringClass
PS> $StringClass.name = "img_extensions"
PS> $StringClass.members = (".jpg", ".gif", ".png")
PS> $Class.create_string_class(,$StringClass)

PS> $Class.get_string_class_list()
test_list
test_class
carp
images
img_extensions

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.gif, .jpg, .png}

Adding Data Group items

Once you have an existing Data Group, you most likely will want to add something to it.  The add_string_class_member() method will take as input the same LocalLB::Class::StringClass structure containing the name of the Data Group and the list of new items to add to it.  The following code will add two values: ".ico" and ".bmp" to the img_extensions Data Group and then will query the values of the Data Group to make sure the call succeeded.

PS> $StringClass.members = (".ico", ".bmp")
PS> $Class.add_string_class_member(,$StringClass)

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.bmp, .gif, .ico, .jpg...}

Removing Data Group Items

If you want to add items, you may very well want to delete items.  That's where the delete_string_class_member() method comes in.  Like the previous examples, it takes the LocalLB::Class::StringClass structure containing the name of the Data Group and the values you would like to remove.  The following example removes the ".gif" and ".jpg" value and queries the current value of the list.

PS> $StringClass.members = (".gif", ".jpg")
PS> $Class.delete_string_class_member(,$StringClass)

PS> $Class.get_string_class((,"img_extensions"))
name                                                        members
----                                                        -------
img_extensions                                              {.bmp, .ico, .png}

Deleting Data Groups

The interface wouldn't be complete if you couldn't delete the Data Groups you previously created.  The delete_class() method takes as input a string array of class names.  This example will delete the img_extensions Data Group and then call the get_string_class_list() method to verify that it was deleted.

PS> $Class.delete_class(,"img_extensions")

PS> $Class.get_string_class_list()
ts_reputation
test_list
test_class
carp
images

Conclusion

That's about it!  Just replace the "string" with "address" and "value" in the above methods and you should be well on your way to building any type of Data Group you need for all your iRule needs.