2.3. Editing a Broker's Configuration in a Fabric

Revision History
6/25/12
Moved the template material to a high-level section.

Abstract

Red Hat JBoss A-MQ supports deploying brokers into a cluster called a fabric. When a broker is deployed into a fabric, the Fabric Agent controls its configuration and you must use special commands to update it.

Overview

When a broker is part of a fabric, it does not manage its configuration. The broker's configuration is managed by the Fabric Agent. The agent runs along with the broker and updates the broker's configuration based on information from the fabric's registry.
Because the configuration is managed by the Fabric Agent, any changes to the broker's configuration needs to be done by updating the fabric's registry. In a fabric, broker configuration is determined by one or more profiles that are deployed into the broker. To change a broker's configuration, you must update the profile(s) deployed into the broker using either the console's fabric: shell or the management console.

Profiles

All configuration in a fabric is stored as profiles in the Fabric Registry. One or more profiles are assigned to brokers that are part of the fabric. A profile is a collection of configuration that specifies:
  • the Apache Karaf features to be deployed
  • OSGi bundles to be deployed
  • the repositories from which artifacts can be provisioned
  • properties that configure the broker's runtime behavior
The configuration profiles are collected into versions. Versions are typically used to make updates to an existing profile without effecting deployed brokers. When a container is configured it is assigned a profile version from which it draws the profiles. Therefore, when you create a new version and edit the profiles in the new version, the profiles that are in use are not changed. When you are ready to test the changes, you can roll them out incrementally by moving brokers to a new version one at a time.
When a broker joins a fabric, a Fabric Agent is deployed with the broker and takes control of the broker's configuration. The agent will ask the Fabric Registry what version and profile(s) are assigned to the broker and configure the broker based on the profiles. The agent will download and install of the specified bundles and features. It will also set all of the specified configuration properties.

Procedure

The recommended approach to configuring brokers in a fabric is:
  1. Create a configuration template.
    See Section 2.1, “Understanding the Red Hat JBoss A-MQ Configuration Model”.
  2. Create a base profile for all of the brokers in the fabric using the configuration template.
  3. Create profiles that inherit from the base profile that will be assigned to one or more brokers.
  4. Modify the properties in each of the profiles to the desired values for the brokers to which the profile will be assigned.
  5. Assign the new profiles to the desired brokers.
You should always create new profiles or a new version of the existing profiles before making configuration changes. Changes to profiles that are assigned to running brokers take effect immediately. Using new profiles, or a new version, allows you make the changes and test them on a subset of your brokers before rolling the changes to the entire fabric.

Creating a base profile

To create a base profile:
  1. Optionally create a new profile version using the fabric:version-create command.
    This will create a new copy of the existing profiles.
  2. Import the new XML template into the registry using the fabric:import command as shown in Example 2.4, “Creating a Profile Using an XML Configuration Template”.

    Example 2.3. Importing an XML Configuration Template

    JBossA-MQ:karaf@root> fabric:import -t /fabric/configs/versions/version/profiles/mq-base/xmlTemplate xmlTemplatePath
  3. Create a new configuration profile instance to hold the new XML template using the fabric:mq-create command as shown in Example 2.4, “Creating a Profile Using an XML Configuration Template”.

    Example 2.4. Creating a Profile Using an XML Configuration Template

    JBossAMQ:karaf@root> fabric:mq-create --config xmlTemplate profileName
    This will create a new profile that is based on the default broker profile but uses the imported XML template.

Creating deployment profiles and assigning them to brokers

To create deployment profiles and assigned them to the brokers:
  1. Create new profile using the fabric:profile-create command as shown in Example 2.5, “Creating a Deployment Profile”.

    Example 2.5. Creating a Deployment Profile

    JBossA-MQ:karaf@root> fabric:profile-create --parents baseProfile profileName
  2. Add values for the property placeholders using the fabric:profile-edit command as shown in Example 2.6, “Setting Properties in a Profile”.

    Example 2.6. Setting Properties in a Profile

    JBossAMQ:karaf@root> fabric:profile-edit -p org.fusesource.mq.fabric.server-profileName/propName=propVal profileName
    The fabric properties for a broker are specified using the PID org.fusesource.mq.fabric.server-profileName, so to specify a value for the broker-name property for the profile called myBroker you would use the command shown in Example 2.7, “Setting the Broker Name Property”.

    Example 2.7. Setting the Broker Name Property

    JBossAMQ:karaf@root> fabric:profile-edit -p org.fusesource.mq.fabric.server-myBroker/broker-name=esmeralda myBroker
  3. Assign the new profile to one or more brokers using the fabric:container-add-profile command as shown in Example 2.8, “Assigning a Profile to a Broker”.

    Example 2.8. Assigning a Profile to a Broker

    JBossAMQ:karaf@root> fabric:container-add-profile brokerName profileName

Using the management console

The management console simplifies the process of configuring brokers in a fabric by providing an easy to use Web-based interface and reducing the number of steps required to make the changes. For more information on using the management console see Using the Management Console.