Chapter 7. Shutting Down a Fabric
Overview
This chapter describes how to shut down part or all of a fabric. In particular, when shutting down the ensemble servers (Fabric Servers), special care is needed.
Shutting down a managed container
From the console, you can shut down a managed container at any time using the
fabric:container-stop command, specifying the name of the managed container—for example:
fabric:container-stop ManagedContainerName
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 you ensure more than half of the Fabric Servers in the ensemble remain up and running.
For example, if you have an ensemble consisting of three servers,
registry1, registry2, and registry3, you can shut down at most one of these Fabric Servers at a time using the fabric:container-stop command—for example:
fabric:container-stop -f registry3
Note
The
-f flag is required when shutting down a container that belongs to the ensemble.
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 ever necessary to shut down an entire fabric. The idea of a fabric is that it provides redundancy, enabling you to shut down part of the fabric and restart it without having to shut down the whole fabric. You can even apply patches to a fabric without shutting down containers.
If you do need to shut down an entire fabric, however, you can do so as follows:
- To take a concrete example, consider a fabric which consists of the following containers:
- Three Fabric Servers (ensemble servers):
registry1,registry2,registry3. - Four managed containers:
managed1,managed2,managed3,managed4.
- Use the
clientconsole utility to log on to one of the containers in the fabric. Because this will be the last container to shut down, it is convenient to choose one of the Fabric Servers. For example, to log on to theregistry1server, enter the following command:./client -u AdminUser -p AdminPass -h Registry1Host
WhereRegistry1Hostis the host whereregistry1is running andAdminUserandAdminPassare the credentials of a user with administration privileges. It is assumed that theregistry1server is listening for console connections on the default IP port (that is,8101) - Shut down all of the managed containers in the fabric, using the
fabric:container-stopcommand—for example:fabric:container-stop managed1 fabric:container-stop managed2 fabric:container-stop managed3 fabric:container-stop managed4
- Remove all but one of the Fabric Servers from the ensemble, using the
fabric:ensemble-removecommand. For example, given the ensemble consisting ofregistry1,registry2, andregistry3(where you are logged on toregistry1), removeregistry2andregistry3from the ensemble as follows:fabric:ensemble-remove registry2 registry3
- You can now shut down the
registry2andregistry3containers using thefabric:container-stopcommand, as follows:fabric:container-stop registry2 fabric:container-stop registry3
- Assuming you are logged on to
registry1(the sole remaining Fabric Server), shut it down as follows:shutdown -f
- Whenever you restart the fabric, you will have to remember to recreate the ensemble, so that it consists of three Fabric Servers again. For example, to recreate the ensemble consisting of
registry1,registry2, andregistry3, you would restart the three servers, and then enter the following command:fabric:ensemble-add registry2 registry3
Note on shutting down the ensemble
If you are logged on to a container that is connected to a fabric, the following obvious procedure for shutting down the fabric ensemble does not work:
fabric:container-stop registry1 fabric:container-stop registry2 fabric:container-stop registry3
The third invocation of
fabric:container-stop will fail and throw an error. This is because of the quorum-based voting system used by the ensemble (which is designed to protect against network splits). After the first two Fabric servers (registry1 and registry2) are shut down, fewer than half of the ensemble servers are available. At this point, the registry shuts down and refuses to service any more requests, because there is no longer a quorum of ensemble servers available (that is, fewer than 50% of the ensemble servers are available). This causes a problem for the fabric:container-stop command, which normally contacts the registry to retrieve details about the container it is trying to shut down.
The solution to this problem is to adopt the procedure described in the section called “Shutting down an entire fabric”, where you first reduce the size of the ensemble using
fabric:ensemble-remove, before attempting to shut down the ensemble servers.
