Chapter 5. 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.properties
file 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.properties
file are automatically used to initialize the fabric's user data, when you create the fabric. You can populate theusers.properties
file, 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 theadmin
role. If theInstallDir/etc/users.properties
already contains users with theadmin
role, you should delete those users before creating the fabric.WarningIf you leave some administrator credentials in theusers.properties
file, this represents a security risk because the file could potentially be accessed by other containers in the fabric.NoteThe initialization of user data fromusers.properties
happens only once, at the time the fabric is created. After the fabric has been created, any changes you make tousers.properties
will 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
NoteIf you want to create a fabric on a remote container, you can log into it using theInstallDir/bin/client
command-line utility. - Create a new fabric by entering the following command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --zookeeper-password ZooPass --resolver manualip --manual-ip StaticIPAddress --wait-for-provisioning
The current container, namedroot
by default, becomes a Fabric Server with a registry service installed. Initially, this is the only container in the fabric. The--new-user
and--new-user-password
options specify the credentials for a new administrator user. The Zookeeper password is used to protect sensitive data in the Fabric registry service (all of the nodes under/fabric
). The--manual-ip
option 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 "Description" in "Console Reference"section "Description" 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 IP port 2181 (which makes fabric configuration data available to all of the containers in the fabric).
- 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
ssh
access.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.