Chapter 2. 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.
Static IP address required for Fabric Server
The IP address and hostname associated with the Fabric Servers in the Fabric ensemble are of critical importance to the fabric. Because these IP addresses and hostnames are used for configuration and service discovery (through the Zookeeper registry), they must not change during the lifetime of the fabric.
You can take either of the following approaches to specifying the IP address:
- For simple examples and tests (with a single Fabric Server) you can work around the static IP requirement by using the loopback address,
127.0.0.1. - For distributed tests (multiple Fabric Servers) and production deployments, you must assign a static IP address to each of the Fabric Server hosts.
Warning
Beware of volatile IP addresses resulting from VPN connections, WiFi connections, and even LAN connections. If a Fabric Server binds to one of these volatile IP addresses, it will cease to function after the IP address has gone away. It is recommended that you always use the
--resolver manualip --manual-ip StaticIPAddress options to specify the static IP address explicitly, when creating a new Fabric Server.
Procedure
To create a new fabric:
- (Optional) Customise the name of the root container by editing the
InstallDir/etc/system.propertiesfile and specifying a different name for this property:karaf.name=root
NoteFor the first container in your fabric, this step is optional. But at some later stage, if you want to join a root container to the fabric, you might need to customise the container's name to prevent it from clashing with any existing root containers in the fabric. - Any existing users in the
InstallDir/etc/users.propertiesfile are automatically used to initialize the fabric's user data, when you create the fabric. You can populate theusers.propertiesfile, by adding one or more lines of the following form:Username=Password[,RoleA][,RoleB]...
But there must not be any users in this file that have administrator privileges (Administrator,SuperUser, oradminroles). If theInstallDir/etc/users.propertiesalready contains users with administrator privileges, you should delete those users before creating the fabric.WarningIf you leave some administrator credentials in theusers.propertiesfile, this represents a security risk because the file could potentially be accessed by other containers in the fabric.NoteThe initialization of user data fromusers.propertieshappens only once, at the time the fabric is created. After the fabric has been created, any changes you make tousers.propertieswill have no effect on the fabric's user data. - If you use a VPN (virtual private network) on your local machine, it is advisable to log off VPN before you create the fabric and to stay logged off while you are using the local container.NoteA local Fabric Server is permanently associated with a fixed IP address or hostname. If VPN is enabled when you create the fabric, the underlying Java runtime is liable to detect and use the VPN hostname instead of your permanent local hostname. This can also be an issue with multi-homed machines.
- Start up your local container.In JBoss Fuse, start the local container as follows:
cd InstallDir/bin ./fuse
- Create a new fabric by entering the following command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --new-user-role Administrator --zookeeper-password ZooPass --resolver manualip --manual-ip StaticIPAddress --wait-for-provisioning
The current container, namedrootby default, becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The--new-user,--new-user-password, and--new-user-roleoptions specify the credentials for a newAdministratoruser. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under/fabric). The--manual-ipoption specifies the Fabric Server's static IP addressStaticIPAddress(see the section called “Static IP address required for Fabric Server”).For more details on fabric:create see section "fabric:create" in "Console Reference".For more details about resolver policies, see section "fabric:container-resolver-list" in "Console Reference" and section "fabric:container-resolver-set" in "Console Reference".
Fabric creation process
Several things happen when a fabric is created from a standalone container:
- The container installs the requisite OSGi bundles to become a Fabric Server.
- The Fabric Server starts a registry service, which listens on TCP port 2181 (which makes fabric configuration data available to all of the containers in the fabric).NoteYou can customize the value of the registry service port by specifying the
--zookeeper-server-portoption. - 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.
- The new Fabric Ensemble consists of a single Fabric Server (the current container).
- A default set of profiles is imported from
InstallDir/fabric/import(can optionally be overridden). - 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.
Expanding a Fabric
You can expand a fabric by creating new managed containers. Fabric supports the container provider plug-in mechanism, which makes it possible to define how to create new containers in different contexts. Currently, Fabric makes container providers available for the following kinds of container:
- Child container, created on the local machine as a child process in its own JVM.Instructions on creating a child container are found in Child Containers.
- SSH container, created on any remote machine for which you have
sshaccess.Instructions on creating a SSH container are found in SSH Containers. - Cloud container, created on compute instance in the cloud.Instructions on creating a cloud container are found in Cloud Containers.
Fabric provides container creation commands that make it easy to create new containers. Using these commands, Fabric can automatically install JBoss Fuse on a remote host (uploading whatever dependencies are needed), start up the remote container process, and join the container to the existing fabric, so that it becomes a fully-fledged managed container in the fabric.
