Chapter 6. Joining a Fabric

Overview

Any standalone container can be joined to an existing fabric using the fabric:join console command. You need to supply the URL of one of the Fuse Servers in the fabric and the standalone container is then added to the fabric. The container 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. Its configuration remains intact after it joins the fabric and is controlled as if the container were a standalone container. Joining the fabric in this manner registers the container with the fabric's ensemble and allows clients to locate the services running in the container using the fabric's discovery mechanism.

Joining a fabric as a managed container

The default behavior of the fabric:join command is to wipe out the container's configuration and replace it with the fabric profile. If you want to preserve the previous configuration of the container, however, you must ensure that the fabric has an appropriately configured profile, which you can deploy into the container after it joins the fabric.
The fabric:join command's -p option enables you to specify a profile to install into the container once the agent is installed.

Joining a fabric as an non-managed container

When a container joins a fabric as a non-managed container, its deployment mechanisms continue to function like a standalone container (based on osgi:install, features:install, and hot deployment), because a Fabric Agent does not take control of its configuration. The agent only registers the container with the fabric's ensemble and keeps the registry entries for it up to date. This enables the newly joined container to discover services running in the container (through Fabric's discovery mechanisms) and to administer these services.
Joining a fabric as an non-managed container is a convenient approach to take when you want to use your local container as a console to administer a fabric. For example, this is an approach that is typically taken with the Fuse Management Console (FMC).

How to join a fabric

To join a container to a fabric, perform the following steps:
  1. Get the registry service URL for one of the Fabric Servers in the existing fabric. The registry service URL has the following format:
    Hostname[:IPPort]
    Normally, it is sufficient to specify just the hostname, Hostname, because the registry service uses the fixed port number, 2182, by default. In exceptional cases, you can discover the registry service port by following the instructions in the section called “How to discover the URL of a Fabric Server”.
  2. Get the ZooKeeper password for the fabric. An administrator can access the fabric's ZooKeeper password at any time, by entering the following console command (while logged into one of the Fabric Containers):
    JBossFuse:karaf@root> fabric:ensemble-password
  3. Connect to the standalone container's command console.
  4. Join a container in one of the following ways:
    • Join as a managed container, with a default profile—uses the fabric profile.
      JBossFuse:karaf@root> fabric:join --zookeeper-password ZooPass URL ContainerName
    • Join as a managed container, specifying a custom profile—uses a custom profile.
      JBossFuse:karaf@root> fabric:join --zookeeper-password ZooPass -p Profile URL ContainerName
    • Join as a non-managed container—preserves the existing container configuration.
      JBossFuse:karaf@root> fabric:join -n --zookeeper-password ZooPass URL ContainerName
    Where you can specify the following values:
    ZooPass
    The existing fabric's ZooKeeper password.
    URL
    The URL for one of the fabric's registry services (usually just the hostname where a Fabric Server is running).
    ContainerName
    The new name of the container when it registers itself with the fabric.
    Warning
    If the container your're adding 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.
    Profile
    The name of the custom profile to install into the container after it joins the fabric (managed container only).
  5. If you joined the container as a managed container, you can subsequently deploy a different profile into the container using the fabric:container-change-profile console command.

How to discover the URL of a Fabric Server

If you suspect that a Fabric Server is not using the default TCP port, 2181, for its registry service, you can discover the port 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 io.fabric8.zookeeper
    JBossA-MQ:karaf@root> config:proplist
       service.pid = io.fabric8.zookeeper
       zookeeper.url = myhostA:2181,myhostB:2181,myhostC:2181,myhostC:2182,myhostC:2183
       fabric.zookeeper.pid = io.fabric8.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.