Stopping or resuming workload distribution to particular members (QUIESCE and ENABLE)
At least one and possibly two methods exist to stop sending new workload requests to particular members, referred to as quiescing. Quiescing does not disrupt existing connections with the target applications, but does prevent new workload requests from being distributed to those members from load balancers. Requests sent directly to applications that do not go through the load balancer are unaffected by quiescing. Quiescing certain members can be useful for a planned outage of a particular system in the sysplex, a particular TCP/IP stack, a particular application, or a homogeneous group of applications, such as all HTTP servers. The first method of quiescing is done using the MODIFY procname,QUIESCE operator command available at each Agent. The second potential method is through the load balancer administrator, if the load balancer implementation supports this function. Only the MODIFY procname,QUIESCE command is described in detail in this topic.
The MODIFY procname,QUIESCE command is available only on the Agents, because they own the IP addresses that belong to TCP/IP stacks on that z/OS® system. Therefore, the scope of the quiesce operation cannot affect members that are not owned by the Agent that is issuing the command.
There are three major scopes or target options for the MODIFY procname,QUIESCE command:
- SYSTEM
Every member owned on that z/OS system can be quiesced
- TCPNAME=tcpname
Every member on one of the Agent's TCP/IP stacks can be quiesced
- PORT=portnum
All members using a particular port can be quiesced
The last target option, quiescing by port, enables you to refine the quiesce to an individual member instead of quiescing all members using the port. For more information on how to specify individual members using the Agent's MODIFY procname,QUIESCE command, see z/OS Communications Server: IP System Administrator's Commands.
When ready for new workloads, use the MODIFY procname,ENABLE command to make the quiesced members available again. Like the quiesce command, this command is only an Agent command, and also has the same target options as the quiesce command.
The quiesce and enable commands are hierarchical. The system level (SYSTEM target option) is at the top of the hierarchy, the stack level (TCPNAME=tcpname target option) is the next highest, and the member level (PORT=portnum target option) is the lowest.
- In the quiesce and enable hierarchy, a member quiesced at one level of the hierarchy cannot be enabled at a lower or higher level of the hierarchy. For example, if the MODIFY procname,QUIESCE,TCPNAME=tcpname command has been issued, a MODIFY procname,ENABLE,SYSTEM command or a MODIFY procname,ENABLE,PORT=portnum command will not be accepted.
- An enable command must be issued at the same level of the hierarchy as the last quiesce command that affected the member.
- When a member has been quiesced at one level of the hierarchy, it can be quiesced at a higher level of the hierarchy. This promotes the quiesce level of the member from the lower hierarchy level to the higher hierarchy level, and any history of it being quiesced at the lower level of the hierarchy is erased. When subsequently issuing an enable command in these circumstances, the enable command must be issued at the higher, promoted level of the hierarchy. For example, if member A was quiesced at the port level, a subsequent command to quiesce all members of the TCP/IP stack would be accepted. Furthermore, only a subsequent enable command at the TCP/IP stack level would be accepted to re-enable the member.
Table 1 shows which quiesce and enable commands are valid for a member after a previous quiesce command has affected that same member. A dot at the intersection of the prior command column and the current command row indicates that the current command would be valid for that member. Absence of a dot indicates that the current command would not be valid after the prior command had affected that member.
| Prior command | ||||
|---|---|---|---|---|
| QUIESCE,SYSTEM | QUIESCE,TCPNAME= | QUIESCE,PORT= | ||
| Current command | QUIESCE,SYSTEM | ● | ● | |
| QUIESCE,TCPNAME= | ● | |||
| QUIESCE,PORT= | ||||
| ENABLE,SYSTEM | ● | |||
| ENABLE,TCPNAME= | ● | |||
| ENABLE,PORT= | ● | |||
- A quiesce command is rejected if any member it applies to has already been quiesced by a command at a higher level of the hierarchy. For example, if you are running in a CINET configuration and you quiesce all members under stack A, which includes a member on stack A that used port 80, you cannot subsequently issue a quiesce command at the port level hoping to quiesce members using port 80 on stacks B and C, because the member on stack A that used that port was already quiesced at the stack level. Because the command would fail for one member, the entire command fails for all members.
- Quiesce commands at the system and stack level apply to currently registered members and also members that are registered in the future, provided that the IP addresses of those future members are owned by the Agent that issued the command. For quiesce commands issued at the stack level, the specified stack must exist at the time the command is issued.
- Quiesce commands at the port level can apply to members registered in the future, if a member currently exists at that port number. For example, if a member is registered by one load balancer at port 80 and the Agent operator quiesces all members at port 80, and then another load balancer registers that same member (same IP address, port, and protocol), the newly registered member would inherit the quiesce performed at the port level.
When a member represents a shareport group (that is, multiple server application instances sharing the same TCP port on the same TCP/IP stack), members cannot be defined to distinguish between the individual server application instances. That is, the combination of the IP address, port, and protocol represents all of the applications sharing the port. Therefore, you cannot selectively quiesce workload requests to only some of the applications sharing the port. Consequently, if you quiesce a member that represents a shareport group, all of the application instances in the group are quiesced.
If an Agent is stopped or fails and is restarted, the quiesce states of any members it might have previously owned are lost. If this occurs, reenter the appropriate quiesce commands to regain the quiesce states that existed during the previous instance of the Agent.
If a member is moved from one system in a sysplex to another using sysplex functions such as VIPA backup, the quiesce state does not move with it. For example, if quiesced member A is using IP address 1.1.1.1 on system X and system X fails, IP address 1.1.1.1 could be moved to system Y. Member A would no longer be quiesced on the new system and, assuming that the application that member A is assigned to is available and active on system Y, new workload requests would be distributed to this application.
If you plan to take a sysplex system out of service, simply stopping the Agent running on that system is not always a wise alternative to issuing a system-level quiesce command on that system's Agent. If an Agent is simply shut down, there are rare cases where a load balancer might choose to continue routing new workload requests to the applications on that system.