Manage Policy Server Load Distribution

Contents
casso127
Contents
1
To help prevent service interruptions,
CA Single Sign-On
includes a failover feature. If the primary Policy Server fails and failover is enabled, a backup Policy Server takes over policy operations. Beginning with
CA Single Sign-On
v6.0, failover can occur not only between Policy Servers, but between groups, or
clusters
, of Policy Servers.
The cluster functionality also improves server performance by providing dynamic load balancing between the servers in a cluster. With dynamic load balancing, policy operations are automatically distributed between the available servers in a cluster according to the performance capabilities of each server.
A host configuration can be associated with one or more Policy Servers, or with one or more clusters of Policy Servers, depending on how you define your host configuration object:
  1. Clustered servers
    • Call AddCluster() for each cluster to create in the host configuration.
    • In the PolicyMgtCluster object returned from AddCluster(), call AddServer() to populate the cluster with servers.
    Behavior: Failover occurs between clusters of servers if multiple clusters are defined. Also, requests to servers within a cluster are sent according to the improved performance-based load-balancing techniques introduced with Agent API v6.0.
  2. Non-clustered servers
    • Call AddServer() for each non-clustered server to create in the host configuration.
    Behavior: Behavior is the same as in v5.x installations—that is, you can enable failover among the servers associated with a host configuration (set EnableFailover() to 1), or you can enable round-robin behavior among the servers (set EnableFailover() to 0).
    When round-robin behavior is enabled, the improved performance-based load-balancing techniques introduced with Agent API are used.
You cannot mix clustered and non-clustered servers in a host configuration.
Cluster Configuration
A cluster is stored in a host configuration object. Cluster failover occurs according to the following configuration values set in PolicyMgtHostConfig:
  • Failover threshold
    . The minimum percentage of servers within a cluster that must be available for Policy Server requests. If the number of available servers falls below the threshold, failover to the next cluster occurs.
    The failover threshold percentage applies to all clusters associated with the host configuration object.
    To determine the number of servers that the percentage represents in any given cluster, multiply the threshold percentage by the number of servers in the cluster, rounding up to the next highest integer. For example:
    • With a 60-percent failover threshold for a cluster of five servers, failover to the next cluster occurs when the number of available servers in the cluster falls below 3.
    • With a 61-percent failover threshold for the same cluster, failover occurs when the number of available servers falls below 4.
    Set through: FailoverThreshold().
  • Server timeout
    . The maximum time an agent will wait for a response from a server. If the wait time exceeds the server timeout value, the server is considered inactive, and failover to the next server occurs.
    If a server timeout occurs within a cluster, and the timeout causes the cluster’s failover threshold to be exceeded, failover to the next cluster occurs.
    Set through: RequestTimeout().
  • Sequence of cluster failover
    . When cluster failover occurs, 
    CA Single Sign-On
     sends subsequent Policy Server requests to the next cluster in the cluster sequence. Cluster sequence is determined by the order of cluster objects in the cluster array.
    Add clusters through: AddCluster(). The newly added cluster is added to the end of the cluster array.
    Retrieve the cluster array through: GetAllClusters().
    The order in which you add clusters to a host configuration object determines the failover sequence. The first cluster you add (that is, the first cluster in the cluster array) is the 
    primary cluster
    . This is the cluster that is used as long as the number of available servers in the cluster does not fall below the failover threshold. If there are not enough available servers in the primary cluster, failover to the next cluster occurs—that is, to the second cluster that was added to the host configuration object. If that cluster also fails, failover to the third cluster added to the host configuration object occurs, and so on.
When All Clusters Fail
If the number of available servers falls below the failover threshold in all clusters within a host configuration, policy operations do not stop. Requests are sent to the first cluster in the cluster sequence that has at least one available server.
For example, suppose a host configuration has two clusters—C1 containing three servers, and C2 containing five servers. The failover threshold for the host configuration is set at 60 percent. The following table shows the minimum number of servers that must be available within each cluster:
Cluster
Servers in Cluster
Percentage Failover Threshold
Numeric Failover Threshold (Minimum Available Servers)
C1
3
60
1
C2
5
60
3
 
If the number of available servers falls below the threshold in each cluster, so that C1 has no available servers and C2 has just two, the next incoming request will be dispatched to a C2 server with the best response time. After at least two of the three C1 servers are repaired, subsequent requests are load-balanced among the available C1 servers.
Agent API v6 is backwards-compatible with Agent API v5, allowing complete interoperability between v5/v6 agents and the v5/v6 Agent APIs.
Example: Create a host configuration
The following code creates a host configuration object and adds a number of clusters and servers:
use Netegrity::PolicyMgtAPI;
 
# Initialize the Policy Management API and create a Host Config object.
$pmgtapi = Netegrity::PolicyMgtAPI->New();
$session = $pmgtapi->CreateSession("SiteMinder", "password");
$hostconf = $session->CreateHostConfig("host", "description",
                                              false, 2, 2, 1, 30);
# Add two non-cluster servers. The Az, Auth and Acct ports are
# specified.
$hostconf->AddServer("1.1.1.1", 44443, 44442, 44441);
$hostconf->AddServer("2.2.2.2", 44443, 44442, 44441);
 
# Add two clusters with two servers in each cluster. One Policy
# Server port number is specified.
$clusterconf1 = $hostconf->AddCluster();
$clusterconf1->AddServer("1.1.1.1", 44443);
$clusterconf1->AddServer("2.2.2.2", 44443);
 
$clusterconf2 = $hostconf->AddCluster();
$clusterconf2->AddServer("3.3.3.3", 44443);
$clusterconf2->AddServer("4.4.4.4", 44443);
 
# Print configuration of all non-cluster servers in the Host
# Config object
@servers = $hostconf->GetAllServers();
foreach $server (@servers) {
    $address = $server->GetServerAddress(); 
    @ports = $server->GetServerPort();  
    print("Server: $address,@ports[0],@ports[1],@ports[2]\n");  
}
 
# Print all cluster servers
@clusters = $hostconf->GetAllClusters();
foreach $cluster (@clusters) {
    $num++; 
    foreach $server ($cluster->GetAllServers()) {   
    $address = $server->GetServerAddress(); 
    $port = $server->GetServerPort();   
    print("Cluster $num Server: $address,$port\n"); 
}
}
 
# Remove all clusters and non-cluster servers from host configuration
$hostconf->RemoveAllClusters();
$hostconf->RemoveAllServers();