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.