vFabric Administration Server Concepts

vFabric Administration Server is built on the concept of a single system image, a collection of systems that behaves as a single system. With vFabric Administration Server, the single system image is a group, and the group is a collection of one or more nodes. A node is a single computer. Administrative operations performed on a group are automatically applied to each node in the group.

Groups and the Single System Image

The server keeps track of the state of each group. When you execute an operation that changes the group's state, the server executes that operation on each member node so that all of the group's nodes conform to the single system image.

If you add a new node to a group, the group's state is applied to the new node to bring it into compliance with its peers. If you remove a node from a group, vFabric Administration Server cleans the group's state from the node.

Scaling a deployment is accomplished by adding or removing group nodes. To scale up a deployment, add nodes to the group. To scale down, remove nodes from the group.


A node is a computer (physical or virtual) that can be managed by vFabric Administration Server. The nodes participating in a group must be compatible—they have the same operating system, the JVM is installed in the same location on each node, and the vFabric Administration Server agent is installed in the same location. Creating a standard installation image or VM template to initialize nodes avoids problems and makes it easier to add nodes later.

To add a node to the system, you download the agent installation ZIP file from the server to the node, extract it, and start it. The agent is preconfigured to connect to the server from which it is downloaded. When the agent starts up the first time, it registers with the server, and the server keeps track of the node from that point forward.

Once the agent is installed, a node is managed by adding it to a group and managing the group. To deploy a single node running an instance of a vFabric Suite component, you create a group containing just one node.

Installation Images and Installations

An installation image is an installation archive for a vFabric Suite Component stored on vFabric Administration Server. An installation is a vFabric Suite Component installed on a group using a previously created installation image.

The archive used to create an installation image can be a ZIP file (for example, .zip or .jar) or a compressed tar archive (.tar.gz). The installation archive contains a directory tree that, when extracted into place, contains a working installation of the vFabric Suite component. Each of the vFabric Suite components that vFabric Administration Server supports is available in a compatible archive format on the VMware download Web site. Executable installers (for example, .exe, .msi, .bin, or .sh) or Linux packaging system distributions (for example, .rpm or .deb) are not supported with vFabric Administration Server.

vFabric Administration Server acts as a central repository for the installers your applications require, ensuring that the same installer is used for all nodes in a group. An installation image has a version attribute used to distinguish between releases of the component. This allows you to deploy different versions of a component when necessary. For example, you can deploy a newer tc Server version in your development environment and an older tc Server version in your production environment.

An installation is an installation image deployed to a group. To create an installation, you specify the installation image and the destination group. vFabric Administration Server distributes the installation image to each node in the group, where the agent extracts the image into place.


An instance is a GemFire cache server, locator, or agent; a SQLFire server, locator or agent; a tc Runtime instance; a Web Server instance; or a RabbitMQ broker. vFabric Administration Server has two views of an instance. A group instance represents the instance across all nodes in a group. A node instance is an instance on a specific node.

A node instance has a state, either STARTING, STARTED, STOPPING, or STOPPED. The state of a group instance is a roll-up of the states of the node instances. Unless all node instances have the same state, vFabric Administration Server reports the group instance state as MIXED.

For most administration tasks, you operate on the group instance and vFabric Administration Server manages the node instances. However, there are certain operations you perform on individual node instances. For example, you view a log file for an individual node instance, since there are no log files associated with a group instance. You can also stop or start a node instance so that the action affects only the selected node. The REST APIs provide access to node instances for these kinds of requirements.

You can navigate between group and node instances using links in their payloads. The API for a group instance provides a list of links to the node instances. The API for a node instance includes a link to its group instance.

Node Metadata

vFabric Administration Server manages a group as a single system image, so configuration files distributed to the nodes in a group are always identical. To customize the configuration on individual nodes, use node metadata. Node metadata are properties saved in the config/metadata.properties file in the directory where the vFabric Administration Server agent is installed on each node. The metadata.properties file is a standard Java properties file and can be edited with a text editor. However, the preferred method to set metadata is with the REST APIs, or the Python or Ruby libraries.

The GemFire and SQLFire REST APIs automatically resolve properties for instances against node metadata. For example, a SQLFire locator instance has properties bind-address, client-bind-address, and peer-discovery-address. To create a locator-instance you set these properties to the names of properties in the node metadata, not to actual addresses. The addresses for each node are then set on each node in the node metadata file.

Another way to use node metadata that works for any instance configuration file is to replace literal values in the configuration file with tokens called eyecatchers. An eyecatcher is a symbolic name enclosed in two pairs of at signs, for example @@var-name@@. When processing configuration files, the vFabric Administration Server agent on each node replaces eyecatchers with values looked up in the node metadata.

An example of a configuration task that requires using node metadata is setting up vFabric Web Server as a load balancer for a cluster of tc Runtime instances. This configuration requires that you add a jvmRoute attribute with a unique value to the Engine element in the Server.xml configuration file for each tc Runtime instance. To accomplish this, add a jvmRoute property to the node metadata for each node. Then, update the Server.xml file for the group instance, inserting the jvmRoute attribute with an eyecatcher as the value, for example:

<Engine name="Catalina" defaultHost="localhost" jvmRoute="@@jvmRoute@@">

vFabric Administration Server distributes the updated configuration file to each node, where the agent replaces the eyecatcher with the value from the local node metadata.