Entering maintenance mode for Liberty collectives

Enter maintenance mode before you perform diagnostic tests, maintenance, or tuning, on a host or server. Maintenance mode can prevent the disruption of client requests by routing client traffic around a server that is in maintenance mode, to another server.

About this task

When a server that is a scaling member is in maintenance mode, the scaling controller cannot start or stop that server. The server does not count toward the minimum or maximum running instance settings for the cluster.

Note: To achieve the full advantages of using maintenance mode in a Liberty collective, it is recommended that you enable the dynamic routing feature, auto scaling feature, or both of these features. For more information about the dynamic routing and auto scaling features, see Setting up dynamic routing for Liberty collectives and Setting up auto scaling for Liberty collectives.

When a host is in maintenance mode, the scaling controller cannot provision a new server on that host.

You can enter maintenance mode on a server that is joined to a collective or on a host that is registered to a collective.

You can use maintenance mode to alter the routing of requests by a web server that is enabled for Intelligent Management.

Entering a server or a host into maintenance mode is a persistent change. A server or host remains in maintenance mode even if the server is restarted until the mode is explicitly changed.

Procedure

Use the collective enterMaintenanceMode command to place a server or a host and its servers into maintenance mode.
```
wlp/bin/collective enterMaintenanceMode 
  --host=controllerHostName
  --port=controllerHttpsPortNumber
  --user=adminUser
  --password=adminPassword
  --hostName=serverHostName
 [--usrDir=serverUserDirectory]
 [--server=serverName]
 [--break]
 [--force]
```
To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.
```
wlp/bin/collective enterMaintenanceMode --controller=adminUser:adminPassword@controllerHostName:controllerHttpsPortNumber --hostName=serverHostName [--usrDir=serverUserDirectory]
 [--server=serverName][--break][--force]
```
The --host and --port arguments identify which collective controller can process the command. The --user and --password arguments are the administrative user ID and password for authenticating with the controller.

The --hostName, --usrDir, and --server arguments identify the server to be placed into maintenance mode. If you want to place a host and its servers into maintenance mode, provide the --hostName argument only and omit the --usrDir and --server arguments.

By default, the web server continues to send requests with affinity to a server in maintenance mode. Use --break to stop any traffic from being routed to the server, including requests with affinity to the server.

The scaling controller starts another server to replace each scaling member that is placed into maintenance mode. Another server will be started to meet the minimum number of instances of the cluster or to meet current workload demand. By default, if the scaling controller cannot find another server to act as a replacement the server is not placed into maintenance mode. Use the --force argument to cause a server to be placed into maintenance mode even if no replacement server is available.

Use the collective exitMaintenanceMode command to take a server or a host and its servers out of maintenance mode.

wlp/bin/collective exitMaintenanceMode 
  --host=controllerHostName
  --port=controllerHttpsPortNumber
  --user=adminUser
  --password=adminPassword
  --hostName=serverHostName
 [--usrDir=serverUserDirectory]
 [--server=serverName]

To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

wlp/bin/collective exitMaintenanceMode --controller=adminUser:adminPassword@controllerHostName:controllerHttpsPortNumber --hostName=serverHostName
[--usrDir=serverUserDirectory][--server=serverName]

Use the collective getMaintenanceMode command to display whether a server or a host and its servers are in maintenance mode.

wlp/bin/collective getMaintenanceMode 
  --host=controllerHostName
  --port=controllerHttpsPortNumber
  --user=adminUser
  --password=adminPassword
  --hostName=serverHostName
 [--usrDir=serverUserDirectory]
 [--server=serverName]

To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

wlp/bin/collective getMaintenanceMode --controller=adminUser:adminPassword@controllerHostName:controllerHttpsPortNumber --hostName=serverHostName 
[--usrDir=serverUserDirectory][--server=serverName]

Example

In this example, the hostc has a collective controller. The collective controller has the scaling controller and dynamic routing features enabled. In the server.xml file of the scaling controller, the minimum number of active cluster members is set to 1. Host1 has two started cluster members, memberA1 for cluster A and memberB1 for cluster B. Host2 has one stopped cluster member, memberA2 for cluster A. All cluster members have the scaling member feature enabled. A web server that is enabled for Intelligent Management also exists, which is routing requests to the cluster members.

To put host1 into maintenance mode, enter the following command:

wlp/bin/collective enterMaintenanceMode 
  --host=hostc 
  --port=controller1HttpsPortNumber
  --user=adminUser
  --password=adminPassword
  --hostName=host1

To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

wlp/bin/collective enterMaintenanceMode --controller=adminUser:adminPassword@hostc:controller1HttpsPortNumber --hostName=host1

The command issues the following response:

Successfully enter maintenance mode for host1.
An alternate server must be started. Maintenance mode will be set for memberA1 when the alternate server is started.
Could not enter maintenance mode for memberB1 because an alternate server is not available.

The scaling controller starts memberA2 as a replacement for memberA1. After memberA2 is started, then memberA1 is placed into maintenance mode. The web server no longer routes HTTP requests to memberA1.

The scaling controller cannot replace memberB1, therefore the member is not placed into maintenance mode. You can run the command again by using the --force argument to force memberB1 to be placed into maintenance mode, which can affect the performance of the requests running in clusterB.

What to do next

The health controller also uses server maintenance mode as an action that is taken when the health policy is breached. For example, if you are using an excessive response time condition, and the response time exceeds the specified average response time threshold for a server, then the server can move to maintenance mode.