21 Configuring Load Balancing Using the Proxy

Administration tasks can be performed that are related to load balancing using the proxy dsconfig or Oracle Unified Directory Services Manager (OUDSM).

The following topics describe how to perform administration tasks:

Note:

21.1 Configuring Load Balancing Using the dsconfig Command

The dsconfig command is used to configure load balancing, to create a workflow element, and to create an algorithm and routes.

The following topics describe how to configure load balancing using dsconfig command:

21.1.1 Configuring Load Balancing using the dsconfig Command

A load balancing workflow element can only have one load balancing algorithm. However, the same load balancing algorithm is used by all the load balancing routes in the deployment. You can configure load balancing using the dsconfig command.

To forward client requests to remote LDAP servers using load balancing, you need the following elements:

  • A load balancing workflow element

  • A load balancing algorithm

  • A load balancing route, for each remote LDAP server

The following examples describe how to configure load balancing using the dsconfig command. All of the examples specify the proxy hostname (-h), the proxy admin port (-p), the bind DN (-D), and the bind password file (-j), and use the -X option to trust all certificates.

  1. Create a load balancing workflow element. See Creating a Load Balancing Workflow Element.
  2. Create a load balancing algorithm. See Creating a Load Balancing Algorithm.
  3. Create one load balancing route for each load balancing workflow element. See Creating Load Balancing Routes.

21.1.2 Creating a Load Balancing Workflow Element

To configure load balancing, you must create a load balancing workflow element using the dsconfig create-workflow-element command.

Follow the below given example to create a workflow element:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-workflow-element \
  --element-name load-bal-we1 \
  --type load-balancing \
  --set enabled:true

To create a load balancing workflow element, the type must be load-balancing. The name of the workflow element is defined by element-name, in this example load-bal-we1.

21.1.3 Creating a Load Balancing Algorithm

To determine how the requests will be forwarded in a load balancing deployment, you must configure the load balancing algorithm. The load balancing algorithm set determines how client requests will be dispatched across the pool of remote LDAP servers.

The possible load balancing types are: failover, optimal, proportional, or saturation.

To create the load balancing algorithm, you must have a load balancing workflow element. See Creating a Load Balancing Workflow Element.

Create a load balancing algorithm using the dsconfig create-load-balancing-algorithm command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-load-balancing-algorithm \
  --element-name load-bal-we1 \
  --type failover

To create a load balancing algorithm, you must indicate the type as proportional, optimal, failover, or saturation. The name of the workflow element is defined by element-name, in this example load-bal-we1.

21.1.4 Creating Load Balancing Routes

You should have one load balancing route per data source. Before you create a load balancing route, the load balancing workflow element and load balancing algorithm must already be created.

To create a load balancing route, use the dsconfig create-load-balancing-route command. For example:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  create-load-balancing-route \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --type failover \
  --set workflow-element:proxy-we1 \
  --set add-priority:1 \
  --set bind-priority:2 \
  --set compare-priority:2 \
  --set delete-priority:1 \
  --set extended-priority:2 \
  --set modify-priority:1 \
  --set modifydn-priority:1 \
  --set search-priority:2 

In this example, load-bal-route1 is the name of the new load balancing route, load-bal-we1 is the name of the existing load balancing workflow element, and proxy-we1 is the name of the LDAP proxy workflow element. The type must be the same as the one defined by the load balancing algorithm associated, in this case failover.

The properties set (in this case priority) are related to the type of load balancing created. For more information about the properties of the routes, linked to the algorithm type see Modifying Load Balancing Properties.

21.1.5 Modifying Load Balancing Properties

After a load balancing deployment has been set up, you can modify certain properties, such as the priority, weight, and saturation threshold. Most of these properties are changed at the load balancing route level.

The following sections describe the different settings possible in a load-balancing deployment:

21.1.5.1 Modifying Load Balancing Properties

You can modify the following load balancing properties, depending on the load balancing algorithm:

Failover Optimal Proportional Saturation Search Filter

add-priority

alert-threshold

add-weight

alert-threshold

priority

bind-priority

saturation-precision*

bind-weight

priority

allowed-attributes

compare-priority

workflow-element

compare-weight

threshold

prohibited-attributes

delete-priority

delete-weight

saturation-precision*

workflow-element

extended-priority

extended-weight

workflow-element

modify-priority

modify-weight

modifydn-priority

modifydn-weight

search-priority

search-weight

workflow-element

workflow-element

switch-back flag

* saturation precision is a property of the LDAP server extension.

To modify load balancing route properties, use the dsconfig set-load-balancing-route-prop command.

New routes can be added on a running algorithm, or routes can be deleted or have their priorities modified without the need to restart the server.

Note:

You cannot modify the load balancing algorithm type.

To change a failover load balancing deployment to a proportional one, for example, you must create a new load balancing deployment. See Configuring Load Balancing Using the dsconfig Command.

21.1.5.2 Setting the Priority in a Failover Algorithm

In a load balancing deployment that uses the failover algorithm, you can modify the proxy workflow element to change the route that is used, as well as the priority of the route for a given operation type.

In a failover algorithm, a priority of 1 is the highest priority and indicates the main route that will be used for a specific operation type. A route with priority 2 (or more) is the secondary route used in case of failure on the primary route. The priority is set for each operation type. This means that a route with a priority of 1 for Add operations, can have a priority of 2 for Bind and Search operations.

For example, if the route load-bal-route1 was initially set as the main route with a priority of 1 for Add operations, but you now want to make it the backup route, you can set the priority to 2 using the following command.

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1
  --set add-priority: 2

Note:

If two routes have the same priority for a given operation type, the choice of the active route which treats the request is random.

21.1.5.3 Setting the switch-back Flag

After failover in a load balancing deployment, the backup route continues to handle all incoming requests, even after the priority server that had failed becomes available.

Switch-back or failback to the primary route does not automatically occur unless the switch-back flag has been set to true. By default, the switch-back flag is set to false.

The switch-back flag is an advanced property. To set the switch-back flag to true, do the following:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  --advanced set-load-balancing-algorithm-prop \
  --element-name load-bal-we1 \
  --set switch-back:true
21.1.5.4 Setting the Saturation Precision for the Optimal or Saturation Algorithm

In a load balancing deployment that uses the optimal or the saturation algorithm, you can set the saturation precision level.

The saturation precision is the delta between two saturation levels, and is used to determine the route with the lowest saturation level. By default, the saturation precision level is set to 5.

If you find that the saturation precision level is too low, and that the routes are changing too frequently, you can modify the saturation precision level as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  --advanced set-extension-prop \
  --extension-name proxy1 \
  --set saturation-precision:10
21.1.5.5 Setting the Weight of a Proportional Algorithm

Once you have created a load balancing deployment using the proportional algorithm, you can modify the proxy workflow element to change the route used, as well as the weight of a route.

The weight can be different for each operation type. The value of the weight should be 0 or more, were 0 indicates that the route will not be used for the specified operation.

Using the interactive mode of dsconfig, you can see that the following properties can be modified:

>>>> Configure the properties of the Proportional Load Balancing Route

        Property          Value(s)
        ---------------------------
    1)  add-weight        1
    2)  bind-weight       1
    3)  compare-weight    1
    4)  delete-weight     1
    5)  extended-weight   1
    6)  modify-weight     1
    7)  modifydn-weight   1
    8)  search-weight     1
    9)  workflow-element  proxy-we1

For example, if you initially set all your routes to a weight of 1 on all operations, then all the servers will handle an equal ratio of operations. However, if you want a remote LDAP server to handle more search requests than the other servers in the deployment, then you can set its search-weight to a higher value, such as 5. To do so, use the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set search-weight:5

Note:

To modify the weight for all operations, you must modify the weight for each operation individually.

To modify load-bal-route1 to handle twice as many operations as the other route, you would set the weight of all operations to 2 (assuming the weight on the other route is set to 1). In other words, run the command as follows:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set add-weight:2 \
  --set bind-weight:2 \
  --set compare-weight:2 \
  --set delete-weight:2 \
  --set extended-weight:2 \
  --set modify-weight:2 \
  --set modifydn-weight:2 \
  --set search-weight:2 

If the weight is set to 0 for any operations, the route will not perform the specified operation. For example, if add-weight is set to 0, then load-bal-route1 will not forward any add requests to the associated remote LDAP server. If all configured routes indicate a weight of 0 for a specific operation, that operation will not be supported.

21.1.5.6 Setting the Threshold for a Saturation Algorithm

Once you have created a load balancing deployment using the saturation algorithm, you can modify the proxy workflow element used, the priority of the route, the saturation threshold, and the saturation threshold alert.

With a saturation algorithm, requests are distributed based on two criteria: the priority of the server and the saturation threshold of the server. The saturation threshold is the limit at which the server is considered “maximized" and service may become degraded. In a load balancing deployment with saturation algorithm, requests are sent to the server with the highest priority (1) until the server reaches the saturation threshold indicated.

For example, if you indicate load-bal-route1 as the server with the highest priority, with a threshold of 80%, all requests will be sent to load-bal-route1 until its saturation threshold goes over 80%. Once it exceeds 80%, then requests are routed to the next server in the priority list.

>>>> Configure the properties of the Saturation Load Balancing Route

        Property          Value(s)
        ---------------------------
    1)  alert-threshold   85
    2)  priority          1
    3)  threshold         80
    4)  workflow-element  proxy-we1

To modify the saturation threshold, use the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set threshold:90

In this example, the saturation threshold has been set to 90%.

21.1.5.7 Setting the Saturation Threshold Alert

You can use the saturation threshold alert to specify at which point the system administrator will receive a notification indicating that the server has passed the saturation limit.

Generally, the saturation threshold alert is set higher than the saturation limit to indicate if the saturation continues to increase past the saturation threshold (which may indicate a problem). You should set the alert with an acceptable buffer, because there may be a short delay in which saturation continues to increase slightly before requests are forwarded to another route.

To modify the saturation threshold, use the following command:

$ dsconfig -h localhost -p 4444 -D "cn=Directory Manager" -j pwd-file -X -n \
  set-load-balancing-route-prop \
  --element-name load-bal-we1 \
  --route-name load-bal-route1 \
  --set alert-threshold:85

To perform preventative actions, you can set the saturation threshold alert to a value that is lower than the saturation threshold. (For example, if the main route is a set of load balanced servers, then you could add one or more servers to that set of servers as a preventive action.) This may imply receiving notifications even in cases where the saturation threshold is not reached. That is, a saturation threshold alert is sent, but the saturation limit drops and does not reach the saturation threshold. However, the requests will only be sent to the next priority route when the saturation threshold is reached.

For more information on setting the notification message, see Configuring Alerts and Account Status Notification Handlers.

21.1.5.8 Setting Client Connection Affinity

When you define a client connection affinity, requests from a specified client connection are routed to the same server, bypassing the specified load balancing algorithm. Client connection affinity is set at the network group level.

To set client connection affinity, use the dsconfig create-network-group-qos-policy command. For more information, see Creating a Network Group Quality of Service Policy.

Example of Client Connection Affinity Rejected

When you set the client connection affinity, the load balancing algorithm is bypassed if the defined weight constraints are respected.

For example, assume that the following routes are set with the following weights:

  • LB-route1: add=10, search= 0

  • LB-route2: add=0, search=10

It is clear that LB-route1 receives all the add requests, and LB-route2 receives all the search requests.

Assume that the load balancing deployment in this example is set with a client connection affinity of all-requests-after-first-write-request. If the load balancing deployment receives the following string of requests: Add, Search, Add, typically, the client connection affinity would send the Search request to the same route (LB-route1) as the first Add request. However, in this case, since Search requests are not allowed on LB-route1, the load balancing algorithm is not bypassed by the client affinity.

21.1.5.9 Deleting Load Balancing Elements

This section introduces you to the concept of deleting load balancing elements.

To delete a complete load balancing workflow (including workflow element, algorithm, and routes), you need only delete the load balancing workflow element. When you delete a load balancing workflow element, the associated load balancing algorithm and routes are silently deleted.

21.2 Configuring Load Balancing Using OUDSM

If you have set up a proxy server instance without configuring either load balancing or distribution, you can configure load balancing by using OUDSM.

Before you begin, it is useful to understand the components comprise a load balancing deployment. For more information, see Configuration 1: Simple Load Balancing.

To configure load balancing by using OUDSM:

  1. Connect to the proxy server from OUDSM, as described in Connecting to the Server Using OUDSM.
  2. Select the Home tab.
  3. Under the Configuration item, select Set up Load Balancer.
  4. On the Load Balancing: Backend Servers screen, complete the following information:
    • In the Load Balancing Name field, provide a name for this load balancing workflow element.

    • Click Add to provide the connection details of at least two replicated back end LDAP servers across which client requests will be balanced.

      OUDSM attempts to connect to these back end LDAP servers, to verify that they are accessible. If the connection attempt is unsuccessful, you are prompted to use the server details anyway, or to verify the connection details.

  5. When you have added all the back end LDAP servers, click Next to continue.
  6. On the Load Balancing: Options screen, complete the following information:
    • Select the Load Balancing Algorithm.

    • Depending on the load balancing algorithm you have selected, specify the relative weight or priority for each back end LDAP server.

    For information about the load balancing algorithms, see Overview of Load Balancing Using the Proxy.

  7. When you have specified the load balancing options, click Next to continue.
  8. On the Load Balancing: Naming Contexts screen, click Add to specify at least one naming context, or suffix, that will be handled by this proxy instance.
  9. When you have added all of the required naming contexts, click Next to continue.
  10. On the Load Balancing Setup: Summary screen, review the load balancing configuration and click Finish to complete the configuration.

When you have configured load balancing, you can modify any aspect of the configuration on the OUDSM Configuration tab.