7 Configuring Oracle Traffic Director

This chapter describes how to configure Oracle Traffic Director (OTD) in WebLogic Server Multitenant (MT). You can use either Fusion Middleware Control (FMWC) or WLST to configure Oracle Traffic Director, as described in this chapter. The chapter refers to the Oracle Traffic Director documentation and online help for additional information as appropriate.

This chapter includes the following sections:

Configuring Oracle Traffic Director: Overview

In a typical deployment scenario, Oracle Traffic Director distributes incoming client requests to Oracle WebLogic Server. In a WLS MT environment, OTD distributes incoming client requests to WLS MT partitions by coordinating its configuration with WLS MT partition management, automatically and without any explicit user action. However, to employ OTD multitenant support, you must perform an initial, one-time OTD configuration as described in the following sections.

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 the OTD domain will distribute the client requests to multiple WebLogic Server MT domains that exist on different hosts. Even though Oracle Traffic Director is in separate domain, it must be collocated with WebLogic Server for its management. For more information, see "Selecting an Oracle Traffic Director Domain Configuration" in Installing Oracle Traffic Director.

  • Oracle WebLogic Server MT and Oracle Traffic Director in a single domain

    In this topology, Oracle Traffic Director will be in the same domain as the WebLogic Server MT domain. The Oracle Traffic Director instance will exist in the same WebLogic Server MT domain and distribute the client requests to it. In this topology also, OTD must be collocated with WebLogic Server MT for its management. For more information, see "Selecting an Oracle Traffic Director Domain Configuration" in Installing Oracle Traffic Director.

In summary, you must:

Oracle Traffic Director Partitions

When you create a WLS MT partition using FMWC, 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. For more information, 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 same as the partition name itself.

You can view and manage logs using Fusion Middleware Control and WLST. For more information, see "Viewing Logs Using Fusion Middleware Control" and "Viewing Logs Using WLST" in Administering Oracle Traffic Director.

Configuring Oracle Traffic Director: Main Steps

This section describes the main steps to create the domain and configuration for Oracle Traffic Director in a WLS MT environment. It contains the following sections:

Creating the Domain for Oracle Traffic Director

In order to create an Oracle Traffic Director MT configuration and instance, you must first create a WLS MT domain and extend it for OTD using the restricted JRF template. Then using either WLST or FMWC, you can create OTD 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 OTD domain on m1 and WLS MT domain on m2:

    Create the OTD domain on m1 as follows:

    1. Install WLS MT+JRF in $ORACLE_HOME.

    2. Install OTD in the same $ORACLE_HOME.

    3. Invoke the Configuration Wizard.

    4. Select the Oracle Traffic Director - Restricted JRF template for OTD and proceed with the domain creation.

    With these steps you will be creating a WLS MT domain and extending it for OTD, so that you can proceed with OTD configurations and instances creation. Note that even in the OTD domain, WLS MT+JRF must be installed and the WLS MT domain must be created and extended for OTD.

    To create the WLS MT domain on m2:

    1. Install WLS MT in $ORACLE_HOME (there is no need for WLS MT+JRF).

    2. Invoke the Configuration Wizard.

    3. Create a basic WLS MT domain.

  • In a collocated domain, you install Oracle Traffic Director into the same ORACLE_HOME where you have installed Oracle WebLogic Server MT.

    For example, if you want to have both OTD and WLS MT in a single domain on machine m1:

    1. Install WLS MT+JRF in $ORACLE_HOME.

    2. Install OTD in the same $ORACLE_HOME.

    3. Invoke the Configuration Wizard.

    4. Select the Oracle Traffic Director - Restricted JRF template for OTD and proceed with the domain creation.

    In this deployment scenario, both WLS MT and OTD are in the same domain and OTD will manage the WLS MT partitions that are created within this domain.

Domain Selection

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 OTD domain (actually, a WLS MT domain that is extended for OTD), you must create a bootstrap Oracle Traffic Director configuration using Fusion Middleware Control or WLST, as described in the following sections.

Using Fusion Middleware Control to Create the Configuration and Instance

For detailed information on creating an Oracle Traffic Director MT configuration and instance using FMWC, 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 detailed information on 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 OTD runtime must be registered in the WLS MT domain. Using FMWC, login to the WLS MT domain before registering the OTD runtime.
  1. From the WebLogic Domain drop-down menu, select Environment > OTD Runtimes.

  2. 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 OTD runtime name, but you must select the same runtime name when creating a load balancer configuration for the WLS MT partition during partition creation.

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

Note:

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

Configuring Oracle Traffic Director: Related Tasks and Links

Using the LCM orchestration, only the OTD artifacts that are required to successfully distribute incoming client requests to WLS MT partitions will be 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 SSL for OTD, creating and managing failover groups in OTD, and such, must be done explicitly using the OTD administration interfaces. For more information, see Administering Oracle Traffic Director.

Oracle Traffic Director: Troubleshooting

The following section provides general debugging tips, frequently asked questions, and corrective actions you can take if WLS MT and OTD components become unsynchronized.

Before associating OTD with a WLS MT partition, make sure of the following:

Frequently Asked Questions

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

  • Can I use an existing OTD configuration for MT?

    Yes. However, the existing configuration name must be specified while registering the OTD runtime with the LCM, using the runtime property called configuration. If it is not specified, the name will default to mt.

  • How do I check whether OTD is successfully associated with a WLS MT partition?

    If the association is successful, OTD artifacts such as virtual server, route and such, will be created for the WLS MT partition in OTD.

    Invoke otd_listPartitions and otd_listResourceGroups WLST commands in the OTD domain to verify.

  • Is it necessary to create an OTD partition explicitly if I use the low level REST APIs?

    Yes. Fusion Middleware Control implicitly creates the OTD partition, but the low level REST APIs do not.

    The OTD partition name must be the same as the WLS MT partition name.

    Note that the OTD partition is not a functional artifact. It is only used to logically group all the OTD artifacts that serve requests to a WLS MT partition.

  • How can I determine whether OTD is notified by the LCM?

    The OTD plugin 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 OTD plugin?

    Set the WLS MT Administration Server domain log level to Debug.

    • In the WLS 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 hostname and uri-prefix value of a virtual target that a WLS MT partition is targeted to but OTD did not get updated. Why?

    The hostname and uri-prefix of a virtual target are non-dynamic attributes which require a partition restart to be effective. Restart the WLS MT partition and OTD will get updated.

  • I have added a new resource group to the existing WLS MT partition but OTD did not get updated. Why?

    This is a known issue. For more information, see "Oracle Traffic Director is Not Being Updated With Resource Group Changes" in Release Notes for Oracle WebLogic Server.

  • How can I synchronize WLS MT and OTD if they become out of sync?

    Invoke 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 WLS MT and OTD?

    Dissociate and then re-associate the WLS MT partition with OTD.

    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 FMWC:

    • Navigate 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 OTD 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.