5 Managing Instances

An instance is an Oracle Traffic Director server running on an administration node, or on the administration server, and listening on one or more ports for requests from clients.

This chapter contains the following sections:

Creating Oracle Traffic Director Instances

You can create Oracle Traffic Director instances of a configuration by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Oracle Java Cloud Service creates an Oracle Traffic Director instance when you create an Oracle Java Cloud Service instance with a load balancer or add a load balancer to an Oracle Java Cloud Service instance. You need to create an instance only if you require additional instances.

Prerequisites for Creating Oracle Traffic Director Instances

To be able to create an instance, you should have defined a configuration (see Creating a Configuration). Creating an instance also requires an administration node. Oracle Java Cloud Service creates an administration node when you create a service instance with a load balancer or add a load balancer to an existing service instance.

Creating Oracle Traffic Director Instances Using the Administration Console

To create Oracle Traffic Director instances of a configuration by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to create an instance.
In the Common Tasks pane, click New Instance.
The New Instance wizard is displayed. The wizard lists the available administration nodes.
Note:
- For a host to be listed as an available administration node, it should be designated as an administration node.
- On an administration node, you can create only one instance of a particular configuration. So if an instance of the configuration that you are trying to deploy already exists on the administration node, the node is not displayed.
Select the check boxes corresponding to the administration nodes on which you want to create instances of the configuration. Then, click Next.
On the resulting screen of the wizard, review the list of administration nodes that you selected. Then, click Create Instance.

A message is displayed confirming the successful creation of the instance.
Click Close.

The Instances page is displayed, showing the instance that you just created.

Creating an Oracle Traffic Director Instance Using the CLI

To create one or more Oracle Traffic Director instances, run the create-instance command.

For example, the following command creates an instance of the configuration named soa on each of the nodes, apps2 and apps2.

tadm> create-instance --config=soa apps1 apps2
OTD-70201 Command 'create-instance' ran successfully.

For more information about create-instance, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

For each Oracle Traffic Director configuration that you instantiate on an administration node, a subdirectory named net-config_name is created in the INSTANCE_HOME subdirectory.

Viewing a List of Oracle Traffic Director Instances

You can view a list of Oracle Traffic Director instances by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Viewing a List of Oracle Traffic Director Instances Using the Administration Console

To view a list of the Oracle Traffic Director instances of a configuration by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to view instances.

The Instances page is displayed, showing the instances of the configuration, as shown in Figure 5-1.

Figure 5-1 List of Instances

Description of "Figure 5-1 List of Instances"

You can view the properties of an instance by clicking on its name.

Viewing a List of Oracle Traffic Director Instances Using the CLI

To view a list of the Oracle Traffic Director instances of a configuration, run the list-instances command, as shown in the following example:

tadm> list-instances --config=soa.example.com --verbose --all

node-name            instance-status   has-service
--------------------------------------------------
soa.example.com      started           false
adf.example.com      stopped           false

Starting, Stopping, and Restarting Oracle Traffic Director Instances

You can start, stop, and restart Oracle Traffic Director instances by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Starting, Stopping, and Restarting Oracle Traffic Director Instances Using the Administration Console

To start, stop, or restart Oracle Traffic Director instances by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to start, stop, or restart instances.
In the navigation pane, select Instances.
Click the Start/Restart or Stop button, as required, for the instance that you want to start, restart, or stop.

Note:

To start or restart all instances of the selected configuration, click Start/Restart Instances in the Common Tasks pane. To stop all instances of the configuration, click Stop Instances.
If a PKCS#11 token that provides the interface to the certificates database is protected with a pin (see Managing PKCS#11 Tokens), when you click Start/Restart or Start/Restart Instances, a prompt to enter the token pin is displayed. To proceed with starting the instances, you should enter the pins for the tokens that are protected with pins.

A message is displayed in the Console Messages pane confirming that the instances were started, stopped, or restarted.

Starting, Stopping, and Restarting Oracle Traffic Director Instances Using the CLI

To start, stop, or restart one or more Oracle Traffic Director instances of a configuration, run the start-instance, stop-instance, or restart-instance command.

For example, the following three commands start, restart, and stop the instances of the configuration soa on the nodes apps1.example.com and apps2.example.com.

tadm> start-instance --config=soa apps1.example.com apps2.example.com

tadm> restart-instance --config=soa apps1.example.com apps2.example.com

tadm> stop-instance --config=soa apps1.example.com apps2.example.com

If a PKCS#11 token that provides the interface to the certificates database is protected with a pin (see Managing PKCS#11 Tokens), when you run start-instance, a prompt to enter the token pin is displayed, as shown in the following example:

Enter password for token "internal">

To proceed with starting the instances, you should enter the pins.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.

Note:

Alternatively, you can use the following commands from within the instance directory to start, restart, and stop the instances:

> $INSTANCE_HOME/net-config_name/bin/startserv

> $INSTANCE_HOME/net-config_name/bin/restart

> $INSTANCE_HOME/net-config_name/bin/stopserv

Updating Oracle Traffic Director Instances Without Restarting

When you make changes to some configuration parameters, the running Oracle Traffic Director instances of the configuration need not be restarted for the changes in the configuration to take effect. You can dynamically reconfigure the Oracle Traffic Director instances to reflect the new configuration.

For a list of the parameters that support dynamic reconfiguration, see "Dynamic Reconfiguration" in the Oracle Traffic Director Configuration Files Reference.

You can dynamically reconfigure the running instances of a configuration by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Reconfiguring an Oracle Traffic Director Instance Using the Administration Console

To reconfigure an Oracle Traffic Director instance by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to reconfigure instances.
In the navigation pane, select Instances.
Click the Reconfigure button for the instance that you want to update dynamically.

A message is displayed in the Console Messages pane confirming that the instance was reconfigured.

Reconfiguring Oracle Traffic Director Instances Using the CLI

To reconfigure one or more Oracle Traffic Director instances of a configuration, run the reconfig-instance command.

For example, the following command reconfigures the instances of the configuration soa on the nodes apps1 and apps2.

tadm> reconfig-instance --config=soa apps1 apps2

For more information about reconfig-instance, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Note:

Alternatively, you can use the following command from within the instance directory:

> $INSTANCE_HOME/net-config_name/bin/reconfig

Deleting Oracle Traffic Director Instances

You can delete instances of a configuration by using either the administration console or the CLI.

Deleting an Oracle Traffic Director Instance Using the Administration Console

To delete an Oracle Traffic Director instance by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to delete instances.
In the navigation pane, select Instances.
Click the Delete button for the instance that you want to delete.

A message is displayed in the Console Messages pane confirming that the instance was deleted.

Deleting Oracle Traffic Director Instances Using the CLI

To delete Oracle Traffic Director instances of a configuration, run the delete-instance command.

For example, the following command deletes the instance of the configuration soa running on nodes apps1 and apps2.

tadm> delete-instance --config=soa apps1 apps2

For more information about delete-instance, see the Oracle Traffic Director Command-Line Reference or run the command with the --help option.

Controlling Oracle Traffic Director Instances Through Scheduled Events

As an administrator, if you have to manage a large number of configurations and their instances, repetitive tasks such as restarting and reconfiguring instances of each configuration individually can become tedious. You can schedule events for administrative tasks to be performed automatically at defined intervals; or on specific days of the week, times of the day, or dates of the month.

You can create and manage events by using either the administration console or the CLI.

Note:

The CLI examples in this section are shown in shell mode (tadm>). For information about invoking the CLI shell, see Accessing the Command-Line Interface.

Managing Events Using the Administration Console

To manage events by using the administration console, do the following:

Log in to the administration console, as described in Accessing the Administration Console.
Click the Configurations button that is situated at the upper left corner of the page.

A list of the available configurations is displayed.
Select the configuration for which you want to schedule events.
In the navigation pane, select Advanced Settings.

The Advanced Settings page is displayed.
Scroll down to the Scheduled Events section of the page.
It lists events that are currently scheduled for the configuration.
- To enable or disable an event, select the Enable/Disable check box.
- To delete an event, click the Delete icon.
- To create an event, click New Event.
  
  The New Configuration Event dialog box is displayed.
  
  Select the event that you want to schedule, and specify the interval or time at which the event should be performed, and then click OK.
A message, confirming the change, is displayed in the Console Messages pane.

In addition, the Deployment Pending message is displayed at the top of the main pane. You can either deploy the updated configuration immediately by clicking Deploy Changes, or you can do so later after making further changes as described in Deploying a Configuration.

Managing Events Using the CLI

Creating an event

To create an event, run the create-event command, as shown in the following examples.
```
tadm> create-event --config=soa --command=restart --interval=86400
tadm> create-event --config=soa --command=reconfigure --time=14:00
```
The first command schedules an event to restart all the instances of the configuration soa after every 86400 seconds.

The second command schedules an event to reconfigure all the instances of the configuration soa at 2 p.m. every day.

Note:

For the scheduled events to take effect, you should redeploy the configuration.

Viewing a list of events

To view a list of scheduled events, run the list-events command.

For example, the following command displays the events scheduled for instances of the configuration soa.

tadm> list-events --config=soa --verbose --all
command        enabled    day-of-month   month   day-of-week   time    interval
-------------------------------------------------------------------------------
restart        false      -              -       -             -       60
reconfig       true       -              -       -             -       60

Disabling an event

When you create an event, it is enabled automatically, unless you specified the --no-enabled option.

To disable an event, run the disable-event command, as shown in the following example:
```
tadm> disable-event --config=soa --command=restart --interval=86400
```
Enabling an event

To enable an event, run the enable-event command, as shown in the following example:
```
tadm> enable-event --config=soa --command=restart --interval=86400
```
Deleting an event

To delete an event, run the delete-event command, as shown in the following example:
```
tadm> delete-event --config=soa --command=restart --interval=86400
```

For the updated configuration to take effect, you should deploy it to the Oracle Traffic Director instances by using the deploy-config command.

For more information about the CLI commands mentioned in this section, see the Oracle Traffic Director Command-Line Reference or run the commands with the --help option.