Chapter 7. 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 locally or on a remote host.

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:
  1. Use the client console utility to log on to one of the Fabric Servers in the ensemble. For example, to log on to the registry1 server, enter a command in the following format:
    ./client -u AdminUser -p AdminPass -h Registry1Host
    Replace AdminUser and AdminPass with the credentials of a user with administration privileges. Replace Registry1Host with name of the host where registry1 is running. It is assumed that the registry1 server is listening for console connections on the default TCP port (that is, 8101)
  2. Ensure that all managed containers in the fabric are running. Execution of fabric:container-list should display true in the alive column for each container. This is required for execution of the fabric:ensemble-remove command, which is the next step.
  3. 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
  4. 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, managed3 and managed4:
    fabric:container-stop -f managed*
    fabric:container-stop -f registry2
    fabric:container-stop -f registry3
  5. 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:
  1. Use the client console utility to log in to the registry1 container host.
  2. Start all containers in the fabric.
  3. 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 entire 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.