Chapter 13. Connecting a Broker to a Fabric

Abstract

If you want a standalone broker to become part of a fabric you can either create the fabric from the standalone broker or join the broker to an existing fabric. Once a broker is added to a fabric, it reverts to an empty fabric container.
When Red Hat JBoss A-MQ is installed it is set up to run a standalone broker. If you want the broker to become part of a fabric you have two options:
  • join an existing fabric
    This option is useful if you have an existing fabric and simply want to add the broker to it. You can add the broker as a fully managed container in which the broker's existing configuration is wiped out and replaced with a profile from the fabric's repository. You can also add the broker as an unmanaged container that retains all of its configuration, but can be discovered through the fabric's ensemble.
    Note
    This option can also be used to move a broker from one fabric to another.
  • create a new fabric
    This option converts the standalone broker into a Fabric Server. You will then need to either add a new broker to the fabric, or assign a broker profile to the server.

13.1. Joining a Broker to a Fabric

Any standalone broker can be joined to an existing fabric using the fabric:join. You need to supply the URL of one of the Fuse Servers in the fabric and the standalone broker is added to the fabric. The broker can join the fabric as either a managed container or a non-managed container:
  • A managed container is a full member of the fabric and is managed by a Fabric Agent. The agent configures the container based on information provided by the fabric's ensemble. The ensemble knows which profiles are associated with the container and the agent determines what to install based on the contents of the profiles.
  • A non-managed container is not managed by a Fabric Agent. It's configuration remains intact after it joins the fabric and is controlled as if the broker were a standalone broker. Joining the fabric in this manner registers the broker with the fabric's ensemble and allows clients to locate the broker using the fabric's discovery mechanism.

13.1.1. Joining a Fabric as a Managed Container

Overview

When a broker joins a fabric as a managed container, it stops being a broker because the default behavior of the fabric:join command is to wipe out the container's configuration and replace it with the fabric profile. To start up as broker, you need to ensure that the fabric has a profile with the proper configuration and associate it with the container. The fabric:join command's -p argument allows you to specify a profile to install into the container once the agent is installed.

Becoming a managed container

Several things happen when a broker joins a fabric as a managed container:
  1. The broker installs the required Fuse Fabric bundles to interact with the fabric's ensemble.
  2. The broker contacts the specified Fabric Server and initiates the joining process.
  3. The Fabric Server registers the container with the fabric's ensemble.
    This adds the container's information to the fabric's registry using the container name as the key. Because the container is a managed container, the registry creates an empty entry for the container and only includes the information it needs to manage the container.
    Warning
    If the container being added to the fabric has the same name as a container already registered with the fabric, both containers will be reset and will always share the same configuration.
  4. The Fabric Server, as a delegate of the fabric's ensemble, takes control of the container.
    This process clears the container and resets its configuration to a default state.
  5. The ensemble installs the fabric profile into the container.
    This loads the Fabric Agent into the container to facilitate the management of the container.
    • If the -p argument is passed the fabric:join, the container's agent installs the artifacts and configuration settings from the specified profile.
    • The container sits empty and ready for you to associate one or more profiles with it.
  7. The agent monitors the container and the ensemble for changes.
    If the state of the container changes, the agent updates the ensemble's registry entry. If the ensemble has updates for the container, such as a new profile being associated with the container or a change to one of the profiles already associated with the container, the agent updates the container.

Remaining a message broker

Joining a fabric as a managed container converts a standalone broker into a vanilla fabric container. It can take on any characteristics that are required. If you want it to join the fabric and continue to function as a message broker, then you must ensure that the fabric being joined has a profile that will configure the container to be a message broker and assign that profile to the container.
The default set of profiles installed with Fuse Fabric include an mq profile that loads a default message broker. You can also create a new profile for your brokers as described in Section 2.3, “Editing a Broker's Configuration in a Fabric”.
The easiest way to assign the profile is to do so when executing the fabric:join by using the -p flag. The specified profile will be assigned to the container as soon as the agent is installed. If you would rather do it in two steps, you can assign the profile using the fabric:container-change-profile command or the management console.

Procedure

To join a broker to a fabric and have it start up as a broker:
  1. Create a profile for your broker.
    For details on creating a broker profile see Section 2.3, “Editing a Broker's Configuration in a Fabric”.
  2. Get the URL for one of the Fabric Servers in the existing fabric.
    The URL of a Server has the following format: 
    HostName:IPPort
    For example, given a fabric registry agent running on the host, myhost, the URL would be myhost:2181. The IP port, 2181, is the default IP port used by a Fabric Server and is usually the correct value to use. If you are in any doubt about which URL to use you can discover the URLs of the Fabric Servers as follows:
    1. Connect to the command console of one of the containers in the fabric.
    2. Enter the following sequence of console commands: 
      JBossA-MQ:karaf@root> config:edit org.fusesource.fabric.zookeeper
JBossA-MQ:karaf@root> config:proplist
 service.pid = org.fusesource.fabric.zookeeper zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183 fabric.zookeeper.pid = org.fusesource.fabric.zookeeper
JBossA-MQ:karaf@root> config:cancel
      The zookeeper.url property holds a comma-separated list of Fabric Server URLs. You can use any one of these URLs to join the fabric.
  3. Connect to the standalone broker's command console.
  4. Enter the following command: 
    JBossA-MQ:karaf@root> fabric:join -p brokerProfile fabricURL brokerName
    You need to provide values for:
    • brokerProfile—the name of the profile you created in Step 1
    • fabricURL—the Fabric Server URL you obtained in Step 2
    • brokerName—the name the broker will use to register with the fabric
      Important
      The name should be unique among the containers in the fabric.

13.1.2. Joining a Fabric as a Non-Managed Container

Overview

When a broker joins a fabric as a non-managed container, it continues being a standalone broker because a Fabric Agent does not take control of the container. The agent only registers the broker with the fabric's ensemble and keeps the registry entries for it up to date. This enables consumers to discover the broker using the fabric's discovery mechanism described in Using Networks of Brokers.

Becoming a non-managed container

Several things happen when a broker joins a fabric as a non-managed container:
  1. The broker installs the required Fuse Fabric bundles to interact with the fabric's ensemble.
  2. The broker contacts the specified Fabric Server and initiates the joining process.
  3. The Fabric Server registers the container with the fabric's ensemble.
    This adds the broker's information to the fabric's registry using the broker's name as the key. Because the broker is non-managed, the registry creates an entry containing information for all the message destinations hosted by the broker.
    Warning
    If the container being added to the fabric has the same name as a container already registered with the fabric, both containers will be reset and will always share the same configuration.
  4. The agent monitors the broker and updates the updates the ensemble's registry entry as needed.

Procedure

To join a broker to a fabric a non-managed container:
  1. Get the URL for one of the Fabric Servers in the existing fabric.
    The URL of a Server has the following format: 
    HostName:IPPort
    For example, given a fabric registry agent running on the host, myhost, the URL would be myhost:2181. The IP port, 2181, is the default IP port used by a Fabric Server and is usually the correct value to use. If you are in any doubt about which URL to use you can discover the URLs of the Fabric Servers as follows:
    1. Connect to the command console of one of the containers in the fabric.
    2. Enter the following sequence of console commands: 
      JBossA-MQ:karaf@root> config:edit org.fusesource.fabric.zookeeper
JBossA-MQ:karaf@root> config:proplist
 service.pid = org.fusesource.fabric.zookeeper zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183 fabric.zookeeper.pid = org.fusesource.fabric.zookeeper
JBossA-MQ:karaf@root> config:cancel
      The zookeeper.url property holds a comma-separated list of Fabric Server URLs. You can use any one of these URLs to join the fabric.
  2. Connect to the standalone broker's command console.
  3. Enter the following command: 
    JBossA-MQ:karaf@root> fabric:join -n fabricURL brokerName
    You need to provide values for:
    • -n—specifies that the broker will not be managed by the fabric
    • fabricURL—the Fabric Server URL you obtained in Step 1
    • brokerName—the name the broker will use to register with the fabric
      Important
      The name should be unique among the containers in the fabric.