---
title: Fuse Fabric User Guide
in_menu: true
sort_info: 10
--- 
{:toc}

## Architecture

### Registry

Fuse Fabric uses [Apache ZooKeeper](http://zookeeper.apache.org/), which is highly reliable distributed coordination service,
as its registry to store the cluster configuration and node registration.  

ZooKeeper is designed with consistency and high availability across data centers in mind while also protecting against network splits by using a quorum of ZooKeeper servers. e.g. you may run 3 or 5 ZooKeeper servers and so long as you have quorum running (2 or 3 servers respectively) you are reliable and are not in a network split.

Conceptually Fabric has 2 registries: 

* **Configuration Registry** which is the logical configuration of your fabric and typically contains no physical machine information; its your logical configuration. 
* **Runtime Registry** which contains details of how many machines are actually running, their physical location details and what services they are implementing.

### Profiles

Fabric defines a notion of *profile* that can be applied to nodes of the Fabric.  A profile consists
of a list of configurations that will be provided to ConfigAdmin along with bundles and features to be provisioned.  Multiple profiles can
be associated to a given node, allowing a given node to serve multiple purposes.

If you want a Fabric where each node is running exactly the same set of features with exactly the same configuration then you only need one profile. However in most real world use cases you often want either to provision features differently across nodes or at least have different configurations. 

For example you may wish to run different kinds of things on different nodes; you may run some message brokers, some web applications, some ESBs and some transformation engines and proxies. Each of these can be profiles that you can manage as a single logical entity irrespective of how many instances you wish to run. Or you may want to run the same features everywhere but you may wish to provide location specific configurations, you may use different locations of message broker or cache services in different data centres or geographical regions.

Profiles can also have inheritance so that parts of configuration can be shared across multiple
profiles; similar to the use of trees in LDAP repositories.  The overall list of configurations is computed using an overlay mechanism which allow
a profile to override values from its parents, which provides power and flexibility while keeping your configuration nice and DRY.
Those profiles are stored in ZooKeeper, hence automatically and immediately propagated to all
nodes which can refresh the configurations as needed.

Fabric defines a provisioning agent relying on Karaf features through ConfigurationAdmin.
The list of features to be installed on a given node is retrieved from a known configuration
by the agent and the features are installed / uninstalled as needed.


## Provisioning and Configuration

Each node in the cluster has a logical name and on startup the provisioning agent registers an ephemeral node in ZooKeeper. It then looks in the configuration using its logical name for its profile of  what configuration to use and what services to provision. If there is no configuration or the logical name it uses the default profile.

Each node watches the relevant parts of the ZooKeeper tree for changes; so that as soon as any profile is updated the dependent nodes refresh and re-apply any provisioning or configuration changes.

### Changing the configuration

You can then use the [Fabric command line shel](commands/commands.html) to interact with the configuration so that you can dynamically control configuration and provisioning.

Through the use of profiles you can then control all or a group of nodes in each operation. For example you can set global configuration properties or properties which only affect a group of nodes (e.g. message brokers only or web servers only or all ESBs within some data centre).

### How discovery works

Each container registers itself into the ZooKeeper runtime registry details of its machine, host name and connection details (e.g. JMX URL) so its easy to discover and introspect the Fabric and to delve into any node to introspect or control it in more detail.

In addition Fabric supports a number of additional discovery mechanisms which are framework specific in the Fabric Extensions.

## Fabric Extensions

In addition to the core Provisioning, Configuration and Management Fabric described above, Fabric also provides a number of technology specific extensions:

### ActiveMQ Fabric

When using ActiveMQ you have to configure your ActiveMQ clients with the locations of the ActiveMQ brokers up front which is not terribly cloud friendly (e.g. working on a number of new EC2 boxes spun up on Amazon). 

However the **ActiveMQ Fabric** lets you avoid this by reusing the Fabric discovery mechanism. ActiveMQ brokers register themselves into the Runtime Registry. Then ActiveMQ clients use the Runtime Registry to discover brokers; plus watch for brokers failing and new brokers starting so there is a real time discovery and load balancing mechanism.

[Here](mq.html) you can find more information on **ActiveMQ Fabric**

### Camel Fabric

When using [ActiveMQ](http://camel.apache.org/activemq.html) or [JMS](http://camel.apache.org/jms.html) endpoints in Camel you are already _fabric ready_ since message brokers provide true location independence (as well as time independence too, the consumer of a message does not even have to be running at the time you send a message).

However if you are using socket or HTTP endpoints this is not the case; each client wishing to invoke your service needs to know all the available network addresses of each implementation (e.g. a list of protocols, host name & ports).

This is where the **Camel Fabric** comes in; it provides a way to reuse Fabric's discovery mechanism to expose physical socket & HTTP endpoints into the runtime registry using a logical name so that clients can use the existing Camel [Load Balancer](http://camel.apache.org/load-balancer.html).

Currently Camel Fabric works using the **fabric** Camel component.

#### Exposing a Camel endpoint into the fabric

{pygmentize:: java}
from("fabric:myName:jetty:http://0.0.0.0:8181").to("bean:foo")
{pygmentize}

Here we just prefix any socket or HTTP based endpoint with **fabric::myName** where the myName is the logical name of the service you wish to use. This prefix is then used to expose your endpoint URI into the Runtime Registry

#### Invoking a Camel fabric endpoint

{pygmentize:: java}
from("seda:foo").to("fabric:myName")
{pygmentize}

In the above route we send to the endpoint **fabric:myName** which at runtime will use the myName entry in the Camel Fabric to discover the currently available physical endpoints in the fabric for this name; then load balance across them.

### CXF Fabric

Like the Camel Fabric above, the **CXF Fabric** makes it easy to expose physical web services into the Runtime Registry so that clients can just bind to the logical name of the service and at runtime locate and load balance across the running implementations.

Basically, your CXF endpoint will know nothing about the Fabric runtime, and you just need to configure the FabricLoadBalanceFeature with the ZKClientFactoryBean and set the feature into the bus, the FabricLoadBalanceFeature will interact with Fabric runtime automatically.

You can configure the fabricPath of the FabricLoadBalancerFeature for the CXF server and CXF client to use.

{pygmentize:: xml}
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xmlns:cxfcore="http://cxf.apache.org/core"
       xsi:schemaLocation="
         http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
         http://cxf.apache.org/core http://cxf.apache.org/schemas/core.xsd">
 
  <bean id="zkClient" class="org.fusesource.fabric.zookeeper.spring.ZKClientFactoryBean">
    <property name="timeoutText" value="30s"/>
    <property name="connectString" value="localhost:2181"/>
  </bean>

  <bean id="fabicLoadBalancerFeature" class="org.fusesource.fabric.cxf.FabricLoadBalancerFeature">
      <property name="fabricPath" value="simple" />
  </bean>
  <!-- configure the feature on the bus -->
  <cxfcore:bus>
    <cxfcore:features>
      <ref bean="fabicLoadBalancerFeature" />
    </cxfcore:features>
  </cxfcore:bus>

</beans>
{pygmentize}

#### Exposing a CXF endpoint into the fabric
{pygmentize:: java}
   // You just need to make sure the bus is configured with the FabricLoadBalanceFeature
   ServerFactoryBean factory = new ServerFactoryBean();
   factory.setServiceBean(new HelloImpl());
   factory.setAddress("http://localhost:9000/simple/server");
   factory.setBus(bus);
   factory.create();
{pygmentize}

Here you can use the CXF normal code to publish the CXF service, but you need to make sure the FabricLoadBalancerFeature is registered into the bus that you service will be published.

#### Invoking a CXF fabric endpoint
{pygmentize:: java}
   ClientProxyFactoryBean clientFactory = new ClientProxyFactoryBean();
   clientFactory.setServiceClass(Hello.class);
   // The address is not the actual address that the client will access
   clientFactory.setAddress("http://someotherplace");
   List<AbstractFeature> features = new ArrayList<AbstractFeature>();
   features.add(feature);
   // we need to setup the feature on the clientfactory
   clientFactory.setFeatures(features);
   Hello hello = clientFactory.create(Hello.class);
   String response = hello.sayHello();
   System.out.println(response);
{pygmentize}

For the CXF client, you just need to set the FabricLoadBalancerFeature directly into the clientFactory. The FabricLoadBalancerFeature will pick a real service physical address for the Fabric service registry for the client to use. 

### OSGi Fabric

The OSGi registry by default contains local services. However since Fabric has a Configuration Registry defining profiles along with a Runtime Registry for discovery, its easy to configure Fabric to expose remote OSGi services into the Runtime Registry for different profiles so that you can get invisible remoting of services with dynamic discovery, load balancing and fail over.
The OSGi Fabric follows the OSGi Remote Services specification.  Any service exported in the OSGi registry with a property named "service.exported.interfaces" (with a value of either "*" or a list of interfaces to export) will be automatically exported in Fabric Registry and imported on other Fabric containers as needed.

#### Exposing an OSGi service into the Fabric using Blueprint
{pygmentize:: xml}
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">
  <bean id="theBean" class="foo.bar.Example" />
  <service ref="theBean" auto-export="interfaces">
    <service-properties>
      <entry key="service.exported.interfaces" value="*"/>
    </service-properties>
  </service>
</blueprint>
{pygmentize}

#### Importing an OSGi service from the Fabric
Well, nothing to do there.  Just use the service as usual and the OSGi Fabric will import it for you :-)

### Process Fabric

While OSGi is cool and all; not everything is available as OSGi bundles. You often want to run other things inside your Fabric other than bundles. For example databases, non Java code or even just different packaging of Java code such as a [Tomcat](http://tomcat.apache.org/) distribution for your web applications.

The *Process Fabric** extends the fabric of Karaf nodes to support any other kind of process on your machine. Think of it as like a distributed version of [monit](http://mmonit.com/monit/) or init.d.


### ServiceMix Fabric

The *ServiceMix Fabric* extends the NMR in ServiceMix which is currently a local registry of endpoints to be a fully distributed registry of endpoints with discovery, load balancing and fail over.

Using the Configuration Registry you can define the policies for which services you wish to expose and load balance. The ServiceMix Fabric then registers the necessary services into the Runtime Registry and then auto-exposes remote endpoints into the NMR - turning the NMR into a true distributed NMR.


## Using Fabric

The primary interface currently for working with Fabric is via the [command line shells in Karaf](commands/commands.html). 

We are working on a web console which will be released shortly along with plugins to the [Fuse IDE](http://fusesource.com/ide/) if you want to interact with Fabric from inside [Eclipse](http://eclipse.org/).




