Enter maintenance mode for Liberty collectives

Enter maintenance mode before performing 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.

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.

IBM recommends enabling dynamic routing, and/or auto scaling.

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

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

We 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.

  1. 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]

    Alternate syntax: 

      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. 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.

  2. 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]

    Alternate syntax: 

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

  3. 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]

    Alternate syntax: 

      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.

Put host1 into maintenance mode: 

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

Alternate syntax: 

    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. We can run the command again 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 we 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.


Related