iControl 101 - #22 - GTM Data Centers
The components that make up the BIG-IP Global Traffic Manager can be divided into two categories: logical and physical components. Logical Components are abstractions of network resources, such as virtual servers. Physical components, on the other hand, have a direct correlation with one or more physical entities on the network. In this article, I will disucss Data Centers (one of the physical network components in the Global Traffic Manager) and illustrate how to programmatically manage them with the iControl API.
A data center defines the group of Global Traffic Managers, Local Traffic Managers, and host systems that reside in a single physical location. Within the Global Traffic Manager, a data center contains at least one server and one link. Every resource, whether physical or logical, is associated in some way with a data center. The Global Traffic Manager consolidates the paths and metrics data collected from both servers, virtual servers, and links into the data center, and uses that consolidated data when conducting load balancing operations.
Any server or link that you add to the Global Traffic Manager configuration must belong to one and only one data center, and you must configure at least one data center before you can add servers to the Global Traffic Manager configuration.
Usage
The following code samples will build a PowerShell command line application allowing control over GTM Data Centers. This program takes as input the bigip, username, and password as well as a subcommand and optional parameters. Usage is displayed with the Write-Usage function
param (
$g_bigip = $null,
$g_uid = $null,
$g_pwd = $null,
$g_cmd = $null,
$g_name = $null,
$g_arg1 = $null,
$g_arg2 = $null
);
Set-PSDebug -strict;
function Write-Usage()
{
Write-Host @"
Usage: GtmDataCenter.ps1 host uid pwd [options]
options
-------
list
- Get a list of rate classess
create name location contact
- Create a data center.
setcontact name contact
- Set the contact info for the given data center.
setlocation name location
- Set the location info for the given data center.
setstate name [enabled|disabled]
- Set the enabled state for the given data center.
getstatistics name
- Get the statisics for the given data center.
"@;
exit;
}
Initialization
As is with all of my iControl PowerShell scripts, validation is made as to whether the iControlSnapin is loaded into the current powershell context. The Initialize-F5.iControl cmdlet is then called to setup the connection to the BIG-IP for subsequent calls.
The main application logic checks for the passed in command and then passes control to one of the local functions defined below:
function Do-Initialize()
{
if ( (Get-PSSnapin | Where-Object { $_.Name -eq "iControlSnapIn"}) -eq $null )
{
Add-PSSnapIn iControlSnapIn
}
$success = Initialize-F5.iControl -HostName $g_bigip -Username $g_uid -Password $g_pwd;
return $success;
}
if ( ($g_bigip -eq $null) -or ($g_uid -eq $null) -or ($g_pwd -eq $null) )
{
Write-Usage;
}
if ( Do-Initialize )
{
switch ($g_cmd)
{
"" {
Get-DataCenterList;
}
"list" {
Get-DataCenterList $g_name;
}
"create" {
Create-DataCenter $g_name $g_arg1 $g_arg2;
}
"delete" {
Delete-DataCenter $g_name;
}
"setcontact" {
Set-DataCenterContact $g_name $g_arg1;
}
"setlocation" {
Set-DataCenterLocation $g_name $g_arg1;
}
"setstate" {
Set-DataCenterEnabledState $g_name $g_arg1;
}
"getstatistics" {
Get-DataCenterStatistics $g_name;
}
default {
Write-Usage;
}
}
}
else
{
Write-Error "ERROR: iControl subsystem not initialized"
}
Retrieving Information About Existing Data Centers
A Data Center is comprised of its Name, a location, and a contact. These can be retrieved with the iControl GlobalLBDataCenter.get_list(), get_location_information(), and get_contact_information() methods respectively. Several other attributes that are read-only include the enabled states, object status, and the links and servers that are part of the specific data center.
The following Get-DataCenterList function will aggregate all the information about a specifed data center (or all data centers if none are supplied) and the results are displayed to the host output stream.
function Get-DataCenterList()
{
param([string]$dc = $null );
if ( $dc )
{
$dc_list = ,$dc;
}
else
{
$dc_list = (Get-F5.iControl).GlobalLBDataCenter.get_list();
}
Write-Host "Data Centers:";
if ( $dc_list )
{
$contacts = (Get-F5.iControl).GlobalLBDataCenter.get_contact_information($dc_list);
$locations = (Get-F5.iControl).GlobalLBDataCenter.get_location_information($dc_list);
$enabled_states = (Get-F5.iControl).GlobalLBDataCenter.get_enabled_state($dc_list);
$statuses = (Get-F5.iControl).GlobalLBDataCenter.get_object_status($dc_list);
$links = (Get-F5.iControl).GlobalLBDataCenter.get_link($dc_list);
$servers = (Get-F5.iControl).GlobalLBDataCenter.get_server($dc_list);
for($i=0; $i -lt $dc_list.Length; $i++)
{
Write-Host @"
--------------------
Data Center $($dc_list[$i])
Contact : $($contacts[$i])
Location : $($locations[$i])
Enabled State : $($enabled_states[$i])
Availability : $($statuses[$i].availability_status)
Enabled Status: $($statuses[$i].enabled_status)
Status Desc :$($statuses[$i].status_description)
"@
Write-Host " Links :";
for($j=0; $j -lt $links[$i].links.Length; $j++)
{
Write-Host " [$j] $($links[$i].links[$j])"
}
Write-Host " Servers :";
for($j=0; $j -lt $servers[$i].servers.Length; $j++)
{
Write-Host " [$j] $($servers[$i].servers[$j])"
}
}
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password
Data Centers:
--------------------
Data Center JoesRack
Contact : Joe Pruitt
Location : Joes Cube
Enabled State : STATE_ENABLED
Availability : AVAILABILITY_STATUS_BLUE
Enabled Status: ENABLED_STATUS_ENABLED
Status Desc : DC JoesRack: Checking
Links :
Servers :
[0] theboss2
Creating Data Centers
Creating a data center only requires you specify the name location and contact information. The Name is intended to be a descriptive name for the data center such as "New York 1" or "West Coast". The Location should be a description of the geographic area in which the data center resides such as "New York City - Building A". And the contact information is for the name of the individual responsible for managing the network at the data center.
The following Create-DataCenter function will take these parameters as input and pass them to the iControl GlobalLBDataCenter.create() method. After the data center is created, it's attributes will be queried with the Get-DataCenterList function.
function Create-DataCenter()
{
param([string]$name = $null,
[string]$location = $null,
[string]$contact = $null);
if ( $name -and $location -and $contact )
{
$dca = New-Object -TypeName iControl.GlobalLBDataCenterDataCenterAttribute;
$dca.name = $name;
$dca.location = $location;
$dca.contact = $contact;
(Get-F5.iControl).GlobalLBDataCenter.create( (,$dca) );
Get-DataCenterList $name;
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password create "Seattle DC" "Elliot Ave W" "Joe Pruitt" Data Centers: -------------------- Data Center Seattle DC Contact : Joe Pruitt Location : Elliot Ave W Enabled State : STATE_ENABLED Availability : AVAILABILITY_STATUS_BLUE Enabled Status: ENABLED_STATUS_ENABLED Status Desc : DC Seattle DC: Checking Links : Servers :
Deleteing Data Centers
Well, if you want to create a data center, odds are someday you will want to delete one. this can be accomplished with the iControl GlobalLBDataCenter.delete_data_center() method as illustrated in the following Delete-DataCenter function.
function Delete-DataCenter()
{
param([string]$name = $null);
if ( $name )
{
$dca = New-Object -TypeName iControl.GlobalLBDataCenterDataCenterAttribute;
(Get-F5.iControl).GlobalLBDataCenter.delete_data_center( (,$name) );
Get-DataCenterList;
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password delete "Seattle DC"
Data Centers:
--------------------
Data Center JoesRack
Contact : Joe Pruitt
Location : Joes Cube
Enabled State : STATE_ENABLED
Availability : AVAILABILITY_STATUS_BLUE
Enabled Status: ENABLED_STATUS_ENABLED
Status Desc : DC JoesRack: Checking
Links :
Servers :
[0] theboss2
Modifying the Data Center Contact
As I mentioned above, the contact refers to the individual who is responsible for managing the network at the data center. This property can be changed with the iControl GlobalLBDataCenter.set_contact_information() method as illustrated in the Set-DataCenterContact function below. After the contact is updated, the information about the given data center is then queried to verify that the contact information was changed.
function Set-DataCenterContact()
{
param([string]$name = $null, [string]$contact = $null);
if ( $name -and $contact )
{
(Get-F5.iControl).GlobalLBDataCenter.set_contact_information(
(, $name),
(, $contact)
);
Get-DataCenterList $name;
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password setcontact "Seattle DC" "Fred Garvin" Data Centers: -------------------- Data Center Seattle DC Contact : Fred Garvin Location : Elliot Ave W Enabled State : STATE_ENABLED Availability : AVAILABILITY_STATUS_BLUE Enabled Status: ENABLED_STATUS_ENABLED Status Desc : DC Seattle DC: Checking Links : Servers :
Modifying the Data Center Location
If you didn't get the location correct when you created the data center, you can easily change it with the iControl GlobalLBDataCenter.set_location_information() method. The Set-DataCenterLocation function works very similarly to the Set-DataCenterContact function as you'll see below.
function Set-DataCenterLocation()
{
param([string]$name = $null, [string]$location = $null);
if ( $name -and $location )
{
(Get-F5.iControl).GlobalLBDataCenter.set_location_information(
(, $name),
(, $location)
);
Get-DataCenterList $name;
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password setlocation "Seattle DC" "30 Rock" Data Centers: -------------------- Data Center Seattle DC Contact : Fred Garvin Location : 30 Rock Enabled State : STATE_ENABLED Availability : AVAILABILITY_STATUS_BLUE Enabled Status: ENABLED_STATUS_ENABLED Status Desc : DC Seattle DC: Checking Links : Servers :
Modifying the Data Center Enabled State
When you create a data center, you'll need to determine whether you want the data center enabled or not. The default value is enabled so if you want it disabled, you'll have to explicity call the iControl GlobalLBDataCenter.set_enabled_state() method as shown in the Set-DataCenterEnabledState function.
Resources associated with a data center are available only if the following criteria are met:
- The data center is enabled.
- The data center is avialable, based on metrics collected by the Global Traffic Manager.
You can enable or disable a data center, allowing you to remove a data center temporarily (for a maintenance window) from the Global Traffic Manager's load balancing operations.
function Set-DataCenterEnabledState()
{
param([string]$name = $null, [string]$state = $null);
if ( $name -and $state )
{
$EnabledState = "STATE_DISABLED";
if ( $state -eq "enabled" ) { $EnabledState = "STATE_ENABLED"; }
(Get-F5.iControl).GlobalLBDataCenter.set_enabled_state(
(, $name),
(, $EnabledState)
);
Get-DataCenterList $name;
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password setstate "Seattle DC" disabled Data Centers: -------------------- Data Center Seattle DC Contact : Fred Garvin Location : 30 Rock Enabled State : STATE_DISABLED Availability : AVAILABILITY_STATUS_BLUE Enabled Status: ENABLED_STATUS_DISABLED Status Desc : DC Seattle DC: Checking : disabled directly Links : Servers :
Querying Data Center Statistics
Statistics are available for the data center by calling the iControl GlobalLBDataCenter.get_statistics() method. The following Get-DataCenterStatistics function calls that method and prints out the statistics such as CPU usage, available memory, throughput and connections.
function Get-DataCenterStatistics
{
param([string]$name = $null);
if ( $name )
{
$DataCenterStats = (Get-F5.iControl).GlobalLBDataCenter.get_statistics( (,$name) );
$stats = $DataCenterStats.statistics[0];
Write-Host "Statistics for Data Center '$(${stats}.data_center)'"
foreach ($stat in $stats.statistics)
{
$val = Convert-To64Bit $stat.value.high $stat.value.low;
Write-Host " " ("{0,-44}" -f ${stat}.type) "=" $val
}
}
}
PS C:\> .\PsGtmDataCenter.ps1 bigip username password getstatistics "Seattle DC" Statistics for Data Center 'Seattle DC' STATISTIC_GTM_METRICS_CPU_USAGE = 0 STATISTIC_GTM_METRICS_MEMORY_AVAILABLE = 0 STATISTIC_GTM_METRICS_BITS_PER_SECOND_IN = 0 STATISTIC_GTM_METRICS_BITS_PER_SECOND_OUT = 0 STATISTIC_GTM_METRICS_PACKETS_PER_SECOND_IN = 0 STATISTIC_GTM_METRICS_PACKETS_PER_SECOND_OUT = 0 STATISTIC_GTM_METRICS_TOTAL_CONNECTIONS = 0
Utility Functions
The Convert-To64Bit function will take as input the low and high 32 bit values from the iControl Common.UInt64 structure returned in the get_statistics() method.
function Convert-To64Bit()
{
param($high, $low);
$low = [Convert]::ToString($low,2).PadLeft(32,'0')
if($low.length -eq "64")
{
$low = $low.substring(32,32)
}
return [Convert]::ToUint64([Convert]::ToString($high,2).PadLeft(32,'0')+$low,2);
}
Conclusion
Now you have all the tools to automate the monitoring and management of your Global Traffic Manager's Data Centers.
The full source code for this application can be found under the PsGtmDataCenter entry in the iControl CodeShare.