Red Hat Training

A Red Hat training course is available for Red Hat Fuse

Chapter 6. Creating a New Fabric

Abstract

When there are no existing fabric's to join, or you want to start a new fabric, you can create a new one from a standalone container.

Overview

A fabric consists of two different kinds of container:
Fabric Server
A Fabric Server has a special status in the fabric, because it is responsible for maintaining a replica of the fabric registry. In each Fabric Server, a registry service is installed. The registry service (based on Apache ZooKeeper) maintains a replica of the registry database and provides a ZooKeeper server, which ordinary agents can connect to in order to retrieve registry data.
Fabric Container
A Fabric Container is aware of the locations of all of the Fabric Servers, and it can retrieve registry data from any Fabric Server in the Fabric Ensemble. A Fabric Agent is installed in each Fabric Container. The Fabric Agent actively monitors the fabric registry, and whenever a relevant modification is made to the registry, it immediately updates its container to keep the container consistent with the registry settings.

Fabric Ensemble

A Fabric Ensemble is a collection of Fabric Servers and Fabric Containers that collectively maintain the state of the fabric registry. The Fabric Ensemble implements a replicated database and uses a quorum-based voting system to ensure that data in the fabric registry remains consistent across all of the fabric's containers. To guard against network splits in a quorum-based system, it is a requirement that the number of Fabric Servers in a Fabric Ensemble is always an odd number.
The number of Fabric Servers in a fabric is typically 1, 3, or 5. A fabric with just one Fabric Server is suitable for experimentation only. A live production system should have at least 3 or 5 Fabric Servers, installed on separate hosts, to provide fault tolerance.

Procedure

To create a new fabric from a standalone container:
  1. Connect to the standalone container's command console.
  2. Any existing users in the InstallDir/etc/users.properties file are automatically used to initialize the fabric's user data, when you create the fabric. This provides a convenient way to initialize the fabric's user data.
    If you have not already done so, it is recommended that you populate the users.properties file, by adding one or more lines of the following form: 
    Username=Password[,RoleA][,RoleB]...
    At least one of the users must have the admin role, to enable administration of the fabric. For example: 
    admin=secretpassword,admin
  3. Assuming that some users are already defined in the users.properties file, you can create a new fabric by entering the following command: 
    JBossFuse:karaf@root> fabric:create --zookeeper-password admin
    The current container (named root by default) becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under /fabric).
    Note
    If you want to import a predefined set of profiles, use the -p import-dir option to specify the set of profiles to import.
    For more details on fabric:create see section "Description" in "Console Reference".
  4. (Alternative) If no users are predefined in the users.properties file, an alternative approach is to define a new user at the same time the fabric is created, by supplying the --new-user and --new-user-password options, as follows: 
    JBossFuse:karaf@root> fabric:create --new-user jdoe --new-user-password secretpassword --zookeeper-password admin
    The new user, jdoe, is automatically assigned the admin role, which gives the user full administration privileges.

Fabric creation process

Several things happen when a fabric is created from a standalone container:
  1. The container installs the requisite OSGi bundles to become a Fabric Server.
  2. The Fabric Server starts a registry service, which listens on IP port 2181 (which makes fabric configuration data available to all of the containers in the fabric).
  3. The Fabric Server installs a new JAAS realm (based on the ZooKeeper login module), which overrides the default JAAS realm and stores its user data in the ZooKeeper registry.
  4. The new Fabric Ensemble consists of a single Fabric Server (the current container).
  5. A default set of profiles is imported from InstallDir/fabric/import (can optionally be overridden).
  6. After the standalone container is converted into a Fabric Server, the previously installed OSGi bundles and Karaf features are completely cleared away and replaced by the default Fabric Server configuration. For example, some of the shell command sets that were available in the standalone container are no longer available in the Fabric Server.