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:
  1. 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.
  2. Use the client console 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 the registry1 server, enter the following command:
    ./client -u AdminUser -p AdminPass -h Registry1Host
    Where Registry1Host is the host where registry1 is running and AdminUser and AdminPass are the credentials of a user with administration privileges. It is assumed that the registry1 server is listening for console connections on the default IP port (that is, 8101)
  3. Shut down all of the managed containers in the fabric, using the fabric:container-stop command—for example:
    fabric:container-stop managed1
    fabric:container-stop managed2
    fabric:container-stop managed3
    fabric:container-stop managed4
  4. Remove all but one of the Fabric Servers from the ensemble, using the fabric:ensemble-remove command. For example, given the ensemble consisting of registry1, registry2, and registry3 (where you are logged on to registry1), remove registry2 and registry3 from the ensemble as follows:
    fabric:ensemble-remove registry2 registry3
  5. You can now shut down the registry2 and registry3 containers using the fabric:container-stop command, as follows:
    fabric:container-stop registry2
    fabric:container-stop registry3
  6. Assuming you are logged on to registry1 (the sole remaining Fabric Server), shut it down as follows:
    shutdown -f
  7. 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, and registry3, 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.