2.4. Editing a Broker's Configuration in a Fabric
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:
- Create a configuration template.
- Create a base profile for all of the brokers in the fabric using the configuration template.
- Create profiles that inherit from the base profile that will be assigned to one or more brokers.
- Modify the properties in each of the profiles to the desired values for the brokers to which the profile will be assigned.
- 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:
- Optionally create a new profile version using the fabric:version-create command.This will create a new copy of the existing profiles.
- 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 - 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 profileNameThis 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:
- 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 - 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 profileNameThe fabric properties for a broker are specified using the PIDorg.fusesource.mq.fabric.server-profileName, so to specify a value for the broker-name property for the profile calledmyBrokeryou 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 - 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.
