Chapter 5. Shutting Down a Fabric
Overview
This chapter describes how to shut down part or all of a fabric.
Shutting down a managed container
You can shut down a managed container from the console at any time. Invoke the
fabric:container-stop command and specify the name of the managed container, for example:
fabric:container-stop -f ManagedContainerName
Note
The
-f flag is required when shutting down a container that belongs to the ensemble.
The
fabric:container-stop command looks up the container name in the registry and retrieves the data it needs to shut down that container. This approach works no matter where the container is deployed: whether on a remote host or in a cloud.
Shutting down a Fabric Server
Occasionally, you might want to shut down a Fabric Server for maintenance reasons. It is possible to do this without disabling the fabric, as long as more than half of the Fabric Servers in the ensemble remain up and running. For example, suppose you have an ensemble that consists of three servers,
registry1, registry2, and registry3. You can shut down only one of these Fabric Servers at a time by using the fabric:container-stop command, for example:
fabric:container-stop -f registry3
After performing the necessary maintenance, you can restart the Fabric Server as follows:
fabric:container-start registry3
Shutting down an entire fabric
In a production environment, it is rarely necessary to shut down an entire fabric. A fabric provides redundancy by enabling you to shut down part of the fabric and restart that part without having to shut down the whole fabric. You can even apply patches to a fabric without shutting down containers.
Red Hat recommends that you minimize the number of times you shut down a complete fabric. This is because shutting down and restarting an entire fabric requires execution of the
fabric:ensemble-remove and fabric:ensemble-add commands. Each time you execute one of these commands, it creates a new ensemble. This new ensemble URL is propagated to all containers in the fabric and all containers need to reconnect to the new ensemble. There is a risk for TCP port numbers to be reallocated, which means that your network configuration might become out-of-date because services might start up on different ports.
However, if you must shut down an entire fabric, follow the steps below. These steps show examples that reflect this configuration:
- Three Fabric Servers (ensemble servers):
registry1,registry2,registry3. - Four managed containers:
managed1,managed2,managed3,managed4.
To shut down a complete fabric:
- Use the
clientconsole utility to log on to one of the Fabric Servers in the ensemble. For example, to log on to theregistry1server, enter a command in the following format:./client -u AdminUser -p AdminPass -h Registry1Host
ReplaceAdminUserandAdminPasswith the credentials of a user with administration privileges. ReplaceRegistry1Hostwith name of the host whereregistry1is running. It is assumed that theregistry1server is listening for console connections on the default TCP port (that is,8101) - Ensure that all managed containers in the fabric are running. Execution of
fabric:container-listshould displaytruein thealivecolumn for each container. This is required for execution of thefabric:ensemble-removecommand, which is the next step. - Remove all but one of the Fabric Servers from the ensemble. For example, if you logged on to
registry1, enter:fabric:ensemble-remove registry2 registry3
- Shut down all managed containers in the fabric, except the container on the Fabric Server you are logged into. In the following example, the first command shuts down
managed1,managed2,managed3andmanaged4:fabric:container-stop -f managed* fabric:container-stop -f registry2 fabric:container-stop -f registry3
- Shut down the last container that is still running. This is the container that is on the Fabric Server you are logged in to. For example:
shutdown -f
After you complete the work that required the fabric to be shut down, you restart the fabric by recreating it. For example:
- Use the
clientconsole utility to log in to theregistry1container host. - Start all containers in the fabric.
- Add the other Fabric Servers, for example:
fabric:ensemble-add registry2 registry3
Note on shutting down a complete fabric
If you are logged on to a container that is connected to a fabric, you might be tempted to shut down the complete fabric by stopping the containers on the Fabric Servers. For example:
fabric:container-stop -f registry1 fabric:container-stop -f registry2 fabric:container-stop -f registry3
This does not work because a fabric requires a quorum (a simple majority) of Fabric Servers to be running in order to stop a container that is in the fabric. In this example, the third invocation of
fabric:container-stop fails and throws an error because only one Fabric Server is still running. At least two Fabric Servers must be running to stop a container. With only one Fabric Server running, the registry shuts down and refuses service requests because a quorum of Fabric Servers is no longer available. The fabric:container-stop command needs the registry to be running so it can retrieve details about the container it is trying to shut down.
The correct way to shut down a complete fabric is to follow the steps in the previous section. That is, remove all Fabric Servers except one and then stop all containers.
