Configuring Oracle Traffic Director

Configuring Oracle Traffic Director: Overview

To employ Oracle Traffic Director multitenant support, you must perform an initial, one-time Oracle Traffic Director configuration.

Consider the following deployment topologies:

Oracle WebLogic Server MT and Oracle Traffic Director in separate domains

In this topology, Oracle Traffic Director resides in a separate domain from the WebLogic Server MT domains. These domains can be on different hosts. The Oracle Traffic Director instance that exists in its domain distributes the client requests to multiple WebLogic Server MT domains that exist on different hosts. Even though Oracle Traffic Director is in a separate domain, it must be collocated with WebLogic Server for its management. See Setting up an Administration Domain in Administering Oracle Traffic Director.
Oracle WebLogic Server MT and Oracle Traffic Director in a single domain

In this topology, Oracle Traffic Director is in the same domain as the WebLogic Server MT domain. The Oracle Traffic Director instance exists in the same WebLogic Server MT domain and distributes the client requests to it. In this topology also, Oracle Traffic Director must be collocated with WebLogic Server MT for its management. See Setting up an Administration Domain in Administering Oracle Traffic Director.

In summary, you must:

Install Oracle Traffic Director, collocated with WebLogic Server MT, and create an Oracle Traffic Director domain. See Creating the Domain for Oracle Traffic Director.
Perform a one-time, initial Oracle Traffic Director configuration to enable Oracle Traffic Director multitenancy features. This includes creating an Oracle Traffic Director MT configuration and instance, and registering the Oracle Traffic Director runtime with the lifecycle manager (LCM). See Creating an Oracle Traffic Director MT Configuration and Instance and Registering the Oracle Traffic Director Runtime.
Use the registered Oracle Traffic Director runtime when creating a load balancer configuration for WebLogic Server MT partitions during partition creation. Upon completion, the LCM coordinates the orchestration with Oracle Traffic Director appropriately, as described in Lifecycle Management.

Oracle Traffic Director Partitions

When you create a WebLogic Server MT partition using Fusion Middleware Control, a corresponding Oracle Traffic Director partition is created for you. The Oracle Traffic Director partition is simply a grouping with the same name as the partition and the resource group. Fusion Middleware Control provides a summary table with the list of Oracle Traffic Director partitions to identify the Oracle Traffic Director artifacts that are mapped to partitions and resource groups. You can also list the Oracle Traffic Director partitions using WLST. See otd_listPartitions and otd_listResourceGroups in WebLogic Scripting Tool Command Reference for Oracle Traffic Director.

Oracle Traffic Director artifacts map to WebLogic Server MT artifacts as follows:

Each cluster maps to an origin-server pool.
The host names of a virtual target that is associated with the partitions and/or resource groups map to a virtual server.
The URI-prefix of the virtual target maps to a route within the virtual server corresponding to the host name of the virtual target.

For descriptions of Oracle Traffic Director artifacts, see Oracle Traffic Director Terminology in Administering Oracle Traffic Director.

Monitoring

Metrics are gathered for each partition. A system administrator can access the partition metrics using either Fusion Middleware Control or WLST. See Methods for Monitoring Oracle Traffic Director Instances in Administering Oracle Traffic Director.

Logging

Oracle Traffic Director has a separate access log for each partition. The access log file name for the partition is the same as the partition name itself.

You can view and manage logs using Fusion Middleware Control and WLST. See Viewing Logs Using Fusion Middleware Control and Viewing Logs Using WLST in Administering Oracle Traffic Director.

Configuring Oracle Traffic Director: Main Steps

To configure Oracle Traffic Director in a WebLogic Server MT environment, you must create an Oracle Traffic Director domain, an Oracle Traffic Director MT configuration and instance, and then register the Oracle Traffic Director runtime with the lifecycle manager (LCM).

Creating the Domain for Oracle Traffic Director

To create an Oracle Traffic Director MT configuration and instance, you must first create a WebLogic Server MT domain and extend it for Oracle Traffic Director using the restricted Oracle Java Required Files (JRF) template. Then, using either WLST or Fusion Middleware Control, you can create Oracle Traffic Director configurations and instances.

Create an Oracle WebLogic Server MT domain as follows:

In large enterprise deployments, where a single Oracle Traffic Director instance distributes client requests to multiple Oracle WebLogic Server MT domains, you will want to create separate domains for Oracle WebLogic Server MT and Oracle Traffic Director.

For example, using two machines (m1 and m2), if you want to have an Oracle Traffic Director domain on m1 and WebLogic Server MT domain on m2:

Create the Oracle Traffic Director domain on m1 as follows:
1. Install WebLogic Server MT with JRF in $ORACLE_HOME.
2. Install Oracle Traffic Director in the same $ORACLE_HOME.
3. Call the Configuration Wizard.
4. Select the Oracle Traffic Director - Restricted JRF template for Oracle Traffic Director and proceed with the domain creation.
With these steps you create a WebLogic Server MT domain and extend it for Oracle Traffic Director, so that you can proceed with Oracle Traffic Director configurations and instances creation. Note that even in the Oracle Traffic Director domain, WebLogic Server MT with JRF must be installed and the WebLogic Server MT domain must be created and extended for Oracle Traffic Director.

To create the WebLogic Server MT domain on m2:
1. Install WebLogic Server MT in $ORACLE_HOME (there is no need for WebLogic Server MT with JRF).
2. Call the Configuration Wizard.
3. Create a basic WebLogic Server MT domain.
In a collocated domain, you install Oracle Traffic Director into the same ORACLE_HOME where you have installed WebLogic Server MT.

For example, if you want to have both Oracle Traffic Director and WebLogic Server MT in a single domain on machine m1:
1. Install WebLogic Server MT with JRF in $ORACLE_HOME.
2. Install Oracle Traffic Director in the same $ORACLE_HOME.
3. Call the Configuration Wizard.
4. Select the Oracle Traffic Director - Restricted JRF template for Oracle Traffic Director and proceed with the domain creation.
In this deployment scenario, both WebLogic Server MT and Oracle Traffic Director are in the same domain and Oracle Traffic Director manages the WebLogic Server MT partitions that are created within this domain.

When using the Configuration Wizard to create the domain, you must select to create a new domain, and in the Templates dialog, you must select the Oracle Traffic Director - 12.2.1 Restricted JRF template.

For detailed steps to install and configuration the domain, see Oracle Traffic Director Installation Guide.

Creating an Oracle Traffic Director MT Configuration and Instance

After creating the Oracle Traffic Director domain (actually, a WebLogic Server MT domain that is extended for Oracle Traffic Director), you must create a bootstrap Oracle Traffic Director configuration using Fusion Middleware Control or WLST.

Using Fusion Middleware Control to Create the Configuration and Instance

For more information about creating an Oracle Traffic Director MT configuration and instance using Fusion Middleware Control, see Creating a Configuration Using Fusion Middleware Control and Creating Oracle Traffic Director Instances Using Fusion Middleware Control in Administering Oracle Traffic Director.

Using WLST to Create the Configuration and Instance

For more information about creating an Oracle Traffic Director MT configuration and instance using WLST, see Creating a Configuration Using WLST and Creating an Oracle Traffic Director Instance Using WLST in Administering Oracle Traffic Director.

Registering the Oracle Traffic Director Runtime

Using Fusion Middleware Control, register the Oracle Traffic Director runtime to enable the lifecycle events or operations.

Note:

The Oracle Traffic Director runtime must be registered in the WebLogic Server MT domain. Using Fusion Middleware Control, log in to the WebLogic Server MT domain before registering the Oracle Traffic Director runtime.

From the WebLogic Domain menu, select Environment > OTD Runtimes.
Click Register Runtime.

Specify a name for the new Oracle Traffic Director runtime and provide information (host, port and credentials) on where this runtime is located. You can specify any Oracle Traffic Director runtime name, but you must select the same runtime name when creating a load balancer configuration for the WebLogic Server MT partition during partition creation.

You also need to provide the name of an existing Oracle Traffic Director configuration that will be used for MT. For example, if you wanted to use the configuration that you created in Using Fusion Middleware Control to Create the Configuration and Instance, then you must specify the same name that you specified during the Oracle Traffic Director configuration creation.

Note:

In the Register Runtime dialog, you must specify the Admin Server host and port details of the Oracle Traffic Director domain and the (Oracle Traffic Director domain) Administration Server credentials.

Oracle Traffic Director: Troubleshooting

WebLogic Server provides general debugging tips, frequently asked questions, and corrective actions you can take if the WebLogic Server MT and Oracle Traffic Director components become unsynchronized.

Before associating Oracle Traffic Director with a WebLogic Server MT partition, verify the following:

The WebLogic Server MT Administration Server and Node Manager are up and running in an Oracle Traffic Director domain.
The WebLogic Server MT Administration Server is able to reach the Node Manager without any issues.
You have created an Oracle Traffic Director configuration and the corresponding instance to be used for MT. See Creating an Oracle Traffic Director MT Configuration and Instance.
You have registered the correct Oracle Traffic Director runtime with the lifecycle manager (LCM). See Registering the Oracle Traffic Director Runtime.

Frequently Asked Questions

The following responses address frequently asked questions and issues. These FAQs are relevant to configuring Oracle Traffic Director for MT and partition management using LCM with Oracle Traffic Director.

Can I use an existing Oracle Traffic Director configuration for MT?

Yes. However, the existing configuration name must be specified while registering the Oracle Traffic Director runtime with the LCM, using the runtime property called configuration. If it is not specified, then the name defaults to mt.
How do I check whether Oracle Traffic Director is successfully associated with a WebLogic Server MT partition?

If the association is successful, then Oracle Traffic Director artifacts such as virtual server, route and such, are created for the WebLogic Server MT partition in Oracle Traffic Director.

Call otd_listPartitions and otd_listResourceGroups WLST commands in the Oracle Traffic Director domain to verify a successful association.
Is it necessary to create an Oracle Traffic Director partition explicitly if I use the low-level Representational State Transfer (REST) APIs?

Yes. Fusion Middleware Control implicitly creates the Oracle Traffic Director partition, but the low-level REST APIs do not.

The Oracle Traffic Director partition name must be the same as the WebLogic Server MT partition name.

Note that the Oracle Traffic Director partition is not a functional artifact. It is used only to logically group all the Oracle Traffic Director artifacts that serve requests to a WebLogic Server MT partition.
How can I determine whether Oracle Traffic Director is notified by the LCM?

The Oracle Traffic Director plug-in will log debug information if it is notified by the LCM. A sample log message:
```
<[com.oracle.weblogic.lifecycle.plugin.otd.OTDUtil:log] OTDLifeyclePlugin : Associating OTD with the WLS MT partition> 
```
How do I enable debugging for the Oracle Traffic Director plug-in?

Set the WebLogic Server MT Administration Server domain log level to Debug.
- In the Oracle WebLogic Server Administration Console, select Environment > Servers > Logging > Advanced and set the required severity levels (Minimum severity to log, Log file severity level, and such) to Debug.
- Using WLST: cd('/Servers/AdminServer/Log/AdminServer') and set the required severity levels to Debug (cmo.setLoggerSeverity('Debug')).
I have changed the host name and URI-prefix value of a virtual target that a WebLogic Server MT partition is targeted to but Oracle Traffic Director did not get updated. Why?

The host name and URI-prefix of a virtual target are nondynamic attributes which require a partition restart to be effective. Restart the WebLogic Server MT partition to update Oracle Traffic Director.
I have added a new resource group to the existing WebLogic Server MT partition but Oracle Traffic Director did not get updated. Why?

This is a known issue. See Oracle Traffic Director Is Not Being Updated with Resource Group Changes in Release Notes for Oracle WebLogic Server.

How can I synchronize WebLogic Server MT and Oracle Traffic Director if they become unsynchronized?

Call the sync LCM REST API.

curl -v \
--user $WLS_DOMAIN_ADMIN_USERNAME:$WLS_DOMAIN_ADMIN_PASSWORD \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-X POST http://$WLS_DOMAIN_ADMIN_HOSTNAME:$WLS_DOMAIN_ADMIN_PORT/management/lifecycle/latest/environments/$ENVIRONMENT_NAME/sync

Note that you must replace the $ tokens appropriately.

What if the sync REST API does not synchronize WebLogic Server MT and Oracle Traffic Director?

Dissociate and then reassociate the WebLogic Server MT partition with Oracle Traffic Director.

Using the REST APIs:

To dissociate:

curl -v \
--user $WLS_DOMAIN_ADMIN_USERNAME:$WLS_DOMAIN_ADMIN_PASSWORD \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d '{ "partition1Name": "$WLSPartition_Name", "partition1RuntimeName" : "$WLS_RUNTIME_NAME", "partition2Name": "$OTDPartition_Name", "partition2RuntimeName": "$OTD_RUNTIME_NAME", "properties" :[]}' \
-X POST http://$WLS_DOMAIN_ADMIN_HOSTNAME:$WLS_DOMAIN_ADMIN_PORT/management/lifecycle/latest/environments/$ENVIRONMENT_NAME/dissociatePartitions

To associate:

curl -v \
--user $WLS_DOMAIN_ADMIN_USERNAME:$WLS_DOMAIN_ADMIN_PASSWORD \
-H X-Requested-By:MyClient \
-H Accept:application/json \
-H Content-Type:application/json \
-d '{ "partition1Name": "$WLSPartition_Name", "partition1RuntimeName" : "$WLS_RUNTIME_NAME", "partition2Name": "$OTDPartition_Name", "partition2RuntimeName": "$OTD_RUNTIME_NAME", "properties" :[]}' \
-X POST http://$WLS_DOMAIN_ADMIN_HOSTNAME:$WLS_DOMAIN_ADMIN_PORT/management/lifecycle/latest/environments/$ENVIRONMENT_NAME/associatePartitions

In Fusion Middleware Control:

Go to Domain Partition > Administration > Load Balancer Configuration.
Deselect the check box Use OTD for load balancing to dissociate.
Select the same check box to associate again.

Is there a separate log file for each Oracle Traffic Director partition?

Yes. The partition log file name is the same as the partition name (for example, <OTD_PARTITION_NAME>.log), which is located at <OTD_DOMAIN_HOME>/servers/<OTD_INSTANCE_NAME>/logs.

You can use the following WLST commands: otd_getPartitionAccessLogProperties and otd_setPartitionAccessLogProperties.

Configuring Oracle Traffic Director: Related Information

Using the LCM orchestration, only the Oracle Traffic Director artifacts that are required to successfully distribute incoming client requests to WebLogic Server MT partitions are configured automatically. These artifacts include virtual servers, origin-server pools (including the origin servers) and routes. Apart from this, all other configurations, such as enabling Secure Sockets Layer (SSL) for Oracle Traffic Director, creating and managing failover groups in Oracle Traffic Director and such, must be done explicitly using the Oracle Traffic Director administration interfaces. See Administering Oracle Traffic Director.