-
Language:
English
-
Language:
English
Fabric Guide
A system for provisioning containers deployed across a network
Red Hat
Copyright © 2011-2015 Red Hat, Inc. and/or its affiliates.
Abstract
Chapter 1. An Overview of Fuse Fabric
Abstract
1.1. Concepts
Fabric
A sample fabric
Figure 1.1. Containers in a Fabric
Registry
- Configuration Registry—the logical configuration of your fabric, which typically contains no physical machine information. It contains details of the applications to be deployed and their dependencies.
- Runtime Registry—contains details of how many machines are actually running, their physical location, and what services they are implementing.
Fabric Ensemble
Fabric Server
Fabric Container (managed container)
Fabric Agent
Git
Profile
osgi:install
or features:install
, respectively), these modifications are impermanent. As soon as you restart the container or refresh its contents, the Fabric agent replaces the container's existing contents with whatever is specified by the deployed profiles.
1.2. Containers
- Java processes running directly on hardware.
- A PaaS (Platform as a Service) such as OpenShift for either a public or private cloud.
- OpenStack as an IaaS (Infrastructure as a Service).
- Amazon Web Services, Rackspace or some other IaaS to manage services.
- Docker containers for each service.
- An open hybrid cloud composing all of the above entries.
1.3. Provisioning and Configuration
Overview
Changing the configuration
How discovery works
Part I. Basic Fabric Deployment
Abstract
Chapter 2. Getting Started with Fuse Fabric
Abstract
2.1. Create a Fabric
Overview
Figure 2.1. A Sample Fabric with Child Containers
Steps to create the fabric
- To create the first fabric container, which acts as the seed for the new fabric, enter this console command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --new-user-role Administrator --zookeeper-password ZooPass --resolver manualip --manual-ip 127.0.0.1 --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
,--new-user-password
, and--new-user-role
options specify the credentials for a newAdministrator
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 loopback address,127.0.0.1
, as the Fabric Server's IP address.NoteA Fabric Server requires a static IP address. For simple trials and tests, you can use the loopback address,127.0.0.1
, to work around this requirement. But if you are deploying a fabric in production or if you want to create a distributed ensemble, you must assign a static IP address to the each of the Fabric Server hosts.NoteMost of the time, you are not prompted to enter the Zookeeper password when accessing the registry service, because it is cached in the current session. When you join a container to a fabric, however, you must provide the fabric's Zookeeper password. - Create a child container. Assuming that your root container is named
root
, enter this console command:JBossFuse:karaf@root> fabric:container-create-child root child The following containers have been created successfully: Container: child.
- Invoke the following command to monitor the status of the child container, as it is being provisioned:
JBossFuse:karaf@root> shell:watch container-list
After the deployment of thechild
has completed, you should see a listing something like this:JBossFuse:karaf@root> shell:watch container-list [id] [version] [alive] [profiles] [provision status] root 1.0 true fabric, fabric-ensemble-0000-1, fuse-esb-full success child 1.0 true default success
Type theReturn
key to get back to the JBoss Fuse console prompt.
2.2. Deploy a Profile
Deploy a profile to the child container
- Deploy the
quickstarts-beginner-camel.log
profile into thechild
container by entering this console command:JBossFuse:karaf@root> fabric:container-change-profile child quickstarts-beginner-camel.log
- Verify that the
quickstarts-beginner-camel.log
profile deploys successfully to thechild
container, using thefabric:container-list
command. Enter the following command to monitor the container status:JBossFuse:karaf@root> shell:watch container-list
And wait until thechild
container status changes tosuccess
.
View the sample output
quickstarts-beginner-camel.log
profile writes a message to the container's log every five seconds. To verify that the profile is running properly, you can look for these messages in the child container's log, as follows:
- Connect to the
child
container, by entering the following console command:JBossFuse:karaf@root> container-connect child
- After logging on to the
child
container, view thechild
container's log using thelog:tail
command, as follows:JBossFuse:karaf@root> log:tail
You should see some output like the following:2015-06-16 11:47:51,012 | INFO | #2 - timer://foo | log-route | ? ? | 153 - org.apache.camel.camel-core - 2.15.1.redhat-620123 | >>> Hello from Fabric based Camel route! : child 2015-06-16 11:47:56,011 | INFO | #2 - timer://foo | log-route | ? ? | 153 - org.apache.camel.camel-core - 2.15.1.redhat-620123 | >>> Hello from Fabric based Camel route! : child
- Type Ctrl-C to exit the log view and get back to the child container's console prompt.
- Type Ctrl-D to exit the child container's console, which brings you back to the root container console.
2.3. Update a Profile
Atomic container upgrades
Profile versioning
Upgrade to a new profile
quickstarts-beginner-camel.log
profile, when it is deployed and running in a container, follow the recommended procedure:
- Create a new version, 1.1, to hold the pending changes by entering this console command:
JBossFuse:karaf@root> fabric:version-create Created version: 1.1 as copy of: 1.0
The new version is initialised with a copy of all of the profiles from version 1.0. - Use the
fabric:profile-edit
command to change the message that is written to the container log by the Camel route. Enter the followingprofile-edit
command to edit thecamel.xml
resource:JBossFuse:karaf@root> fabric:profile-edit --resource camel.xml quickstarts-beginner-camel.log 1.1
This opens the built-in text editor for editing profile resources (see Appendix A, Editing Profiles with the Built-In Text Editor).Remember to specify version1.1
to thefabric:profile-edit
command, so that the modifications are applied to version 1.1 of thequickstarts-beginner-camel.log
profile.When you are finished editing, type Ctrl-S to save your changes and then type Ctrl-X to quit the text editor and get back to the console prompt. - Upgrade the
child
container to version1.1
by entering this console command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 child
Roll back to an old profile
quickstarts-beginner-camel.log
profile, using the fabric:container-rollback
command like this:
JBossFuse:karaf@root> fabric:container-rollback 1.0 child
2.4. Shutting Down the Containers
Shutting down the containers
fabric:container-stop
command. For example, to shut down the current fabric completely, enter these console commands:
JBossFuse:karaf@root> fabric:container-stop child JBossFuse:karaf@root> shutdown -f
fabric:container-start
console command.
Chapter 3. Creating a New Fabric
Abstract
Static IP address required for Fabric Server
- 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.
--resolver manualip --manual-ip StaticIPAddress
options to specify the static IP address explicitly, when creating a new Fabric Server.
Procedure
- (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 administrator privileges (Administrator
,SuperUser
, oradmin
roles). If theInstallDir/etc/users.properties
already contains users with administrator privileges, 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 A-MQ, start the local container as follows:
cd InstallDir/bin ./amq
- Create a new fabric by entering the following command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --new-user-role Administrator --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
,--new-user-password
, and--new-user-role
options specify the credentials for a newAdministrator
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 "fabric:create" in "Console Reference".For more details about resolver policies, see section "fabric:container-resolver-list" in "Console Reference" and section "fabric:container-resolver-set" in "Console Reference".
Fabric creation process
- The container installs the requisite OSGi bundles to become a Fabric Server.
- The Fabric Server starts a registry service, which listens on TCP port 2181 (which makes fabric configuration data available to all of the containers in the fabric).NoteYou can customize the value of the registry service port by specifying the
--zookeeper-server-port
option. - 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
- 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.
Chapter 4. Fabric Containers
4.1. Child Containers
Abstract
Overview
One container or many?
Creating a child container
fabric:container-create-child
command, specifying the parent container name and the name of the new child container. For example, to create the new child container, onlychild
, with root
as its parent, enter the following command:
fabric:container-create-child root onlychild
fabric:container-create-child root child 3
child1 child2 child3
Stopping and starting a child container
fabric:container-stop
command. For example, to shut down the child1
container:
fabric:container-stop child1
fabric:container-start
command, as follows:
fabric:container-start child1
ps
and kill
.
Deleting a child container
fabric:container-delete
command, as follows:
fabric:container-delete child1
4.2. SSH Containers
Abstract
Overview
Prerequisites
- Linux or UNIX operating system,
- SSHD running on the target host and:
- A valid account credentials, or
- Configured public key authentication
- Java is installed (for supported versions, see Red Hat JBoss A-MQ Supported Configurations).
- Curl installed.
- GNU tar installed.
- Telnet installed.
Creating an SSH container
fabric:container-create-ssh
console command, for creating SSH containers.
myhost
(accessible from the local network) with the SSH user account, myuser
, and the password, mypassword
, your could create an SSH container on myhost
, using the following console command:
fabric:container-create-ssh --host myhost --user myuser --password mypassword myremotecontainername
myuser
user on myhost
has configured public key authentication for SSH, you can skip the password option:
fabric:container-create-ssh --host myhost --user myuser myremotecontainername
~/.ssh/id_rsa
for authentication. If you need to use a different key, you can specify the key location explicitly with the --private-key
option:
fabric:container-create-ssh --host myhost --user myuser --private-key ~/.ssh/fabric_pk myremotecontainername
--pass-phrase
option, in case your key requires a pass phrase.
Creating a Fabric server using SSH
fabric:container-create-ssh
supports the --ensemble-server
option, which can be invoked to create a container which is a Fabric server. For example, the following container-create-ssh
command creates a new fabric consisting of one Fabric server on the myhost
host:
fabric:container-create-ssh --host myhost --user myuser --ensemble-server myremotecontainername
Managing remote SSH containers
fabric:container-stop myremotecontainername
fabric:container-start myremotecontainername
fabric:container-delete myremotecontainername
References
4.3. Fabric Containers on Windows
Abstract
Overview
Creating a Fabric container on Windows
- Following the instructions in the JBoss Fuse Installation Guide, manually install the JBoss Fuse product on the Windows target host.
- Open a new command prompt and enter the following commands to start the container on the target host:
cd InstallDir\bin fuse.bat
- If the Fabric servers from the Fabric ensemble are not already running, start them now.
- Join the container to the existing fabric, by entering the following console command:
JBossFuse:karaf@root> fabric:join --zookeeper-password ZooPass ZooHost:ZooPort Name
WhereZooPass
is the ZooKeeper password for the Fabric ensemble (specified when you create the fabric withfabric:create
);ZooHost
is the hostname (or IP address) where the Fabric server is running andZooPort
is the ZooKeeper port (defaults to2181
). If necessary, you can discover the ZooKeeper host and port by logging into the Fabric server and entering the following console command:config:proplist --pid io.fabric8.zookeeper
TheName
argument (which is optional) specifies a new name for the container after it joins the fabric. It is good practice to provide this argument, because all freshly installed containers have the nameroot
by default. If you do not specify a new container name when you join the fabric, there are bound to be conflicts.NoteThe container where you run thefabric:join
command must be a standalone container. It is an error to invokefabric:join
in a container that is already part of a fabric.
default
profile deployed on it.
Creating a Fabric server on Windows
- Following the instructions in the JBoss Fuse Installation Guide, manually install the JBoss Fuse product on the Windows target host.
- To start the container on the target host, open a new command prompt and enter the following commands:
cd InstallDir\bin fuse.bat
- To create a new fabric (thereby turning the current host into a Fabric server), enter the following console command:
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --new-user-role Administrator --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
,--new-user-password
, and--new-user-role
options specify the credentials for a newAdministrator
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”).
Managing remote containers on Windows
fabric:join
), there are certain restrictions on which commands you can use to manage it. In particular, the following commands are not supported:
fabric:container-stop fabric:container-start fabric:container-delete
4.4. Cloud Containers
Abstract
4.4.1. Preparing to use Fabric in the Cloud
Overview
Prerequisites
- A valid account with one of the cloud providers implemented by JClouds. The list of cloud providers can be found at JClouds supported providers.NoteIn the context of JClouds, the term supported provider does not imply commercial support for the listed cloud providers. It just indicates that there is an available implementation.
Hybrid clusters
- Fabric registry is running inside the public cloud.In this case, local containers will have no problem accessing the registry, as long as they are able to connect to the Internet.
- Cloud and local containers are part of a Virtual Private Network (VPN).If the Fabric registry is running on the premises, the cloud containers will not be able to access the registry, unless you set up a VPN (or make the registry accessible from the Internet, which is not recommended).
- Fabric registry is accessible from the Internet (not recommended).
Preparation
fabric:create
command. You cannot access the requisite cloud console commands until you create a Fabric locally.
JBossFuse:karaf@root> fabric:create --new-user AdminUser --new-user-password AdminPass --zookeeper-password ZooPass --wait-for-provisioning
--new-user
and --new-user-password
options specify the credentials for a new administrator user. The ZooPass
password specifies the password that is used to protect the Zookeeper registry.
JBossFuse:karaf@root> profile-list [id] [# containers] [parents] ... cloud-aws.ec2 0 cloud-base ... cloud-openstack 0 cloud-base cloud-servers.uk 0 cloud-base cloud-servers.us 0 cloud-base ...
cloud-aws.ec2
profile, as follows:
fabric:container-add-profile root cloud-aws.ec2
root
is the name of your local container.
Feature naming convention
cloud-aws.ec2
profile is the jclouds-aws-ec2
feature, which provides the necessary bundles for interacting with Amazon EC2:
JBossFuse:karaf@root> profile-display cloud-aws.ec2 Profile id: cloud-aws.ec2 Version : 1.0 ... Container settings ---------------------------- Features : jclouds-aws-ec2 ...
jclouds-aws-ec2
- Feature for the Amazon EC2 cloud provider.
jclouds-cloudservers-us
- Feature for the Rackspace cloud provider.
jclouds-ProviderID
, where ProviderID
is one of the provider IDs listed in the JClouds supported providers page. Or you can list the available JClouds features using the features:list
command:
features:list | grep jclouds
fabric:profile-edit --features jclouds-ProviderID MyProfile fabric:container-add-profile root MyProfile
Registering a cloud provider
fabric:cloud-service-add
console command (the registration process will store the provider credentials in the Fabric registry, so that they are available from any Fabric container).
fabric:cloud-service-add --name aws-ec2 --provider aws-ec2 --identity AccessKeyID --credential SecretAccessKey
--name
option is an alias that you use to refer to this registered cloud provider instance. It is possible to register the same cloud provider more than once, with different user accounts. The cloud provider alias thus enables you distinguish between multiple accounts with the same cloud provider.
4.4.2. Administering Cloud Containers
Creating a new fabric in the cloud
fabric:container-create-cloud
with the --ensemble-server
option, which creates a new Fabric server. For example, to create a Fabric server on Amazon EC2:
fabric:container-create-cloud --ensemble-server --name aws-ec2 --new-user AdminUser --new-user-password AdminPass --zookeeper-password ZooPass mycontainer
Basic security
fabric:container-create-cloud
command, to ensure that the new fabric is adequately protected. You need to specify the following security data:
- JAAS credentials—the
--new-user
and--new-user-password
options define JAAS credentials for a new user with administrative privileges on the fabric. These credentials can subsequently be used to log on to the JMX port or the SSH port of the newly created Fabric server. - ZooKeeper password—is used to protect the data stored in the ZooKeeper registry in the Fabric server. The only time you will be prompted to enter the ZooKeeper password is when you try to join a container to the fabric using the
fabric:join
command.
Joining a standalone container to the fabric
fabric:join -n --zookeeper-password ZooPass PublicIPAddress
PublicIPAddress
is the public host name or the public IP address of the compute instance that hosts the Fabric server (you can get this address either from the JBoss Fuse console output or from the Amazon EC2 console).
Creating a cloud container
fabric:container-create-cloud
command to create new Fabric containers in the cloud. For example to create a container on Amazon EC2:
fabric:container-create-cloud --name aws-ec2 mycontainer
fabric:container-create-cloud
command with the --os-family
option as follows:
fabric:container-create-cloud --name aws-ec2 --os-family centos mycontainer
--os-version
option:
fabric:container-create-cloud --name aws-ec2 --os-family centos --os-version 5 mycontainer
--image
option.
fabric:container-create-cloud --name aws-ec2 --image myimageid mycontainer
Looking up for compute service. Creating 1 nodes in the cloud. Using operating system: ubuntu. It may take a while ... Node fabric-f674a68f has been created. Configuring firewall. Installing fabric agent on container cloud. It may take a while... Overriding resolver to publichostname. [id] [container] [public addresses] [status] us-east-1/i-f674a68f cloud [23.20.114.82] success
Images
- Linux O/S
- RedHat or Debian packaging style
- Either no Java installed or Java 1.7+ installed. If there is no Java installed on the image, Fabric will install Java for you. If the wrong Java version is installed, however, the container installation will fail.
fabric:cloud-service-add --name aws-ec2 --provider aws-ec2 --identity AccessKeyID --credential SecretAccessKey --owner myownerid
Locations and hardware
jclouds:location-list
jclouds:hardware-list
fabric:container-create-cloud
command. For example:
fabric:container-create-cloud --name aws-ec2 --location eu-west-1 --hardware m2.4xlarge mycontainer
Chapter 5. Shutting Down a Fabric
Overview
Shutting down a managed container
fabric:container-stop
command and specify the name of the managed container, for example:
fabric:container-stop -f ManagedContainerName
-f
flag is required when shutting down a container that belongs to the ensemble.
fabric:container-stop
command looks up the container name in the registry and retrieves the data it needs to shut down that container. This approach works no matter where the container is deployed: whether on a remote host or in a cloud.
Shutting down a Fabric Server
registry1
, registry2
, and registry3
. You can shut down only one of these Fabric Servers at a time by using the fabric:container-stop
command, for example:
fabric:container-stop -f registry3
fabric:container-start registry3
Shutting down an entire fabric
fabric:ensemble-remove
and fabric:ensemble-add
commands. Each time you execute one of these commands, it creates a new ensemble. This new ensemble URL is propagated to all containers in the fabric and all containers need to reconnect to the new ensemble. There is a risk for TCP port numbers to be reallocated, which means that your network configuration might become out-of-date because services might start up on different ports.
- Three Fabric Servers (ensemble servers):
registry1
,registry2
,registry3
. - Four managed containers:
managed1
,managed2
,managed3
,managed4
.
- Use the
client
console utility to log on to one of the Fabric Servers in the ensemble. For example, to log on to theregistry1
server, enter a command in the following format:./client -u AdminUser -p AdminPass -h Registry1Host
ReplaceAdminUser
andAdminPass
with the credentials of a user with administration privileges. ReplaceRegistry1Host
with name of the host whereregistry1
is running. It is assumed that theregistry1
server is listening for console connections on the default TCP port (that is,8101
) - Ensure that all managed containers in the fabric are running. Execution of
fabric:container-list
should displaytrue
in thealive
column for each container. This is required for execution of thefabric:ensemble-remove
command, which is the next step. - Remove all but one of the Fabric Servers from the ensemble. For example, if you logged on to
registry1
, enter:fabric:ensemble-remove registry2 registry3
- Shut down all managed containers in the fabric, except the container on the Fabric Server you are logged into. In the following example, the first command shuts down
managed1
,managed2
,managed3
andmanaged4
:fabric:container-stop -f managed* fabric:container-stop -f registry2 fabric:container-stop -f registry3
- Shut down the last container that is still running. This is the container that is on the Fabric Server you are logged in to. For example:
shutdown -f
- Use the
client
console utility to log in to theregistry1
container host. - Start all containers in the fabric.
- Add the other Fabric Servers, for example:
fabric:ensemble-add registry2 registry3
Note on shutting down a complete fabric
fabric:container-stop -f registry1 fabric:container-stop -f registry2 fabric:container-stop -f registry3
fabric:container-stop
fails and throws an error because only one Fabric Server is still running. At least two Fabric Servers must be running to stop a container. With only one Fabric Server running, the registry shuts down and refuses service requests because a quorum of Fabric Servers is no longer available. The fabric:container-stop
command needs the registry to be running so it can retrieve details about the container it is trying to shut down.
Chapter 6. Fabric Profiles
Abstract
6.1. Introduction to Profiles
Overview
What is in a profile?
- OSGi bundle URLs
- Web ARchive (WAR) URLs
- Fuse Application Bundle (FAB) URLs
- OSGi Configuration Admin PIDs
- Apache Karaf feature repository URLs
- Apache Karaf features
- Maven artifact repository URLs
- Blueprint XML files or Spring XML files (for example, for defining broker configurations or Camel routes)
- Any kind of resource that might be needed by an application (for example, Java properties file, JSON file, XML file, YML file)
- System properties that affect the Apache Karaf container (analogous to editing
etc/config.properties
) - System properties that affect installed bundles (analogous to editing
etc/system.properties
)
Profile hierarchies
Some basic profiles
- [default]
- The
default
profile defines all of the basic requirements for a Fabric container. For example it specifies thefabric-agent
feature, the Fabric registry URL, and the list of Maven repositories from which artifacts can be downloaded. - [karaf]
- Inherits from the
default
profile and defines the Karaf feature repositories, which makes the Apache Karaf features accessible. - [feature-camel]
- Inherits from
karaf
, defines the Camel feature repositories, and installs some core Camel features: such ascamel-core
andcamel-blueprint
. If you are deploying a Camel application, it is recommended that you inherit from this profile. - [feature-cxf]
- Inherits from
karaf
, defines the CXF feature repositories, and installs some core CXF features. If you are deploying a CXF application, it is recommended that you inherit from this profile. - [mq-base]
- Inherits from the
karaf
profile and installs themq-fabric
feature - [mq-default]
- Inherits from the
mq-base
profile and provides the configuration for an A-MQ broker. Use this profile, if you want to deploy a minimal installation of an ActiveMQ broker. - [jboss-fuse-full]
- Includes all of the features and bundles required for the JBoss Fuse full container.
6.2. Working with Profiles
Changing the profiles in a container
fabric:container-change-profile
command as follows:
fabric:container-change-profile mycontainer myprofile
myprofile
profile to the mycontainer
container. All profiles previously assigned to the container are removed. You can also deploy multiple profiles to the container, with the following command:
fabric:container-change-profile mycontainer myprofile myotherprofile
Adding a profile to a container
fabric:container-add-profile
command gives you a simple way to add profiles to a container, without having to list all of the profiles that were already assigned. For example, to add the example-camel
profile to the mycontainer
container:
fabric:container-add-profile mycontainer example-camel
Listing available profiles
fabric:profile-list
console command:
fabric:profile-list
Inspecting profiles
fabric:profile-display
command. For example, to display what is defined in the feature-camel
profile, enter the following command:
fabric:profile-display feature-camel
Profile id: feature-camel Version : 1.0 Attributes: parents: karaf Containers: Container settings ---------------------------- Repositories : mvn:org.apache.camel.karaf/apache-camel/${version:camel}/xml/features Features : camel-core camel-blueprint fabric-camel Configuration details ---------------------------- Other resources ---------------------------- Resource: io.fabric8.insight.metrics.json
feature-camel
profile, taking into account all of its ancestors, you must specify the --overlay
switch, as follows:
fabric:profile-display --overlay feature-camel
--display-resources
switch (or -r
for short) to the profile-display
command, as follows:
fabric:profile-display -r feature-camel
Creating a new profile
fabric:profile-create
command, as follows:
fabric:profile-create myprofile
--parents
option to the command:
fabric:profile-create --parents feature-camel myprofile
Adding or removing features
fabric:profile-edit
command. For example, to add the camel-jclouds
feature to the feature-camel
profile.
fabric:profile-edit --feature camel-jclouds feature-camel
fabric:profile-display
command to see what the camel profile looks like now. You should see that the camel-jclouds
feature appears in the list of features for the feature-camel
profile.
Features : camel-jclouds camel-blueprint/2.9.0.fuse-7-061 camel-core/2.9.0.fuse-7-061 fabric-camel/99-master-SNAPSHOT
--delete
option. For example, if you need to remove the camel-jclouds
feature, you could use the following command:
fabric:profile-edit --delete --feature camel-jclouds feature-camel
Editing PID properties
- Edit the PID using the built-in text editor—the Karaf console has a built-in text editor which you can use to edit profile resources such as PID properties. To start editing a PID using the text editor, enter the following console command:
fabric:profile-edit --pid PID ProfileName
For more details about the built-in text editor, see Appendix A, Editing Profiles with the Built-In Text Editor. - Edit the PID inline, using console commands—alternatively, you can edit PIDs directly from the console, using the appropriate form of the
fabric:profile-edit
command. This approach is particularly useful for scripting. For example, to set a specific key-value pair,Key=Value
, in a PID, enter the following console command:fabric:profile-edit --pid PID/Key=Value ProfileName
Editing a PID inline
fabric:profile-edit
command:
- Assign a value to a PID property, as follows:
fabric:profile-edit --pid PID/Key=Value ProfileName
- Append a value to a delimited list (that is, where the property value is a comma-separated list), as follows:
fabric:profile-edit --append --pid PID/Key=ListItem ProfileName
- Remove a value from a delimited list, as follows:
fabric:profile-edit --remove --pid PID/Key=ListItem ProfileName
- Delete a specific property key, as follows:
fabric:profile-edit --delete --pid PID/Key ProfileName
- Delete a complete PID, as follows:
fabric:profile-edit --delete --pid PID ProfileName
Example of editing a PID inline
io.fabric8.agent
PID, changing the Maven repository list setting. The default
profile contains a section like this:
Agent Properties : org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2, http://repo.fusesource.com/nexus/content/repositories/releases, http://repo.fusesource.com/nexus/content/groups/ea, http://repository.springsource.com/maven/bundles/release, http://repository.springsource.com/maven/bundles/external, http://scala-tools.org/repo-releases
io.fabric8.agent
PID. So, by modifying the io.fabric8.agent
PID, we effectively change the agent properties. You can modify the list of Maven repositories in the agent properties PID as follows:
fabric:profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories=http://repositorymanager.mylocalnetwork.net default
fabric:profile-display
on the default
profile, you should see agent properties similar to the following:
Agent Properties : org.ops4j.pax.url.mvn.repositories = http://repositorymanager.mylocalnetwork.net
Setting encrypted PID property values
- Use the
fabric:encrypt-message
command to encrypt the property value, as follows:fabric:encrypt-message PropValue
This command returns the encrypted property value,EncryptedValue
.NoteThe default encryption algorithm used by Fabric isPBEWithMD5AndDES
. - You can now set the property to the encrypted value,
EncryptedValue
, using the following syntax:my.sensitive.property = ${crypt:EncryptedValue}
For example, using thefabric:profile-edit
command, you can set an encrypted value as follows:fabric:profile-edit --pid com.example.my.pid/my.sensitive.property=${crypt:EncryptedValue} Profile
Alternative method for encrypting PID property values
- Use the Jasypt
encrypt
command-line tool to encrypt the property value, as follows:./encrypt.sh input="Property value to be encrypted" password=ZooPass verbose=false
This command returns the encrypted property value,EncryptedValue
.NoteThe default encryption algorithm used by Fabric isPBEWithMD5AndDES
. You must ensure that theencrypt.sh
utility is using the same algorithm as Fabric.
Customizing the PID property encryption mechanism
- Customize the master password for encryption—using the following console command:
fabric:crypt-password-set MasterPassword
You can retrieve the current master password by entering thefabric:crypt-password-get
command. The default value is the ensemble password (as returned byfabric:ensemble-password
). - Customize the encryption algorithm—using the following console command:
fabric:crypt-algorithm-set Algorithm
Where the encryption algorithm must be one of the algorithms supported by the underlying Jasypt encryption toolkit. You can retrieve the current encryption algorithm by entering thefabric:crypt-algorithm-get
command. The default isPBEWithMD5AndDES
.
Profile editor
fabric:profile-edit
command without any options, as follows:
fabric:profile-edit Profile [Version]
Editing resources with the profile editor
broker.xml
file in the mq-amq
profile, enter the following console command:
fabric:profile-edit --resource broker.xml mq-amq
6.3. Profile Versions
Overview
fabric-agent
, will choose the defined version and retrieve all the information provided by the specific version of the profile.
Creating a new version
fabric:version-create
command (analogous to creating a new branch in the underlying Git repository). The default version is 1.0. To create version 1.1, enter the following command:
fabric:version-create 1.1
fabric:version-create --description "expanding all camel routes" 1.1
.
feature-camel
profile:
fabric:profile-display --version 1.1 feature-camel
fabric:profile-edit
command, specifying the version right after the profile argument. For example, to add the camel-jclouds
feature to version 1.1 of the feature-camel
profile, enter the following command:
fabric:profile-edit --feature camel-jclouds feature-camel 1.1
Rolling upgrades and rollbacks
mycontainer
container to the 1.1 version, invoke the fabric:container-upgrade
command as follows:
fabric:container-upgrade 1.1 mycontainer
mycontainer
to use version 1.1 of all the profiles currently assigned to it.
fabric:container-rollback
command, as follows:
fabric:container-rollback 1.0 mycontainer
--all
option, as follows:
fabric:container-upgrade --all 1.1 mycontainer
Chapter 7. Fabric8 Maven Plug-In
Abstract
7.1. Preparing to Use the Plug-In
Edit your Maven settings
~/.m2/settings.xml
file to add the fabric server's user and password so that the maven plugin can log in to the fabric. For example, you could add the following server
element to your settings.xml
file:
<settings> <servers> <server> <id>fabric8.upload.repo</id> <username>Username</username> <password>Password</password> </server> ... </servers> </settings>
Username
and Password
are the credentials of a Fabric user with administrative privileges (for example, the credentials you would use to log on to the Management Console).
Customising the repository ID
fabric8.upload.repo
. You can specify additional server
elements in your settings.xml
file for each of the fabrics you need to work with. To select the relevant credentials, you can set the serverId
property in the Fabric8 Maven plug-in configuration
section (see Section 7.4, “Configuration Properties”) or set the fabric8.serverId
Maven property.
7.2. Using the Plug-In to Deploy a Maven Project
Prerequisites
- Your Maven
~/.m2/settings.xml
file is configured as described in Section 7.1, “Preparing to Use the Plug-In”. - A JBoss Fuse container instance is running on your local machine (alternatively, if the container instance is running on a remote host, you must configure the plug-in's
jolokiaUrl
property appropriately).
Running the plug-in on any Maven project
mvn io.fabric8:fabric8-maven-plugin:1.0.0.redhat-355:deploy
Adding the plug-in to a Maven POM
pom.xml
file as follows:
<plugins> <plugin> <groupId>io.fabric8</groupId> <artifactId>fabric8-maven-plugin</artifactId> <version>1.2.0.redhat-621084</version> <configuration> <profile>testprofile</profile> <version>1.2</version> </configuration> </plugin> </plugins>
plugin/configuration/version
element specifies the Fabric8 version of the target system (which is not necessarily the same as the version of the Fabric8 Maven plug-in).
mvn fabric8:deploy
What does the plug-in do?
- Uploads any artifacts into the fabric's maven repository,
- Lazily creates the Fabric profile or version you specify,
- Adds/updates the maven project artifact into the profile configuration,
- Adds any additional parent profile, bundles or features to the profile.
Example
quickstart
examples, as follows:
cd InstallDir/quickstarts/rest mvn io.fabric8:fabric8-maven-plugin:1.0.0.redhat-355:deploy
7.3. Configuring the Plug-In
Specifying profile information
configuration
element to the plug-in configuration in your pom.xml
file, as follows:
<plugins>
<plugin>
<groupId>io.fabric8</groupId>
<artifactId>fabric8-maven-plugin</artifactId>
<configuration>
<profile>my-thing</profile>
</configuration>
</plugin>
</plugins>
Multi-module Maven projects
pom.xml foo/ pom.xml a/pom.xml b/pom.xml ... bar/ pom.xml c/pom.xml d/pom.xml ...
pom.xml
file, as follows:
<plugins> <plugin> <groupId>io.fabric8</groupId> <artifactId>fabric8-maven-plugin</artifactId> </plugin> </plugins>
foo/pom.xml
file you need only define the fabric8.profile
property, as follows:
<project> ... <properties> <fabric8.profile>my-foo</fabric8.profile> ... </properties> ... </project>
foo
folder, such as foo/a
and foo/b
, will deploy to the same profile (in this case the profile, my-foo
). You can use the same approach to put all of the projects under the bar
folder into a different profile too.
fabric8.profile
property to specify exactly where it gets deployed; along with any other property on the plug-in (see the Property Reference below).
Specifying features, additional bundles, repositories and parent profiles
<plugins> <plugin> <groupId>io.fabric8</groupId> <artifactId>fabric8-maven-plugin</artifactId> <configuration> <profile>my-rest</profile> <features>fabric-cxf-registry fabric-cxf cxf war swagger</features> <featureRepos>mvn:org.apache.cxf.karaf/apache-cxf/${version:cxf}/xml/features</featureRepos> </configuration> </plugin> </plugins>
features
element allows you to specify a space-separated list of features to include in the profile.
Configuring with Maven properties
fabric8.
. For example, to deploy a maven project to the cheese
profile name, enter the command:
mvn fabric8:deploy -Dfabric8.profile=cheese
fabric8.upload=false
—for example:
mvn fabric8:deploy -Dfabric8.upload=false
Specifying profile resources
src/main/fabric8
, in your Maven project and add any resource files or a ReadMe.md
file to your project, they will automatically be uploaded into the profile as well. For example, if you run the following commands from your Maven project directory:
mkdir -p src/main/fabric8 echo "## Hello World" >> src/main/fabric8/ReadMe.md mvn fabric8:deploy
ReadMe.md
wiki page.
7.4. Configuration Properties
Specifying properties
configuration
element of the plug-in in your project's pom.xml
file. For example, the profile
property can be set as follows:
<plugins> <plugin> <groupId>io.fabric8</groupId> <artifactId>fabric8-maven-plugin</artifactId> <configuration> <profile>${fabric8.profile}</profile> </configuration> </plugin> </plugins>
fabric8.
. For example, to set the profile name, you could add the following property to your pom.xml
file:
<project> ... <properties> <fabric8.profile>my-foo</fabric8.profile> ... </properties> ...
mvn fabric8:deploy -Dfabric8.profile=my-foo
Property reference
configuration
element in the pom.xml
file or as Maven properties, when prefixed by fabric8.
):
Parameter | Description |
---|---|
abstractProfile
|
Specifies whether the profile is abstract. Default is false .
|
artifactBundleType
|
Type to use for the project artifact bundle reference. |
artifactBundleClassifier
|
Classifier to use for the project artifact bundle reference. |
baseVersion
|
If the version does not exist, the baseVersion provides the initial values for the newly created version. This is like creating a branch from the baseVersion for a new version branch in git.
|
bundles
|
Space-separated list of additional bundle URLs (of the form mvn:groupId/artifactId/version ) to add to the newly created profile. Note you do not have to include the current Maven project artifact; this configuration is intended as a way to list dependent required bundles.
|
featureRepos
|
Space-separated list of feature repository URLs to add to the profile. The URL has the general form mvn:groupId/artifactId/version/xml/features .
|
features
|
Space-separated list of features to add to the profile. For example, the following setting would include both the camel feature and the cxf feature: <features>camel cxf</features>
|
generateSummaryFile
|
Whether or not to generate a Summary.md file from the pom.xml file's description element text value. Default is true .
|
ignoreProject
|
Whether or not we should ignore this maven project in goals like fabric8:deploy or fabric8:zip . Default is false .
|
includeArtifact
|
Whether or not we should add the Maven deployment unit to the Fabric profile. Default is true .
|
includeReadMe
|
Whether or not to upload the Maven project's ReadMe file, if no specific ReadMe file exists in the your profile configuration directory (as set by profileConfigDir ). Default is true .
|
jolokiaUrl
|
The Jolokia URL of the JBoss Fuse Management Console. Defaults to http://localhost:8181/jolokia .
|
locked
|
Specifies whether or not the profile should be locked. |
minInstanceCount
|
The minimum number of instances of this profile which we require to run. Default is 1 .
|
parentProfiles
|
Space-separated list of parent profile IDs to be added to the newly created profile. Defaults to karaf .
|
profile
|
The name of the Fabric profile to deploy your project to. Defaults to the groupId-artifactId of your Maven project.
|
profileConfigDir
|
The folder in your Maven project containing resource files to be deployed into the profile, along with the artifact configuration. Defaults to src/main/fabric8 . You should create the directory and add any configuration files or documentation you wish to add to your profile.
|
profileVersion
|
The profile version in which to update the profile. If not specified, it defaults to the current version of the fabric. |
replaceReadmeLinksPrefix
|
If provided, then any links in the ReadMe.md files will be replaced to include the given prefix.
|
scope
|
The Maven scope to filter by, when resolving the dependency tree. Possible values are: compile , provided , runtime , test , system , import .
|
serverId
|
The server ID used to lookup in ~/.m2/settings/xml for the server element to find the username and password to log in to the fabric. Defaults to fabric8.upload.repo .
|
upload
|
Whether or not the deploy goal should upload the local builds to the fabric's Maven repository. You can disable this step if you have configured your fabric's Maven repository to reuse your local Maven repository. Defaults to true .
|
useResolver
|
Whether or not the OSGi resolver is used for bundles or Karaf based containers to deduce the additional bundles or features that need to be added to your projects dependencies to be able to satisfy the OSGi package imports. Defaults to true .
|
webContextPath
|
The context path to use for Web applications, for projects using war packaging.
|
Chapter 8. ActiveMQ Brokers and Clusters
Abstract
fabric:mq-create
command to create and deploy clusters of brokers.
8.1. Creating a Single Broker Instance
MQ profiles
mq-base
- An abstract profile, which defines some important properties and resources for the broker, but should never be used directly to instantiate a broker.
mq-default
- A basic single broker, which inherits most of its properties from the
mq-base
profile.
fabric:profile-display
command, as follows:
JBossFuse:karaf@root> fabric:profile-display mq-default ... JBossFuse:karaf@root> fabric:profile-display mq-base ...
Creating a new broker instance
mq-default
profile.
mq-default
broker instance called broker1
, enter the following console command:
JBossFuse:karaf@root>fabric:container-create-child --profile mq-default root broker1 The following containers have been created successfully: broker1
broker1
with a broker of the same name running on it.
fabric:mq-create command
fabric:mq-create
command provides a short cut to creating a broker, but with more flexibility, because it also creates a new profile. To create a new broker instance called brokerx
using fabric:mq-create
, enter the following console command:
JBossFuse:karaf@root> fabric:mq-create --create-container broker --replicas 1 brokerx MQ profile mq-broker-default.brokerx ready
fabric:container-create-child
command, fabric:mq-create
creates a container called broker1
and runs a broker instance on it. There are some differences, however:
- The new
broker1
container is implicitly created as a child of the current container, - The new broker has its own profile,
mq-broker-default.brokerx
, which is based on themq-base
profile template, - It is possible to edit the
mq-broker-default.brokerx
profile, to customize the configuration of this new broker. - The
--replicas
option lets you specify the number of master/slave broker replicas (for more details, see Section 8.3.2, “Master-Slave Cluster”). In this example, we specify one replica (the default is two).
mq-broker-Group.BrokerName
by default. If you want the profile to have the same name as the broker (which was the default in JBoss A-MQ version 6.0), you can specify the profile name explicitly using the --profile
option.
Starting a broker on an existing container
fabric:mq-create
command can be used to deploy brokers on existing containers. Consider the following example, which creates a new Fuse MQ broker in two steps:
JBossFuse:karaf@root> fabric:container-create-child root broker1 The following containers have been created successfully: broker1 JBossFuse:karaf@root> fabric:mq-create --assign-container broker1 brokerx MQ profile mq-broker-default.brokerx ready
mq-broker-default.brokerx
profile to the container, by invoking fabric:mq-create
with the --assign-container
option. Of course, instead of deploying to a local child container (as in this example), we could assign the broker to an SSH container or a cloud container.
Broker groups
fabric:mq-create
command are always registered with a specific broker group. If you do not specify the group name explicitly at the time you create the broker, the broker gets registered with the default
group by default.
--group
option of the fabric:mq-create
command. For example, to create a new broker that registers with the west-coast
group, enter the following console command:
JBossFuse:karaf@root> fabric:mq-create --create-container broker --replicas 1 --group west-coast brokery MQ profile mq-broker-default.brokery ready
west-coast
group does not exist prior to running this command, it is automatically created by Fabric. Broker groups are important for defining clusters of brokers, providing the underlying mechanism for creating load-balancing clusters and master-slave clusters. For details, see Section 8.3, “Topologies”.
8.2. Connecting to a Broker
Overview
default
group.
Client URL
discovery:(fabric:GroupName)
default
group, the client would use the following URL:
discovery:(fabric:default)
Example client profiles
example-mq
profile into a container. The example-mq
profile instantiates a pair of messaging clients: a producer client, that sends messages continuously to the FABRIC.DEMO
queue on the broker; and a consumer client, that consumes messages from the FABRIC.DEMO
queue.
example-mq
profile, by entering the following command:
JBossFuse:karaf@root> fabric:container-create-child --profile example-mq root example
example
container is successfully provisioned, using the following console command:
JBossFuse:karaf@root> watch container-list
JBossFuse:karaf@root> container-connect example JBossFuse:karaf@example> log:display
8.3. Topologies
8.3.1. Load-Balancing Cluster
Overview
loadbal
, and with three brokers registered in the group: brokerx
, brokery
, and brokerz
. This type of topology is ideal for load balancing non-persistent messages across brokers and for providing high-availability.
Figure 8.1. Load-Balancing Cluster
Create brokers in a load-balancing cluster
- Choose a group name for the load-balancing cluster.
- Each broker in the cluster registers with the chosen group.
- Each broker must be identified by a unique broker name.
- Normally, each broker is deployed in a separate container.
loadbal
and the cluster consists of three broker instances with broker names: brokerx
, brokery
, and brokerz
.
- First of all create some containers:
JBossFuse:karaf@root> container-create-child root broker 3 The following containers have been created successfully: Container: broker1. Container: broker2. Container: broker3.
- Wait until the containers are successfully provisioned. You can conveniently monitor them using the
watch
command, as follows:JBossFuse:karaf@root> watch container-list
- You can then assign broker profiles to each of the containers, using the
fabric:mq-create
command, as follows:JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker1 brokerx MQ profile mq-broker-loadbal.brokerx ready JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker2 brokery MQ profile mq-broker-loadbal.brokery ready JBossFuse:karaf@root> mq-create --group loadbal --assign-container broker3 brokerz MQ profile mq-broker-loadbal.brokerz ready
- You can use the
fabric:profile-list
command to see the new profiles created for these brokers:JBossFuse:karaf@root> profile-list --hidden [id] [# containers] [parents] ... mq-broker-loadbal.brokerx 1 mq-base mq-broker-loadbal.brokery 1 mq-base mq-client-loadbal ...
- You can use the
fabric:cluster-list
command to view the cluster configuration for this load balancing cluster:JBossFuse:karaf@root> cluster-list [cluster] [masters] [slaves] [services] ... fusemq/loadbal brokerx broker1 - tcp://MyLocalHost:50394 brokery broker2 - tcp://MyLocalHost:50604 brokerz broker3 - tcp://MyLocalHost:50395
Configure clients of a load-balancing cluster
discovery:(fabric:GroupName)
, which automatically load balances the client across the available brokers in the cluster. For example, to connect a client to the loadbal
cluster, you would use a URL like the following:
discovery:(fabric:loadbal)
mq-create
command automatically generates a profile named mq-client-GroupName
, which you can combine either with the example-mq-consumer
profile or with the example-mq-producer
profile to create a client of the load-balancing cluster.
loadbal
group, you can deploy the mq-client-loadbal
profile and the example-mq-consumer
profile together in a child container, by entering the following command:
JBossFuse:karaf@root> container-create-child --profile mq-client-loadbal --profile example-mq-consumer root consumer The following containers have been created successfully: Container: consumer.
loadbal
group, you can deploy the mq-client-loadbal
profile and the example-mq-producer
profile together in a child container, by entering the following command:
JBossFuse:karaf@root> container-create-child --profile mq-client-loadbal --profile example-mq-producer root producer The following containers have been created successfully: Container: producer.
JBossFuse:karaf@root> container-connect consumer JBossFuse:admin@consumer> log:display 2014-01-16 14:31:41,776 | INFO | Thread-42 | ConsumerThread | io.fabric8.mq.ConsumerThread 54 | 110 - org.jboss.amq.mq-client - 6.1.0.redhat-312 | Received test message: 982 2014-01-16 14:31:41,777 | INFO | Thread-42 | ConsumerThread | io.fabric8.mq.ConsumerThread 54 | 110 - org.jboss.amq.mq-client - 6.1.0.redhat-312 | Received test message: 983
8.3.2. Master-Slave Cluster
Overview
masterslave
, and three brokers that compete with each other to register as the broker, hq-broker
. A broker becomes the master by acquiring a lock (where the lock implementation is provided by the underlying ZooKeeper registry). The other two brokers that fail to acquire the lock remain as slaves (but they continue trying to acquire the lock, at regular time intervals).
Figure 8.2. Master-Slave Cluster
Create brokers in a master-slave cluster
- Choose a group name for the master-slave cluster.
- Each broker in the cluster registers with the chosen group.
- Each broker must be identified by the same virtual broker name.
- Normally, each broker is deployed in a separate container.
masterslave
and the cluster consists of three broker instances, each with the same broker name: hq-broker
. You can create this cluster by entering a single fabric:mq-create
command, as follows:
JBossFuse:karaf@root> mq-create --create-container broker --replicas 3 --group masterslave hq-broker
broker1
, broker2
and broker3
(possibly running on separate machines), you can deploy a cluster of three brokers to the containers by entering the following command:
JBossFuse:karaf@root> mq-create --assign-container broker1,broker2,broker3 --group masterslave hq-broker
Configure clients of a master-slave cluster
discovery:(fabric:GroupName)
, which automatically connects the client to the current master server. For example, to connect a client to the masterslave
cluster, you would use a URL like the following:
discovery:(fabric:masterslave)
mq-client-masterslave
, to create sample clients. For example, to create an example consumer client in its own container, enter the following console command:
JBossFuse:karaf@root> container-create-child --profile mq-client-masterslave --profile example-mq-consumer root consumer The following containers have been created successfully: Container: consumer.
JBossFuse:karaf@root> container-create-child --profile mq-client-masterslave --profile example-mq-producer root producer The following containers have been created successfully: Container: producer.
Locking mechanism
Re-using containers for multiple clusters
broker1
, broker2
, and broker3
, already running the hq-broker
cluster, it is possible to reuse the same containers for another highly available broker cluster, web-broker
. You can assign the web-broker
profile to the existing containers with the following command:
mq-create --assign-container broker1,broker2,broker3 web-broker
web-broker
profile to the same containers already running hq-broker
. Fabric automatically prevents two masters from running on the same container, so the master for hq-broker
will run on a different container from the master for web-broker
. This arrangement makes optimal use of the available resources.
Configuring persistent data
fabric:mq-create
command enables you to specify the location of the data directory, as follows:
mq-create --assign-container broker1 --data /var/activemq/hq-broker hq-broker
hq-broker
virtual broker, which uses the /var/activemq/hq-broker
directory for the data (and store) location. You can then mount some shared storage to this path and share the storage amongst the brokers in the master-slave cluster.
8.3.3. Broker Networks
Overview
Broker networks
Creating network connectors
--network
option to the fabric:mq-create
command.
Example broker network
Figure 8.3. Broker Network with Master-Slave Clusters
- The first cluster has the group name,
us-west
, and provides high-availability with a master-slave cluster of two brokers,us-west1
andus-west2
. - The second cluster has the group name,
us-east
, and provides high-availability with a master-slave cluster of two brokers,us-east1
andus-east2
.
us-east
group (consisting of the two containers us-east1
and us-east2
), you would log on to a root container running in the US East location and enter a command like the following:
mq-create --group us-east --network us-west --networks-username User --networks-password Pass --create-container us-east us-east
--network
option specifies the name of the broker group you want to connect to, and the User
and Pass
are the credentials required to log on to the us-west
broker cluster. By default, the fabric:mq-create
command creates a master/slave pair of brokers.
us-west
group (consisting of the two containers us-west1
and us-west2
), you would log on to a root container running in the US West location and enter a command like the following:
mq-create --group us-west --network us-east --networks-username User --networks-password Pass --create-container us-west us-west
User
and Pass
are the credentials required to log on to the us-east
broker cluster.
--assign-container
option in place of --create-container
.
Connecting to the example broker network
discovery:(fabric:us-east)
discovery:(fabric:us-west)
8.4. Alternative Master-Slave Cluster
Why use an alternative master-slave cluster?
Alternative locking mechanism
- Disable the default Zookeeper locking mechanism (which can be done by setting
standalone=true
in the broker'sio.fabric8.mq.fabric.server-BrokerName
PID). - Enable the shared file system master/slave locking mechanism in the KahaDB persistence layer (see section "Shared File System Master/Slave" in "Fault Tolerant Messaging").
standalone property
standalone
property belongs to the io.fabric8.mq.fabric.server-BrokerName
PID and is normally used for a non-Fabric broker deployment (for example, it is set to true
in the etc/io.fabric8.mq.fabric.server-broker.cfg
file). By setting this property to true
, you instruct the broker to stop using the discovery and coordination services provided by Fabric (but it is still possible to deploy the broker in a Fabric container). One consequence of this is that the broker stops using the Zookeeper locking mechanism. But this setting has other side effects as well.
Side effects of setting standalone=true
standalone=true
, on a broker deployed in Fabric has the following effects:
- Fabric no longer coordinates the locks for the brokers (hence, the broker's persistence adapter needs to be configured as shared file system master/slave instead).
- The broker no longer uses the
ZookeeperLoginModule
for authentication and falls back to using thePropertiesLoginModule
instead. This requires users to be stored in theetc/users.properties
file or added to thePropertiesLoginModule
JAAS Realm in the container where the broker is running for the brokers to continue to accept connections - Fabric discovery of brokers no longer works (which affects client configuration).
Configuring brokers in the cluster
- Set the property,
standalone=true
, in each broker'sio.fabric8.mq.fabric.server-BrokerName
PID. For example, given a broker with the broker name,brokerx
, which is configured by the profile,mq-broker-default.brokerx
, you could set thestandalone
property totrue
using the following console command:profile-edit --pid io.fabric8.mq.fabric.server-brokerx/standalone=true mq-broker-default.brokerx
- To customize the broker's configuration settings further, you need to create a unique copy of the broker configuration file in the broker's own profile (instead of inheriting the broker configuration file from the base profile,
mq-base
). If you have not already done so, follow the instructions in the section called “Customizing the broker configuration file” to create a custom broker configuration file for each of the broker's in the cluster. - Configure each broker's KahaDB persistence adapter to use the shared file system locking mechanism. For this you must customize each broker configuration file, adding or modifying (as appropriate) the following XML snippet:
<broker ... > ... <persistenceAdapter> <kahaDB directory="/sharedFileSystem/sharedBrokerData" lockKeepAlivePeriod="5000"> <locker> <shared-file-locker lockAcquireSleepInterval="10000" /> </locker> </kahaDB> </persistenceAdapter> ... </broker>
You can edit this profile resource either though the Fuse Management Console, through the Git configuration approach (see Section 8.5, “Broker Configuration”), or using thefabric:profile-edit
command.
Configuring authentication data
standalone=true
on a broker, it can no longer use the default ZookeeperLoginModule
authentication mechanism and falls back on the PropertiesLoginModule
. This implies that you must populate authentication data in the etc/users.properties
file on each of the hosts where a broker is running. Each line of this file takes an entry in the following format:
Username=Password,Role1,Role2,...
Username
and Password
credentials and a list of one or more roles, Role1, Role2,...
.
Configuring a client
failover:(tcp://broker1:61616,tcp://broker2:61616,tcp://broker3:61616)
8.5. Broker Configuration
Overview
Setting OSGi Config Admin properties
broker1
profile created by entering the following fabric:mq-create
command:
fabric:mq-create --create-container broker --replicas 1 --network us-west brokerx
mq-broker-default.brokerx
, and assigns this profile to the newly created broker1
container.
mq-broker-Group.BrokerName
by default. If you want the profile to have the same name as the broker (which was the default in JBoss A-MQ version 6.0), you can specify the profile name explicitly using the --profile
option.
mq-broker-default.brokerx
profile using the fabric:profile-display
command, as follows:
JBossFuse:karaf@root> profile-display mq-broker-default.brokerx Profile id: mq-broker-default.brokerx Version : 1.0 Attributes: parents: mq-base Containers: broker Container settings ---------------------------- Configuration details ---------------------------- PID: io.fabric8.mq.fabric.server-brokerx replicas 1 standby.pool default broker-name brokerx keystore.password JA7GNMZV data ${runtime.data}brokerx keystore.file profile:keystore.jks ssl true kind MasterSlave truststore.file profile:truststore.jks keystore.cn localhost connectors openwire mqtt amqp stomp truststore.password JA7GNMZV keystore.url profile:keystore.jks config profile:ssl-broker.xml group default network us-west Other resources ---------------------------- Resource: keystore.jks Resource: truststore.jks
io.fabric8.mq.fabric.server-brokerx
PID are a variety of property settings, such as network
and group
. You can now modify the existing properties or add more properties to this PID to customize the broker configuration.
Modifying basic configuration properties
io.fabric8.mq.fabric.server-brokerx
PID by invoking the fabric:profile-edit
command, with the appropriate syntax for modifying PID properties.
network
property to us-east
, enter the following console command:
profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network=us-east mq-broker-default.brokerx
Customizing the SSL keystore.jks and truststore.jks file
mq-broker-default.brokerx
profile when SSL is enabled (which is the default case):
keystore.jks
- A Java keystore file containing this broker's own X.509 certificate. The broker uses this certificate to identify itself to other brokers in the network. The password for this file is stored in the
io.fabric8.mq.fabric.server-brokerx/keystore.password
property. truststore.jks
- A Java truststore file containing one or more Certificate Authority (CA) certificates or other certificates, which are used to verify the certificates presented by other brokers during the SSL handshake. The password for this file is stored in the
io.fabric8.mq.fabric.server-brokerx/truststore.password
property.
mq-broker-default.brokerx
profile, perform the following steps:
- If you have not done so already, clone the git repository that stores all of the profile data in your Fabric. Enter a command like the following:
git clone -b 1.0 http://Username:Password@localhost:8181/git/fabric cd fabric
WhereUsername
andPassword
are the credentials of a Fabric user withAdministrator
role and we assume that you are currently working with profiles in version1.0
(which corresponds to the git branch named1.0
).NoteIn this example, it is assumed that the fabric is set up to use the git cluster architecture (which is the default) and also that the Fabric server running onlocalhost
is currently the master instance of the git cluster. - The
keystore.jks
file and thetruststore.jks
file can be found at the following locations in the git repository:fabric/profiles/mq/broker/default.brokerx.profile/keystore.jks fabric/profiles/mq/broker/default.brokerx.profile/truststore.jks
Copy your custom versions of thekeystore.jks
file andtruststore.jks
file to these locations, over-writing the default versions of these files. - You also need to modify the corresponding passwords for the keystore and truststore. To modify the passwords, edit the following file in a text editor:
fabric/profiles/mq/broker/default.brokerx.profile/io.fabric8.mq.fabric.server-brokerx.properties
Modify thekeystore.password
andtruststore.password
settings in this file, to specify the correct password values for your custom JKS files. - When you are finished modifying the profile configuration, commit and push the changes back to the Fabric server using git, as follows:
git commit -a -m "Put a description of your changes here!" git push
- For these SSL configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the
broker
container, you would restart thebroker
container as follows:fabric:container-stop broker fabric:container-start broker
Customizing the broker configuration file
ssl-broker.xml
, for an SSL-enabled broker; and broker.xml
, for a non-SSL-enabled broker.
mq-base
parent profile). The easiest way to make this kind of change is to use a git repository of profile data that has been cloned from a Fabric ensemble server.
mq-broker-default.brokerx
profile, perform the following steps:
- It is assumed that you have already cloned the git repository of profile data from the Fabric ensemble server (see the section called “Customizing the SSL keystore.jks and truststore.jks file”). Make sure that you have checked out the branch corresponding to the profile version that you want to edit (which is assumed to be
1.0
here). It is also a good idea to do a git pull to ensure that your local git repository is up-to-date. In your git repository, enter the following git commands:git checkout 1.0 git pull
- The default broker configuration files are stored at the following location in the git repository:
fabric/profiles/mq/base.profile/ssl-broker.xml fabric/profiles/mq/base.profile/broker.xml
Depending on whether your broker is configured with SSL or not, you should copy either thessl-broker.xml
file or thebroker.xml
file into your broker's profile. For example, assuming that your broker uses themq-broker-default.brokerx
profile and is configured to use SSL, you would copy the broker configuration as follows:cp fabric/profiles/mq/base.profile/ssl-broker.xml fabric/profiles/mq/broker/default.brokerx.profile/
- You can now edit the copy of the broker configuration file, customizing the broker's Spring XML configuration as required.
- When you are finished modifying the broker configuration, commit and push the changes back to the Fabric server using git, as follows:
git commit -a -m "Put a description of your changes here!" git push
- For the configuration changes to take effect, a restart of the affected broker (or brokers) is required. For example, assuming that the modified profile is deployed on the
broker
container, you would restart thebroker
container as follows:fabric:container-stop broker fabric:container-start broker
Additional broker configuration templates in mq-base
mq-base
profile, which can then be used as templates for creating new brokers with the fabric:mq-create
command. Additional template configurations must be added to the following location in the git repository:
fabric/profiles/mq/base.profile/
--config
option to the fabric:mq-create
command.
mybrokertemplate.xml
, has just been installed:
fabric/profiles/mq/base.profile/mybrokertemplate.xml
mybrokertemplate.xml
configuration template by invoking the fabric:mq-create
command with the --config
option, as follows:
fabric:mq-create --config mybrokertemplate.xml brokerx
--config
option assumes that the configuration file is stored in the current version of the mq-base
profile, so you need to specify only the file name (that is, the full ZooKeeper path is not required).
Setting network connector properties
network.NetworkPropName
. For example, to add the setting, network.bridgeTempDestinations=false
, to the PID for brokerx
(which has the profile name, mq-broker-default.brokerx
), enter the following console command:
profile-edit --pid io.fabric8.mq.fabric.server-brokerx/network.bridgeTempDestinations=false mq-broker-default.brokerx
Network connector properties by reflection
network.OptionName
can be used to set the corresponding OptionName
property on the org.apache.activemq.network.NetworkBridgeConfiguration
class. In particular, this implies you can set any of the following network.OptionName
properties:
Property | Default | Description |
---|---|---|
name | bridge | Name of the network - for more than one network connector between the same two brokers, use different names |
userName | None | Username for logging on to the remote broker port, if authentication is enabled. |
password | None | Password for logging on to the remote broker port, if authentication is enabled. |
dynamicOnly | false | If true , only activate a networked durable subscription when a corresponding durable subscription reactivates, by default they are activated on start-up. |
dispatchAsync | true | Determines how the network bridge sends messages to the local broker. If true , the network bridge sends messages asynchronously. |
decreaseNetworkConsumerPriority | false | If true , starting at priority -5 , decrease the priority for dispatching to a network Queue consumer the further away it is (in network hops) from the producer. If false , all network consumers use same default priority (that is, 0 ) as local consumers. |
consumerPriorityBase | -5 | Sets the starting priority for consumers. This base value will be decremented by the length of the broker path when decreaseNetworkConsumerPriority is set. |
networkTTL | 1 | The number of brokers in the network that messages and subscriptions can pass through (sets both messageTTL and consumerTTL ) |
messageTTL | 1 | The number of brokers in the network that messages can pass through. |
consumerTTL | 1 | The number of brokers in the network that subscriptions can pass through (keep to 1 in a mesh). |
conduitSubscriptions | true | Multiple consumers subscribing to the same destination are treated as one consumer by the network. |
duplex | false | If true , a network connection is used both to produce and to consume messages. This is useful for hub and spoke scenarios, when the hub is behind a firewall, and so on. |
prefetchSize | 1000 | Sets the prefetch size on the network connector's consumer. It must be greater than 0 , because network consumers do not poll for messages |
suppressDuplicateQueueSubscriptions | false | If true , duplicate subscriptions in the network that arise from network intermediaries are suppressed. For example, consider brokers A , B , and C , networked using multicast discovery. A consumer on A gives rise to a networked consumer on B and C . In addition, C networks to B (based on the network consumer from A ) and B networks to C . When true , the network bridges between C and B (being duplicates of their existing network subscriptions to A ) will be suppressed. Reducing the routing choices in this way provides determinism when producers or consumers migrate across the network as the potential for dead routes (stuck messages) are eliminated. The networkTTL value needs to match or exceed the broker count to require this intervention. |
suppressDuplicateTopicSubscriptions | true | If true , duplicate network topic subscriptions (in a cyclic network) are suppressed. |
bridgeTempDestinations | true |
Whether to broadcast advisory messages for temporary destinations created in the network of brokers. Temporary destinations are typically created for request-reply messages. Broadcasting the information about temp destinations is turned on by default, so that consumers of a request-reply message can be connected to another broker in the network and still send back the reply on the temporary destination specified in the
JMSReplyTo header. In an application scenario where most or all of the messages use the request-reply pattern, this generates additional traffic on the broker network, because every message typically sets a unique JMSReplyTo address (which causes a new temp destination to be created and broadcasted with an advisory message in the network of brokers).
If you disable this feature, this network traffic can be reduced, but in this case the producers and consumers of a request-reply message need to be connected to the same broker. Remote consumers (that is, connected through another broker in your network) will not be able to send the reply message, but instead will raise a
temp destination does not exist exception.
|
alwaysSyncSend | false | If true , non-persistent messages are sent to the remote broker using request/reply semantics instead of oneway message semantics. This setting affects both persistent and non-persistent messages the same way. |
staticBridge | false | If true , the broker does not respond dynamically to new consumers. It uses only staticallyIncludedDestinations to create demand subscriptions. |
useCompression | false | Compresses the message body when sending it over the network. |
advisoryForFailedForward | false | If true , send an advisory message when the broker fails to forward the message to the temporary destination across the bridge. |
useBrokerNamesAsIdSeed | true | Add the broker name as a prefix to connections and consumers created by the network bridge. It helps with visibility. |
gcDestinationViews | true | If true , remove any MBeans for destinations that have not been used for a while. |
gcSweepTime | 60000 | The period of inactivity in milliseconds, after which we remove MBeans. |
checkDuplicateMessagesOnDuplex | false | If true , check for duplicates on the duplex connection. |
Part II. Fabric in Production
Abstract
Chapter 9. Fabric Ensemble and Registry
Abstract
9.1. Fabric Registry
Overview
Registry structure
fabric | +----registry (runtime registry) | | | +----containers | | | +----root | +----configs (configuration registry) | +----versions | | | +----1.0 | | | +----profiles | | | +----default | +----containers
Parts of the registry
- Configuration Registry—the logical configuration of your fabric, which typically contains no physical machine information. It contains details of the applications to be deployed and their dependencies.
- Runtime Registry—contains details of how many machines are actually running, their physical location, and what services they are implementing.
Making the registry highly available
9.2. Administering a Fabric Ensemble
Recommendations for an ensemble in production
- Deploy a minimum of five Fabric servers in production (if one server is taken down for maintenance, one other server can fail, and the Fabric registry will still be available).
- Fabric servers should be deployed on separate host machines.
- Each Fabric server should only have a Fabric registry agent deployed inside it. No other profiles should be deployed in it.
- The size of the ensemble should be fixed at the outset, and not changed later (if you subsequently add or remove containers from the ensemble, the ZooKeeper IP ports would be re-assigned).
Creating an ensemble
- Create an initial ensemble, consisting of one Fabric server.
- Expand the ensemble, by adding an even number of containers.
Creating an initial ensemble
fabric:create
console command (which converts the current container into a Fabric server, which is a sole member of the newly created ensemble). Alternatively, when creating a new container with the fabric:container-create-ssh
or fabric:container-create-cloud
commands, you can pass the --ensemble-server
option.
fabric:create
command, see Chapter 3, Creating a New Fabric.
Expanding the ensemble
fabric:ensemble-add
command. To expand the ensemble, perform the following steps:
- Create some new managed containers in the current fabric, which you can then add to the ensemble. Use the default profile for these new containers. For a production environment, it is recommended that you create at least four new managed containers (must be an even number), each running on their own host.
- While logged on to a container in the fabric, use the
fabric:ensemble-add
command to add the managed containers to the ensemble. For example, given the four managed containers,container1
,container2
,container3
, andcontainer4
, you would enter the following command:fabric:ensemble-add container1 container2 container3 container4
NoteYou must specify an even number of containers to thefabric:ensemble-add
command. - To check that the ensemble has been successfully created, invoke the
fabric:container-list
command.
Taking a Fabric server down for maintenance
fabric:container-stop
command, specifying the name of the Fabric server.
Chapter 10. Fabric Agents
Abstract
10.1. Introduction
Fabric agent
- Retrieves the profiles and versions assigned to the container on which it is running.
- Reconfigures the container.
- Calculates what needs to be installed, removed or updated on the container.
- Performs the requisite install, remove, and update actions.
Agent modules
- [fabric-configadmin]
- The Fabric configuration admin bridge. Translates the registry information into configuration information.
- [fabric-agent]
- The deployment agent. Reads the translated configuration and provisions the container accordingly.
10.2. The Configuration Admin Bridge
Overview
Information in a profile
- Configuration information—which includes:
- System configuration
- OSGi configuration
- Provisioning information—which includes lists of:
- Bundles
- Karaf features
Actions performed
io.fabric8.agent
PID (in the context of the OSGi Configuration Admin service, a PID is a named collection of property settings).
io.fabric8.agent
PID, even when there are multiple assigned profiles.
io.fabric8.agent
PID.
Configuration updates
10.3. The Deployment Agent
Actions performed
io.fabric8.agent
PID. Any change in that configuration will trigger the deployment agent.
- The deployment agent reads the whole
io.fabric8.agent
PID and calculates what bundles are to be installed in the container. - If the profiles assigned to the container specify any Karaf features, the deployment agent translates them into a list of bundles, so that the agent obtains a complete list of bundles to install.
- The deployment agent compares the list of bundles to install with the list of bundles currently installed, in order to identify:
- Bundles to uninstall,
- Bundles to install,
- Bundles to update.
- The deployment agent then performs the bundle uninstalling, installing, and updating in the container.
Downloading artifacts
- Registered Fabric Maven proxies
- Configured Maven repositories (any Maven repository configured in the profile overlay).
org.ops4j.pax.url.mvn.repositories
property of the io.fabric8.agent
PID.
org.ops4j.pax.url.mvn.repositories
property using the fabric:profile-edit
command:
fabric:profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories=http://repositorymanager.mylocalnetwork.net default
default
profile, which is the ancestor of all of the standard profiles, is the ideal place for this.
Container restarts
- Changes to the OSGi framework;
- Changes to the OSGi framework configuration.
Monitoring the provisioning status
fabric:container-list
command.
JBossFuse:karaf@root> fabric:container-list [id] [version] [alive] [profiles] [provision status] root* 1.0 true fabric, fabric-ensemble-0000-1 success mq1 1.0 true mq success mq2 1.0 true mq downloading billing-broker 1.0 true billing success admin-console 1.0 true web, admin-console success
fabric:container-list
command as an argument to the shell:watch
command, as follows:
shell:watch fabric:container-list
Resolution and startup ordering
Import-Package
- For each package listed here, the OBR resolver searches for a bundle that declares the package in a corresponding
Export-Package
header. Import-Service
- For each service listed here, the OBR resolver searches for a bundle that declares the service in a corresponding
Export-Service
header.
Export-Service
header to bundles that implement services. Blueprint configuration files with mandatory references to services will automatically be packaged with the Import-Service
bundle header (assuming that you use the maven-bundle-plugin
). If the bundle that exports the service does not explicitly specify an Export-Service
header, resolution will fail. To fix this error, either the exporter bundle must add an Export-Service
declaration, or the importer bundle must remove the Import-Service
directive.
Chapter 11. Allocating Ports
Abstract
11.1. The Port Service
What is the port service?
- Ports clashing with third-party services—a server machine in a production environment often has multiple services deployed on it, with a wide range of IP ports in use. In this environment, there is a relatively large risk that a Fabric container could clash with existing IP ports.
- Ports clashing with other Fabric containers—when multiple Fabric containers are deployed on the same host, it is necessary to configure their standard services with different IP ports. Setting the IP ports manually would be a considerable nuisance (and error prone).
- Ports clashing within a container—a port clash can also occur within a single container, if multiple services are competing for the same ports (for example, multiple routes binding to the same ports). Because Fabric containers are highly dynamic, we need to be able to prevent port clashes in this case, and ports must be allocated and de-allocated as services come and go.
Benefits of the port service
- Avoiding port clashes for standard container services
- Avoiding port clashes for custom services
Avoiding port clashes for standard container services
Avoiding port clashes for custom services
Using the port service in your own applications
- Use the OSGi Config Admin service to define a key, whose value is a port range. Use the following syntax to define a key:
KeyID = ${port:MinValue,MaxValue}
The preceding syntax defines the key,KeyID
, whereMinValue
specifies the minimum value of the IP port, andMaxValue
specifies the maximum value of the IP port. You can create this key using the standard Karaf commands for editing persistent IDs (PIDs) and their keys (using thefabric:profile-edit
command with the--pid
option in a Fabric container).For example, if you are logged into a Fabric container, you can see that thedefault
profile defines the key,org.osgi.service.http.port
, which specifies the container's Jetty port, as follows:FuseFabric:karaf@root> fabric:profile-display default ... PID: org.ops4j.pax.web org.ops4j.pax.web.config.checksum ${checksum:profile:jetty.xml} org.ops4j.pax.web.config.url profile:jetty.xml javax.servlet.context.tempdir ${karaf.data}/pax-web-jsp org.osgi.service.http.port ${port:8181,8282}
- In your application's XML configuration (either Spring XML or Blueprint XML), replace the literal port value in the service's address by a property placeholder—for example,
${org.osgi.service.http.port}
—which substitutes the value of the key defined in step 1.For a complete example of how to configure the property placeholder, see Section 11.2, “Using the Port Service”.
How the port service allocates a port
${port:9090,9190}
) running on a specific target host, when you start up the service for the first time, the port service allocates a port as follows:
- Determines which ports in the range are already in use on the target host (whether local or remote), by actually trying to bind to the ports.
- Checks the registered ports in the ZooKeeper registry for all of the containers deployed on the target host (even if the containers are currently not running).
- Allocates the first free port, within the specified range, that does not clash with any of the ports discovered in steps 1 and 2.
How allocated ports are stored
/fabric/registry/ports/
KeyID
, is filed under its corresponding persistent ID, PID
, and container name, ContainerName
, as follows:
/fabric/registry/ports/containers/ContainerName/PID/KeyID
Child1
, the key for the child container's Jetty port would be stored in the following ZooKeeper node:
/fabric/registry/ports/containers/Child1/org.ops4j.pax.web/org.osgi.service.http.port
Keys used by the standard container services
/fabric/registry/ports/containers/ContainerName/org.apache.karaf.shell/sshPort /fabric/registry/ports/containers/ContainerName/org.ops4j.pax.web/org.osgi.service.http.port /fabric/registry/ports/containers/ContainerName/org.apache.karaf.management/rmiServerPort /fabric/registry/ports/containers/ContainerName/org.apache.karaf.management/rmiRegistryPort
Behavior upon stopping and restarting a container
- The ports used by the container's services remain constant (after the initial allocation has occurred). You can advertise the ports to clients and be confident that the ports will remain valid over the long term.
- If, while the container is stopped, another service binds to one of the container's ports, there is a port clash when the container restarts, and the affected service fails to start (but at least we can guarantee that Fabric will not cause such a clash, because Fabric deliberately avoids re-using allocated container ports).
Deallocating ports
fabric:container-delete
command), Fabric deallocates all of the ports assigned to that container, so that they become available for use again by services in other containers. In other words, when the ContainerName
container is deleted, all of the key entries under /fabric/registry/ports/containers/ContainerName
are deleted from the ZooKeeper registry.
11.2. Using the Port Service
Overview
example-camel-cxf
profile as an example. There are two basic steps to configuring the port service in your application:
- At development time—using the property placeholder service, replace a service's fixed port number by a key.
- At deployment time—using the OSGi Config Admin service, specify the key value as a port range. For example, you can specify the key value as a PID property setting in a Fabric profile.
Demonstration code
example-camel-cxf
profile. The source code for the example is taken from the fabric-camel-cxf
example on Github, which is available from the following URL:
https://github.com/fabric8io/fabric8/tree/1.x/fabric/fabric-examples/fabric-camel-cxf
Property placeholder in XML configuration
src/main/resources/OSGI-INF/blueprint/cxf.xml
, in the fabric-camel-cxf
demonstration):
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:cxf="http://camel.apache.org/schema/blueprint/cxf" xmlns:cm="http://aries.apache.org/blueprint/xmlns/blueprint-cm/v1.1.0" xsi:schemaLocation=" http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd http://camel.apache.org/schema/blueprint/cxf http://camel.apache.org/schema/blueprint/cxf/camel-cxf.xsd"> <cm:property-placeholder id="placeholder" persistent-id="io.fabric8.examples.camel.cxf" update-strategy="reload"> <cm:default-properties> <cm:property name="greeterPort" value="9090"/> </cm:default-properties> </cm:property-placeholder> <cxf:cxfEndpoint id="greeterEndpoint" address="http://localhost:${greeterPort}/greeter" serviceClass="io.fabric8.examples.camelcxf.Greeter"> <cxf:features> <bean class="io.fabric8.cxf.endpoint.ManagedApiFeature"/> </cxf:features> </cxf:cxfEndpoint> ... </blueprint>
cxf:cxfEndpoint
element. In the address
attribute, the port number is specified by substituting the greeterPort
key, ${greeterPort}
. The property placeholder mechanism is configured by the cm:property-placeholder
element, which specifies that the greeterPort
property belongs to the io.fabric8.examples.camel.cxf
PID. The property placeholder mechanism is integrated with the OSGi Config Admin service, which allows you to override the port number at deployment time.
Specifying a port range using OSGi Config Admin
example-camel-cxf
profile, the port number is integrated with the port service and specified as a port range.
example-camel-cxf
Fabric profile. You can see the configured port range by entering the following console command:
JBossFuse:karaf@root> fabric:profile-display example-camel-cxf
io.fabric8.examples.camel.cxf
persistent ID:
... Configuration details ---------------------------- PID: io.fabric8.examples.camel.cxf greeterPort ${port:9090,9190} ...
greeterPort
key is set to ${port:9090,9190}
.
Modifying the port range
example-camel-cxf
profile, you can do so using the fabric:profile-edit
console command. For example, to change the value of greeterPort
to the range, ${port:7070,7170}
, you would enter the following console command:
JBossFuse:karaf@root> fabric:profile-edit --pid io.fabric8.examples.camel.cxf/greeterPort=\$\{port:7070,7170\} example-camel-cxf
$
sign and the curly braces, { }
, must be escaped by the backslash character, \
, as shown. Alternatively, if you prefer to edit the port range using the built-in text editor, you can enter the following console command instead:
JBossFuse:karaf@root> fabric:profile-edit --pid io.fabric8.examples.camel.cxf example-camel-cxf
Chapter 12. Gateway
Abstract
12.1. Gateway Architecture
Deployment strategies
- Run the gateway on each machine that needs to discover services and communicate with it through
localhost
. In this case, you do not need to hard code any host names in your messaging or Web clients and the connection to the gateway onlocalhost
is nice and fast. - Run the gateway on one or more known hosts using DNS or VIP load balancing (mapping host names to machines). In thise case, you can use a fixed host name for all your services
How the gateway works
12.2. Running the Gateway
Deploy a gateway profile
gateway-mq
- Profile for a messaging gateway (for accessing Apache ActiveMQ brokers in the fabric).
gateway-http
- Profile for a HTTP gateway (for Web applications or Web services).
12.3. Configuring the Gateway
Configuring with the Management Console
HTTP mapping rules
example-quickstarts-rest
profile, that uses a URI like /cxf/crm/customerservice/customers/123
on whatever host and port it is deployed on. Hence, by default, it is visible on the gateway at http://localhost:9000/cxf/crm/customerservice/customers/123. For this example, the URI template is:
{contextPath}/
/cxf/crm
) and append /
, giving /cxf/crm/
. Any request within that path is then passed to an instance of the CXF crm
service.
Selecting part of the ZooKeeper registry
ZooKeeper Path | Description |
---|---|
/fabric/registry/clusters/apis/rest
|
REST based web services |
/fabric/registry/clusters/apis/ws
|
SOAP based web services |
/fabric/registry/clusters/servlets
|
Servlets (registered usually individually via the OSGI APIs) |
/fabric/registry/clusters/webapps
|
Web Applications (i.e. WARs) |
Segregating URI paths
/api/
and Web applications to be available under /app/
, update the URI templates as follows:
ZooKeeperPath: /fabric/registry/clusters/apis URI template: /api{contextPath}/
ZooKeeperPath: /fabric/registry/clusters/webapps URI template: /app{contextPath}/
ZooKeeperPath: /fabric/registry/clusters/apis/rest URI template: /rest{contextPath}/ ZooKeeperPath: /fabric/registry/clusters/apis/ws URI template: /ws{contextPath}/
12.4. Versioning
Explicit URIs
/version/{version}{contextPath}/
1.0
and 1.1
versions of a profile that packages Web services or Web applications, you can now access the different versions using version-specific URIs. For example, if you are running version 1.0
and version 1.1
implementations of the example-quickstarts-rest
profile, you can access either one through the following URIs:
- Version 1.0 through http://localhost:9000/version/1.0/cxf/crm/customerservice/customers/123
- Version 1.1 through http://localhost:9000/version/1.1/cxf/crm/customerservice/customers/123
Rolling upgrades
1.0
version of the gateway-http
profile and run a few services, you will see all 1.0
versions of them. If you run some 1.1
versions of these services, the gateway will not see them. If you now do a rolling upgrade of your gateway to version 1.1
, it will switch to showing only the 1.1
versions of the services.
12.5. URI Template Expressions
Variables
Expression | Description |
---|---|
{bundleName}
|
The name of the bundle that registers the Web service, servlet or application. This variable is currently not supported for Web services, but works for Web applications and servlets in an OSGi container. |
{bundleVersion}
|
The version of the bundle that registers the Web service, servlet or application. This variable is currently not supported for Web services, but works for Web applications and servlets in an OSGi container. |
{container}
|
The container ID of the container where the Web service or Web application is deployed. |
{contextPath}
|
The context path (the part of the URL after the host and port) of the Web service or Web application implementation. |
{servicePath}
|
The relative path within ZooKeeper that a service is registered. This is usually is made up of, for web services as the service name and version. For web applications its often the maven coordinates |
{version}
|
The profile version of the Web service or Web application. |
Chapter 13. Securing Fabric Containers
Abstract
Default authentication system
io.fabric8.jaas.ZookeeperLoginModule
). This system allows you to define user accounts and assign passwords and roles to the users. Out of the box, the user credentials are stored in the Fabric registry, unencrypted.
Managing users
jaas:*
family of console commands. First of all you need to attach the jaas:*
commands to the ZookeeperLoginModule
login module, as follows:
JBossFuse:karaf@root> jaas:realms Index Realm Module Class 1 karaf org.apache.karaf.jaas.modules.properties.PropertiesLoginModule 2 karaf org.apache.karaf.jaas.modules.publickey.PublickeyLoginModule 3 karaf io.fabric8.jaas.ZookeeperLoginModule JBossFuse:karaf@root> jaas:manage --index 3
jaas:*
commands to the ZookeeperLoginModule
login module. You can then add users and roles, using the jaas:useradd
and jaas:roleadd
commands. Finally, when you are finished editing the user data, you must commit the changes by entering the jaas:update
command, as follows:
JBossFuse:karaf@root> jaas:update
jaas:cancel
.
Obfuscating stored passwords
ZookeeperLoginModule
stores passwords in plain text. You can provide additional protection to passwords by storing them in an obfuscated format. This can be done by adding the appropriate configuration properties to the io.fabric8.jaas
PID and ensuring that they are applied to all of the containers in the fabric.
Enabling LDAP authentication
LDAPLoginModule
), which you can enable by adding the requisite configuration to the default profile.
Chapter 14. Fabric Maven Proxies
Abstract
14.1. Cluster of Fabric Maven Proxies
Overview
Figure 14.1. Maven Proxy Cluster
Master-slave cluster
Maven proxy
- The Maven proxy builds up a large cache over time, which can be served up quickly to other containers in the Fabric.
- It is not necessary for every container to download Maven artifacts from remote repositories—the Maven proxy performs this service for the other containers.
- In a network with limited Internet access, you can arrange to deploy the Maven proxy on a host with Internet access, while the other containers in the fabric are deployed on hosts without Internet access.
Managed container
Resolving a Maven artifact
- The Fabric8 agent searches its local Maven repository for the artifact.
- If that fails, the Fabric8 agent contacts the Maven proxy to request the artifact.
- If that fails, the Fabric8 agent attempts to contact remote Maven repositories directly to request the artifact.
Endpoint discovery
Which Fabric server is the current master?
fabric:cluster-list
console command, as follows:
JBossFuse:karaf@root> cluster-list servlets/io.fabric8.fabric-maven-proxy [cluster] [masters] [slaves] [services] [] 1.2.0.redhat-621084/maven/download root root - http://127.0.0.1:8181/maven/download 1.2.0.redhat-621084/maven/upload root root - http://127.0.0.1:8181/maven/upload
root
container) in this Fabric ensemble. This command returns two URLs: one for downloading artifacts (http://127.0.0.1:8181/maven/download
), and another for uploading artifacts (http://127.0.0.1:8181/maven/upload
). For more details about uploading artifacts, see Section 14.6, “Automated Deployment”.
What happens during failover?
- The URLs for the master Maven proxy are changed. Clients must now connect to a different URL to connect to the Maven proxy. For Fabric8 agents, this failover is transparent, because the Fabric8 agent automatically rediscovers the new URLs.
- If you have been automatically uploading artifacts to the Maven proxy as part of your build process (see Section 14.6, “Automated Deployment”), you will need to reconfigure the upload URL. In this case, failover is not transparent.
- It is likely that the new master has a much smaller cache of Maven artifacts than the old master. This could result in noticeable delays, because many previously cached artifacts have to be downloaded again.
No replication
Managing the Maven artifact data
UserHome/.m2/repository
). You could simply do a manual copy of the contents of the local Maven repository from one Maven proxy host to another. Or for a more sophisticated approach, you can try storing the local Maven repository on a networked file system.
14.2. How a Managed Container Resolves Artifacts
Overview
system/
directory or in its local Maven repository) it tries to download the missing artifact from the fabric's Maven proxy server (master instance). In other words, downloading from the Maven proxy is the primary mechanism for managed containers to obtain new artifacts.
Fabric profiles drive bundle provisioning
bundle.BundleName
entry to the profile's agent properties. Provisioning can also be triggered when you edit other resources (not directly associated with OSGi Config Admin) in a profile—for example, by referencing a resource through a checksum property resolver (see Section C.6, “Checksum property resolver”).
Fabric8 agent
mvn
URL scheme, the Fabric8 agent is responsible for locating these new bundles through Maven. In the context of Fabric, the Fabric8 agent effectively plays the same role that the Pax URL Aether component plays in a standalone (non-Fabric) container.
mvn
URL, reads the relevant Maven configuration properties, and calls directly into the Eclipse Aether layer to resolve the referenced artifact.
Eclipse Aether layer
Provisioning a managed container
Figure 14.2. Provisioning a Managed Container
Provisioning steps
- Provisioning of a profile is triggered when the properties of a current profile are updated. In particular, whenever new bundles or features are added to a profile, the Fabric8 agent is responsible for resolving the new Maven artifacts (referenced through the
mvn
URL protocol). - The Fabric8 agent reads its Maven configuration from the
io.fabric8.agent
PID in thedefault
profile (and possibly also from a Mavensettings.xml
file, if so configured). - The Fabric8 agent contacts Zookeeper to discover the repository URL of the Fabric8 Maven proxy (master instance)—see Section 14.1, “Cluster of Fabric Maven Proxies”. The Fabric8 agent then inserts the discovered Maven proxy URL at the head of the list of remote Maven repositories.The Fabric8 agent parses the requested Maven URL and combines this information with the specified configuration—including the discovered Maven proxy URL—in order to invoke the Eclipse Aether library.
- When the Aether library is invoked, the first step is to look up any local Maven repositories to try and find the Maven artifact. The following local repositories are configured by default:
InstallDir/system
- The JBoss A-MQ system directory, which contains all of the Maven artifacts that are bundled with the JBoss A-MQ distribution.
UserHome/.m2/repository
- The user's own local Maven repository in the user's home directory,
UserHome
.
If the Maven artifact is found locally, skip straight to step 8. - If the Maven artifact cannot be found in one of the local repositories, Aether next tries to download the artifact from the Maven proxy. If the Maven artifact is found in the Maven proxy, skip straight to step 7.NoteIf you configure the Fabric8 agent to use a HTTP proxy, the Maven proxy would also be accessed through the HTTP proxy. To bypass the HTTP proxy in this case, you could configure the Maven proxy host to be a HTTP non-proxy host—see the section called “Configuring a HTTP proxy”.
- Aether next tries to look up the specified remote repositories (using the list of remote repositories specified in the Fabric8 agent configuration). Because the remote repositories are located on the Internet (accessed through the HTTP protocol), it is necessary to have Internet access in order for this step to succeed.NoteIf your local network requires you to use a HTTP proxy to access the Internet, it is possible to configure Fabric8 to use a HTTP proxy. For example, see the section called “Configuring a HTTP proxy” for details.
- If the Maven artifact is found in the Maven proxy or in a remote repository, Aether automatically installs the artifact into the user's local Maven repository, so that another remote lookup will not be required.
- Finally, assuming that the Maven artifact has been successfully resolved, Karaf installs the artifact in the Karaf bundle cache,
InstallDir/data/cache
, and loads the artifact (usually, an OSGi bundle) into the container runtime. At this point, the artifact is effectively installed in the container.
io.fabric8.agent configuration
io.fabric8.agent
PID (also known as agent properties). The Maven properties are normally set in the default
profile, which ensures that the same settings are used throughout the entire fabric (recommended).
default
profile using the fabric:profile-display
command, as follows:
JBossFuse:karaf@root> profile-display default ... Agent Properties : ... org.ops4j.pax.url.mvn.globalUpdatePolicy = always org.ops4j.pax.url.mvn.defaultRepositories = file:${runtime.home}/${karaf.default.repository}@snapshots@id=karaf-default, file:${runtime.data}/maven/upload@snapshots@id=fabric-upload org.ops4j.pax.url.mvn.repositories = file:${runtime.home}/${karaf.default.repository}@snapshots@id=karaf-default, file:${runtime.data}/maven/upload@snapshots@id=fabric-upload, http://repo1.maven.org/maven2@id=central, https://repo.fusesource.com/nexus/content/groups/public@id=fusepublic, https://repository.jboss.org/nexus/content/repositories/public@id=jbosspublic, https://repo.fusesource.com/nexus/content/repositories/releases@id=jbossreleases, https://repo.fusesource.com/nexus/content/groups/ea@id=jbossearlyaccess, http://repository.springsource.com/maven/bundles/release@id=ebrreleases, http://repository.springsource.com/maven/bundles/external@id=ebrexternal ...
org.ops4j.pax.url.mvn.*
are the Maven properties used by the Fabric8 agent.
org.ops4j.pax.url.mvn.*
properties are not related to the Pax URL Aether component. There is some potential for confusion here, because the Fabric8 agent uses the same property names as Pax URL Aether. These properties are read by the Fabric8 agent, however, not by Pax URL Aether (and are associated with the io.fabric8.agent
PID, not the org.ops4j.pax.url.mvn
PID).
14.3. How a Maven Proxy Resolves Artifacts
Overview
Fabric8 Maven proxy server
Host
, the Maven proxy can be accessed through the following URL:
http://Host:8181/maven/download
io.fabric8.maven.proxy
PID. By default, some of these properties are set in the default
profile and some are set in the fabric
profile.
io.fabric8.maven bundle layer
io.fabric8.maven
bundle layer offers similar functionality to the Pax URL Aether component (from a standalone Karaf container).
io.fabric8.maven
bundle is configured by setting properties from the io.fabric8.maven
PID and these properties are normally set in the default
profile (recommended).
Serving artifacts through the Maven proxy
Figure 14.3. Maven Proxy Serving an Artifact
Steps to serve artifacts
- Resolution of a Maven artifact is triggered when a managed container sends a request to the Maven proxy server.
- The Maven proxy server parses the incoming HTTP request and then makes a call to the
io.fabric8.maven
layer, asking it to resolve the requested Maven artifact. - The
io.fabric8.maven
layer reads its Maven configuration from theio.fabric8.maven
PID in thedefault
profile (and possibly also from a Mavensettings.xml
file, if so configured). - When the Aether library is invoked, the first step is to look up any local Maven repositories to try and find the Maven artifact. The following local repositories are configured by default:
InstallDir/system
- The JBoss A-MQ system directory, which contains all of the Maven artifacts that are bundled with the JBoss A-MQ distribution.
InstallDir/data/maven/upload
- The Maven proxy's upload directory, which is used to store artifacts that have been directly uploaded to the Maven proxy—see Section 14.6, “Automated Deployment”.
UserHome/.m2/repository
- The user's own local Maven repository in the user's home directory,
UserHome
.
If the Maven artifact is found locally, skip straight to step 7. - Aether next tries to look up the specified remote repositories. Because the remote repositories are located on the Internet (accessed through the HTTP protocol), it is necessary to have Internet access in order for this step to succeed.NoteIf your local network requires you to use a HTTP proxy to access the Internet, it is possible to configure Fabric8 to use a HTTP proxy. For example, see the section called “Configuring a HTTP proxy” for details.
- If the Maven artifact is found in a remote repository, Aether automatically installs the artifact into the local Maven repository,
UserHome/.m2/repository
, so that another remote lookup will not be required. - The Maven proxy server returns the successfully located Maven artifact to the client (or an error message, if the artifact could not be found).
14.4. Configuring Maven Proxies Directly
Overview
io.fabric8.agent
PID and the io.fabric8.maven
PID. Because these properties are set in a profile, they are immediately available to all containers in a fabric.
org.ops4j.pax.url.mvn.repositories
property in the io.fabric8.agent
PID. If this property is not set, the Fabric8 agent falls back to reading configuration from the Maven settings.xml
file.
settings.xml
file. See Section 14.5, “Configuring Maven Proxies and HTTP Proxies through settings.xml”.
Tools for editing configuration
fabric:profile-edit
). It is worth recalling, however, that there are several different tools you can use to modify the settings in a fabric:
- Karaf console—use the
fabric:*
family of commands (for example,fabric:profile-edit
). - Fuse Management Console (Hawtio)—you can edit profile settings through the Profile tab or the Wiki tab in the Fabric perspective of the Hawtio console, http://localhost:8181/hawtio/login.
- Git configuration—you can edit profile settings by cloning the Git profile repository. See Chapter 16, Configuring with Git for details.
Rolling out configuration changes
default
profile, as follows:
profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default
1.0
):
version-create 1.1 profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default 1.1
1.1
, using the following command:
container-upgrade 1.1 mycontainer
Adding a remote Maven repository
org.ops4j.pax.url.mvn.repositories
property of the io.fabric8.agent
PID in the default
profile (not forgetting to specify the mandatory @id
suffix in the repository URL).
http://foo/bar
Maven repository to the list of remote repositories, enter the following console command:
profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories='http://foo/bar@id=myfoo' --append default
- The preceding setting simultaneously updates the
io.fabric8.maven/io.fabric8.maven.repositories
property (which, by default, is configured to copy the contents of theio.fabric8.agent/org.ops4j.pax.url.mvn.repositories
property). This is the property that actually configures the Maven proxy. - By editing this property in the
default
profile (which is normally the base profile of every profile), you ensure that this setting is propagated to all containers and to all Maven proxies in the Fabric. - The preceding command immediately changes the configuration of all containers at the current version. If you prefer to implement a phased rollout of the new configuration, use profile versions, as described in Section 6.3, “Profile Versions”.
@id
option specifies the name of the repository and is required. You can choose an arbitrary value for this ID.
14.5. Configuring Maven Proxies and HTTP Proxies through settings.xml
Overview
settings.xml
file. For example, this approach is particularly convenient in a development environment, because it makes it possible to store your build time settings and your run time settings in one place.
Enabling the settings.xml configuration approach
settings.xml
file, perform the following steps:
- Delete the
org.ops4j.pax.url.mvn.repositories
property setting from theio.fabric8.agent
PID in thedefault
profile, using the following console command:profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default
When the repositories setting is absent, Fabric implicitly switches to thesettings.xml
configuration approach.NoteThis step simultaneously clears both the repositories list used by the Fabric8 agent and the repositories list used by the Maven proxy server (because the Maven proxy's repository list is normally copied straight from the Fabric8 agent's repository list). - Set the
io.fabric8.maven.settings
property from theio.fabric8.maven
PID in thedefault
profile to the location of the Mavensettings.xml
file. For example, if yoursettings.xml
file is stored in the location,/home/fuse/settings.xml
, you would set theio.fabric8.maven.settings
property as follows:profile-edit --pid io.fabric8.maven/io.fabric8.maven.settings='/home/fuse/settings.xml' default
NoteThe effect of this setting is to configure the Maven proxy server to takes its Maven configuration from the specifiedsettings.xml
file. The Fabric8 agent is not affected by this setting. - In order to configure the Fabric8 agent with the Maven
settings.xml
, set theorg.ops4j.pax.url.mvn.settings
property from theio.fabric8.agent
PID in thedefault
profile to the location of the Mavensettings.xml
file. For example, if yoursettings.xml
file is stored in the location,/home/fuse/settings.xml
, you would set theorg.ops4j.pax.url.mvn.settings
property as follows:profile-edit --pid io.fabric8.agent/org.ops4j.pax.url.mvn.settings='/home/fuse/settings.xml' default
ImportantIf you configure a HTTP proxy in yoursettings.xml
file, it is essential to configure the ensemble hosts (where the Maven proxies are running) as HTTP non-proxy hosts. Otherwise, the Fabric8 agent tries to connect to the local Maven proxy through the HTTP proxy (which is an error).
Adding a remote Maven repository
settings.xml
file, open the settings.xml
file in a text editor and add a new repository
XML element. For example, to create an entry for the JBoss A-MQ public Maven repository, add a repository
element as shown:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <profiles> <profile> <id>my-fuse-profile</id> <activation> <activeByDefault>true</activeByDefault> </activation> <repositories> <!-- | Add new remote Maven repositories here --> <repository> <id>jboss-fuse-public-repository</id> <url>https://repo.fusesource.com/nexus/content/groups/public/</url> <releases> <enabled>true</enabled> </releases> <snapshots> <enabled>false</enabled> </snapshots> </repository> ... </repositories> </profiles> ... </settings>
Configuring a HTTP proxy
settings.xml
file in a text editor and add a new proxy
XML element as a child of the proxies
XML element. The definition of the proxy follows the standard Maven syntax. For example, to create a proxy for the HTTP (insecure) protocol with host, 192.0.2.0
, and port, 8080
, add a proxy
element as follows:
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd"> ... <proxies> <proxy> <id>fuse-proxy-1</id> <active>true</active> <protocol>http</protocol> <host>192.0.2.0</host> <port>8080</port> <nonProxyHosts>ensemble1|ensemble2|ensemble3</nonProxyHosts> </proxy> </proxies> ... </settings>
nonProxyHosts
element. This ensures that the Fabric8 agents do not attempt to connect to the Maven proxies through the HTTP proxy, but make a direct connection instead. In the preceding example, the ensemble host names are ensemble1
, ensemble2
, and ensemble3
.
proxy
element configured with the https
protocol.
Alternative approaches to configuring a HTTP proxy
settings.xml
file. For example, you could take the approach of setting the http.proxyHost
and http.proxyPort
system properties in the InstallDir/etc/system.properties
file (just like the approach for a standalone, non-Fabric container):
http.proxyHost=192.0.2.0 http.proxyPort=8080
http.nonProxyHosts=ensemblehost1|ensemblehost2|ensemblehost3
Reference
settings.xml
file, see the Maven Settings Reference. But please note that not all of the features documented there are necessarily supported by Fabric.
14.6. Automated Deployment
Overview
Discover the upload URL of the current master
fabric:cluster-list
command, as follows:
JBossFuse:karaf@root> cluster-list servlets/io.fabric8.fabric-maven-proxy [cluster] [masters] [slaves] [services] [] 1.2.0.redhat-621084/maven/download root root - http://127.0.0.1:8181/maven/download 1.2.0.redhat-621084/maven/upload root root - http://127.0.0.1:8181/maven/upload
http://127.0.0.1:8181/maven/upload
.
Manually deploy a Maven project
mvn deploy
with the altDeploymentRepository
command-line option. The value of altDeploymentRepository
is specified in the following format:
ID::Layout::RepositoryURL
ID
- Can be used to pick up the relevant credentials from the
settings.xml
file (from the matchingsettings/servers/server/id element
). Otherwise, the credentials must be specified in the repository URL. If necessary, you can simply specify a dummy value for the ID. Layout
- Can be either
default
(for Maven3 or Maven2) orlegacy
(for Maven1, which is not compatible with JBoss A-MQ). RepositoryURL
- The Maven proxy upload URL. For example,
http://User:Password@localhost:8181/maven/upload/
.
127.0.0.1
), authenticating with the admin/admin credentials, enter a command like the following:
mvn deploy -DaltDeploymentRepository=releaseRepository::default::http://admin:admin@127.0.0.1:8181/maven/upload/
Automatically deploy a Maven project
14.7. Fabric Maven Configuration Reference
Overview
io.fabric8.agent
PID, the io.fabric8.maven
PID, and the io.fabric8.maven.proxy
PID.
Repository URL syntax
file:
, http:
, or https:
scheme, optionally appending one or more of the following suffixes:
@snapshots
- Allow snapshot versions to be read from the repository.
@noreleases
- Do not allow release versions to be read from the repository.
@id=RepoName
- (Required) Specifies the repository name. This setting is required by the Aether handler.
@multi
- Marks the path as a parent directory of multiple repository directories. At run time the parent directory is scanned for subdirectories and each subdirectory is used as a remote repository.
@update=UpdatePolicy
- Specifies the Maven
updatePolicy
, overriding the value oforg.ops4j.pax.url.mvn.globalUpdatePolicy
. @releasesUpdate=UpdatePolicy
- Specifies the Maven
updatePolicy
specifically for release artifacts (overriding the value of@update
). @snapshotsUpdate=UpdatePolicy
- Specifies the Maven
updatePolicy
specifically for snapshot artifacts (overriding the value of@update
). @checksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
, which specifies how to react if a downloaded Maven artifact has a missing or incorrect checksum. The policy value can be:ignore
,fail
, orwarn
. @releasesChecksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
specifically for release artifacts (overriding the value of@checksum
). @snapshotsChecksum=ChecksumPolicy
- Specifies the Maven
checksumPolicy
specifically for snapshot artifacts (overriding the value of@checksum
).
https://repo.example.org/maven/repository@id=example.repo
io.fabric8.agent PID
io.fabric8.agent
PID configures the Fabric8 agent. The io.fabric8.agent
PID supports the following properties relating specifically to Maven configuration:
org.ops4j.pax.url.mvn.defaultRepositories
- Specifies a list of default (local) Maven repositories that are checked before looking up the remote repositories. Specified as a comma-separated list of
file:
repository URLs, where each repository URL has the syntax defined in the section called “Repository URL syntax”. org.ops4j.pax.url.mvn.globalUpdatePolicy
- Specifies the Maven
updatePolicy
, which determines how often Aether attempts to update local Maven artifacts from remote repositories. Can take the following values:always
—always resolve the latest SNAPSHOT from remote Maven repositories.never
—never check for newer remote SNAPSHOTS.daily
—check on the first run of the day (local time).interval:Mins
—check everyMins
minutes.
Thedefault
profile sets this property toalways
. If not set, default isdaily
. org.ops4j.pax.url.mvn.repositories
- Specifies a list of remote Maven repositories that can be searched for Maven artifacts. This property can be used in any of the following ways:
- Use this property and disable
settings.xml
Normally, theorg.ops4j.pax.url.mvn.repositories
property is set as a comma-separated list of repository URLs, where the \ character can be used for line continuation. In this case, any Mavensettings.xml
file is ignored (that is, theorg.ops4j.pax.url.mvn.settings
property setting is ignored). For example, this property is set as follows in thedefault
profile:org.ops4j.pax.url.mvn.repositories= file:${runtime.home}/${karaf.default.repository}@snapshots@id=karaf-default, \ file:${runtime.data}/maven/upload@snapshots@id=fabric-upload, \ http://repo1.maven.org/maven2@id=central, \ https://repo.fusesource.com/nexus/content/groups/public@id=fusepublic, \ https://repository.jboss.org/nexus/content/repositories/public@id=jbosspublic, \ https://repo.fusesource.com/nexus/content/repositories/releases@id=jbossreleases, \ https://repo.fusesource.com/nexus/content/groups/ea@id=jbossearlyaccess, \ http://repository.springsource.com/maven/bundles/release@id=ebrreleases, \ http://repository.springsource.com/maven/bundles/external@id=ebrexternal
- Use
settings.xml
and disable this propertyIf you want to use a Mavensettings.xml
file to configure the list of remote repositories instead of this property, you must remove theorg.ops4j.pax.url.mvn.repositories
property settings from the profile. For example, assuming that this property is set in the default profile, you can delete it with the following command:profile-edit --delete --pid io.fabric8.agent/org.ops4j.pax.url.mvn.repositories default
- Use both this property and
settings.xml
You can combine the remote repositories specified in this setting and the remote repositories configured in asettings.xml
file by using a special syntax for the list of repository URLs. In this case, you must specify a space-separated list of repository URLs, where each repository URL is prefixed by the+
character, and the repository URLs are listed on a single line (the\
line continuation character is not supported in this syntax). For example:org.ops4j.pax.url.mvn.repositories = +file://${runtime.data}/maven/upload@snapshots@id=fabric-upload +file://${runtime.home}/${karaf.default.repository}@snapshots@id=karaf-default
org.ops4j.pax.url.mvn.settings
- Specifies a path on the file system to override the default location of the Maven
settings.xml
file. The Fabric8 agent resolves the location of the Mavensettings.xml
file in the following order:- The location specified by
org.ops4j.pax.url.mvn.settings
. ${user.home}/.m2/settings.xml
${maven.home}/conf/settings.xml
M2_HOME/conf/settings.xml
NoteAllsettings.xml
files are ignored, if theorg.ops4j.pax.url.mvn.repositories
property is set.
io.fabric8.maven PID
io.fabric8.maven
PID configures the io.fabric8.maven
bundle (which is used by the Maven proxy server) and supports the following properties:
io.fabric8.maven.proxies
- This option is obsolete and no longer works. In older Fabric8 releases it was used to configure a HTTP proxy port.
io.fabric8.maven.repositories
- Specifies a list of remote Maven repositories that can be searched for Maven artifacts. This setting is normally copied from
org.ops4j.pax.url.mvn.repositories
. io.fabric8.maven.useFallbackRepositories
- This option is deprecated and should always be set to
false
.Thedefault
profile sets this property tofalse
.
io.fabric8.maven.proxy PID
io.fabric8.maven.proxy
PID configures the Fabric8 Maven proxy server and supports the following properties:
appendSystemRepos
- The
fabric
profile sets this property tofalse
. role
- Specifies a comma-separated list of security roles that are allowed to access the Maven proxy server. For details of role-based access control, see section "Role-Based Access Control" in "Security Guide".The
default
profile sets this property to the following list:admin,manager,viewer,Monitor,Operator,Maintainer,Deployer,Auditor,Administrator,SuperUser
updatePolicy
- Specifies the Maven
updatePolicy
.Thefabric
profile sets this property toalways
. uploadRepository
- Specifies the location of the directory used to store artifacts uploaded to the Maven proxy server.The
fabric
profile sets this property to${runtime.data}/maven/upload
.
Chapter 15. Offline Repositories
Abstract
15.1. Offline Repository for a Profile
Download into a specified directory
ProfileName
, enter the following console command:
fabric:profile-download --profile ProfileName /tmp/myrepo
/tmp/myrepo
directory.
Download into the system folder
fabric:profile-download
command installs the files to the system
folder inside the current Fuse container (thereby populating the local maven repository for the container). For example:
fabric:profile-download --profile ProfileName
15.2. Offline Repository for a Version
Download the current version
fabric:profile-download /tmp/myrepo
Download a specific version
--version
option, as follows:
fabric:profile-download --version 1.0 /tmp/myrepo
fabric:profile-download
command installs the files into thesystem
folder inside the current Fuse container (thereby populating the local maven repository for the container).
15.3. Offline Repository for a Maven Project
Download repository for Maven project
pom.xml
file), you should be able to run the following Maven command:
mvn org.apache.maven.plugins:maven-dependency-plugin:2.8:go-offline -Dmaven.repo.local=/tmp/cheese
/tmp/cheese
directory.
Chapter 16. Configuring with Git
Abstract
16.1. How Git Works inside Fabric
Cluster architecture
- Each Fabric server has its own clone of the Git configuration.
- One Fabric server is elected to be the master instance, and serves as the master remote repository for the other Fabric servers.
- All configuration changes made in the other Fabric servers (the slave instances) are pushed to the master instance.
- When changes occur in the master, the slaves automatically pull the new configuration from the master.
- If the master instance is stopped, another container is elected to be the master (failover).
- An administrator can access the Git configuration layer by cloning a local Git repository from the master instance. By pushing updates from this local repository, the administrator can change the configuration of the fabric.
External Git repository architecture
- The external Git repository is created in an external Git server (for example, using a service such as GitLab or Gerrit).
- When the Fabric is created, it automatically populates the external Git repository with the default configuration (which is initialized by reading the
InstallDir/fabric/import
directory). - Each Fabric server maintains a synchronized state with the external Git repository.
- All configuration changes made in the Fabric servers are pushed to the external Git repository.
- When changes occur in the external Git repository, the Fabric servers automatically pull the new configuration from the external Git repository.
- An administrator can access the Git configuration layer by cloning a local Git repository from the external Git repository. By pushing updates from this local repository to the external Git repository, the administrator can change the configuration of the fabric.
What is stored in the Git repositories?
Git branches
JBossA-MQ:karaf@root> fabric:version-create Created version: 1.1 as copy of: 1.0
1.1
. In fact, most of the Fabric version commands are approximately equivalent to a corresponding git
command, as shown in the following table:
Fabric Version Command | Analogous Git Command |
---|---|
fabric:version-create NewBranch
|
git branch NewBranch
|
fabric:version-list
|
git branch
|
fabric:version-set-default Branch
|
git checkout Branch
|
fabric:version-delete Branch
|
git branch -d Branch
|
Configuring through the console commands
fabric:profile-create
, new files are added to the Git repository, and the changes are committed. Similarly, when you edit a profile using the fabric:profile-edit
command, these changes are added and committed to the underlying Git repository.
Prerequisites
git
binaries to be installed on your system, because it is implemented using the JGit library. You will need to install Git binaries on your local system, however, if you want to configure Fabric directly through Git, using a clone of the Git repository.
Configuring directly through Git
16.2. Using a Git Cluster
Overview
Figure 16.1. Git Cluster Architecture
Clone the Git repository
$ git clone -b 1.0 http://Hostname:Port/git/fabric
Hostname
and Port
are the hostname and IP port of the master Fabric server. Note the following points:
- The port number,
Port
, is usually8181
, by default. But if you deploy multiple Fabric containers on the same host, their HTTP ports are automatically incremented, 8182, 8183, (or whichever is the next available port number at the time the container is created). - The
-b
option is used to check out the1.0
Git branch, which corresponds to version 1.0 of the Fabric profile data. There is also amaster
branch, but it is normally not used by the Fabric servers. - You can also see a sample clone command in the Fuse Management Console, if you navigate to the Container: page for the relevant container, click on the URLs tag, and go to the Git: field. Note, however, that if you try to clone from a slave instance, you will get an error (the Fuse Management Console currently does not indicate whether the container is a slave or a master).
InstallDir/data/git/local/fabric
directory (which holds the container's local Git repository). This approach does not work. When you push and pull to the container's HTTP port, it automatically triggers synchronization events within the Git cluster. These necessary synchronizations would be bypassed, if you cloned from a directory.
Authentication
- Let Git prompt you for credentials—this is the default, if you use a Git URL of the form,
http://Hostname:Port/git/fabric
. - Embed credentials in the Git URL—you can embed the credentials directly in the Git URL, using the following syntax:
http://User:Pass@Hostname:Port/git/fabric
Basic tasks with Git
- Push to the Fabric Git server—you can use your local Git repository to edit profile configurations and push the changes up to the fabric. For example, to edit the Camel route in the
example-camel-twitter
profile:- Make sure that you are working in the correct branch (initially, this should be branch
1.0
):$ cd LocalGitRepo $ git checkout 1.0
- Edit the following Blueprint XML file in your local Git repository, to alter the Camel route:
LocalGitRepo/fabric/profiles/example/camel/twitter.profile/camel.xml
- Add and commit the changes locally, using Git commands:
$ git add -u $ git commit -m "Changed the route in example-camel-twitter"
- Push the changes to the fabric:
$ git push
This updates the configuration in all of the Fabric servers in the Git cluster. If any of the containers in your fabric have deployed theexample-camel-twitter
profile, they will immediately be updated with the changes.
- Pull from the Fabric Git server—if you change the profile configuration using commands in the Karaf console, you can synchronize those changes with your local Git repository by doing a
git pull
. For example, to edit the Camel route in theexample-camel-twitter
profile from the Karaf console:- In the Karaf console, you can edit the Camel route from the
example-camel-twitter
profile by entering the following console command:fabric:profile-edit --resource camel.xml example-camel-twitter
- You can now synchronize your local Git repository to these changes. Open a command prompt, and enter the following commands:
$ cd LocalGitRepo $ git checkout 1.0
- Pull the changes from the fabric:
$ git pull
What happens after a failover?
origin
upstream repository. But what happens if there is a failover? For example, if the Fabric server that is the master instance is stopped and restarted. If your ensemble consists of only one Fabric server, this makes no difference, because there is no other server to fail over to. But if there are three (or five) servers in your ensemble, one of the other Fabric servers will automatically be elected as the new master.
git push
or a git pull
after failover, you will get the following error:
$ git pull fatal: repository 'http://Hostname:8181/git/fabric/' not found
Adding multiple upstream repositories
$ git remote add ensemble2 Ensemble2GitURL $ git remote add ensemble3 Ensemble2GitURL
$ git push UpstreamName BranchName
1.0
of the ensemble2
Git server:
$ git push ensemble2 1.0
origin
, ensemble2
, ensemble3
, is accessible at one time, however (whichever is the master).
Git cluster tutorial
- (Optional) Prepare the container for a cold start. Delete the following directories:
InstallDir/data InstallDir/instances
WarningPerforming a cold start completely wipes the current state of the root container, including all of the deployed bundles, and features, and most of the stored data. Do not perform this operation on a production system. - Start up the container, by entering the following command:
./bin/amq
- Create a new fabric. At the container prompt, enter the following console command:
fabric:create --new-user admin --new-user-password AdminPass --new-user-role Administrator \ --zookeeper-password ZooPass --global-resolver manualip \ --resolver manualip --manual-ip 127.0.0.1 --wait-for-provisioning
You need to substitute your own values forAdminPass
andZooPass
. This sample command uses the--manual-ip
option to assign the loopback address,127.0.0.1
, to the root container. If your host has a static IP address and hostname assigned to it, however, it would be better to use the assigned hostname here instead.You need to wait a minute or two for this command to complete. - Create two new child containers in the fabric, by entering the following console command:
fabric:container-create-child --profile fabric root ensemble 2
This command returns quickly, with the following message:The following containers have been created successfully: Container: ensemble. Container: ensemble2.
But it takes a couple of more minutes for the new child containers to be completely provisioned. Check the status of the child containers, by entering the following command:fabric:container-list
Wait until the child containers have a[provision status]
ofsuccess
before proceeding. - Add the two child containers to the Fabric ensemble, so that the Fabric ensemble consists of three containers in all:
root
,ensemble
, andensemble2
. Enter the following console command:fabric:ensemble-add ensemble ensemble2
Wait until the ensemble containers have been successfully provisioned before proceeding. - Clone the Git repository. The three containers in the Fabric ensemble now constitute a Git cluster. Initially, the
root
container is the master instance of the cluster, so you should attempt to clone the Git repository from the HTTP port exposed by theroot
container.Open a new command prompt and, at a convenient location in the file system, enter the following command:git clone -b 1.0 http://127.0.0.1:8181/git/fabric
This command clones the Fabric Git repository and checks out the1.0
branch. You should now be able to see the profile configuration files under thefabric/profiles
subdirectory.If theroot
container is not the current master, you can expect to see an error message like the following when you attempt to clone:Cloning into 'fabric'... fatal: repository 'http://127.0.0.1:8181/git/fabric/' not found
- In the next few steps, we explore the failover behaviour of the Git cluster. First of all, we stop the
root
container (the current Git master), in order to force a failover. In the root container console, enter theshutdown
command, as follows:JBossA-MQ:karaf@root> shutdown Confirm: shutdown instance root (yes/no): yes
- Now restart the root container, by entering the following command:
./bin/amq
- Return to the command prompt where you cloned the Git repository and try to do a
git pull
, as follows:cd fabric git pull
You will get an error like the following:$ git pull fatal: repository 'http://127.0.0.1:8181/git/fabric/' not found
Because the root container (listening on IP port 8181) is no longer the master.NoteIn this example, because all of the ensemble containers are running on the same host, the ensemble containers are distinguished by having different IP port numbers (8181, 8182, and 8183). If you created the other ensemble containers on separate hosts, however, they would all have the same port number (8181), but different host names. - One of the other Fabric servers (
ensemble
orensemble2
) is now the master. To gain access to the master, try adding both of the alternative Git URLs as upstream repositories. From a directory in the cloned Git repository, enter the following commands:$ git remote add ensemble http://127.0.0.1:8182/git/fabric $ git remote add ensemble2 http://127.0.0.1:8183/git/fabric
- You can now try pulling from one of the other Fabric servers. You can either pull from the
ensemble
container (pulling branch1.0
), as follows:$ git pull ensemble 1.0
Or from theensemble2
container (pulling branch1.0
), as follows:$ git pull ensemble2 1.0
Only one of these alternatives can succeed (pulling from the master). Pulling from the slave instance returns an error. - After you have identified the current master, you can proceed to push and pull using the long form of the
git
commands (for example,git pull RemoteName BranchName
).
16.3. Using an External Git Repository
Overview
Figure 16.2. External Git Repository Architecture
External git repository architecture
data/
directories), but this local copy is kept up-to-date by regularly polling the external Git repository for updates. If a change is detected in the external Git repository, every Fabric server will do a git pull
to update it's local copy of the Git repository.
git
commands, the administrator can now edit the configuration files in the local copy and push the changes to the external Git repository. As soon as those changes are received by the external Git repository, the Fabric servers will detect that an update has occurred and pull the latest configuration.
Preparing an external Git repository
- The Git repository must be initialized. For example, if you were creating a new Git repository on your local file system, you would initialize it using the command
git init
. If you are using a Git server to host your repository (for example, Gerrit, GitLab, or GitHub), the Git repository is usually initialized automatically, after you create it. - You must ensure that all of your Fabric servers are able to access the external Git repository. For example, if your Git server uses a HTTP based protocol to access the repository, you are generally required to have username/password credentials for the HTTP BASIC authentication protocol.
Authentication
- HTTP URL—in this case, the Git server is likely to use HTTP with TLS (HTTPS), to verify the server identity, and HTTP BASIC authentication, to verify the client identity. When creating the fabric (with the
fabric:create
command), you need to specify the following additional options in this case:--external-git-url ExternalGitHttpUrl
--external-git-user ExternalGitUser
--external-git-password ExternalGitPass
- File URL—in this case, no authentication is required. You can specify the Git URL either in the form
/path/to/repo
(recommended) orfile:///path/to/repo
(slower). If the Fabric servers are deployed on separate hosts, you must make sure that they all have access to the specified directory (for example, through a Network File Server). When creating the fabric (with thefabric:create
command), you need to specify the following additional options in this case:--external-git-url ExternalGitFileUrl
Creating a fabric with an external Git repository
fabric:create --new-user admin --new-user-password AdminPass --new-user-role Administrator \ --zookeeper-password ZooPass --global-resolver manualip \ --resolver manualip --manual-ip StaticIPAddress --wait-for-provisioning \ --external-git-url ExternalGitHttpUrl \ --external-git-user ExternalGitUser --external-git-password ExternalGitPass
- A new user is created with username,
admin
, password,AdminPass
, and role,Administrator
. You can use these JAAS credentials to log on to any of the containers in the fabric. - The Zookeeper password is set to
ZooPass
(the only time you are prompted to enter the Zookeeper password is when joining a container to the fabric). - The resolver policy for the root container is set to
manualip
(using the--resolver
option) and the global resolver policy (which becomes the default resolver policy for containers created in this fabric) is also set tomanualip
. This enables you to specify the root container's IP address,StaticIPAddress
, explicitly. It is essential that you assign a static IP address to the Fabric server host (for demonstrations and tests on a single machine, you can use the loopback address,127.0.0.1
). - The Git URL,
ExternalGitHttpUrl
, is specified through the--external-git-url
option. - Assuming that you use a HTTP Git URL with BASIC authentication enabled, you will also need to specify credentials, using the
--external-git-user
and--external-git-password
options.
What happens if the external Git repository fails?
External Git repository tutorial
- Create a new (empty) Git repository, which you can use as the external Git repository. Typically, you would create the Git repository in a hosting service, such as GitLab, Gerrit, or GitHub. Make a note of the new repository's HTTP URL,
ExternalGitHttpUrl
, and make sure that it is possible to access the external Git repository from the hosts where you will be deploying your Fabric servers. - (Optional) Prepare the container for a cold start. Delete the following directories:
InstallDir/data InstallDir/instances
WarningPerforming a cold start completely wipes the current state of the root container, including all of the deployed bundles, and features, and most of the stored data. Do not perform this operation on a production system. - Start up the container, by entering the following command:
./bin/amq
- Create a new fabric. At the container prompt, enter the following console command:
fabric:create --new-user admin --new-user-password AdminPass --new-user-role Administrator \ --zookeeper-password ZooPass --global-resolver manualip \ --resolver manualip --manual-ip 127.0.0.1 --wait-for-provisioning \ --external-git-url ExternalGitHttpUrl \ --external-git-user ExternalGitUser --external-git-password ExternalGitPass
You need to substitute your own values forAdminPass
andZooPass
. TheExternalGitHttpUrl
is the HTTP URL of the external Git repository you created earlier and theExternalGitUser
value and theExternalGitPass
value are the username/password credentials required to access the external Git repository (using HTTP BASIC authentication).This sample command uses the--manual-ip
option to assign the loopback address,127.0.0.1
, to the root container. If your host has a static IP address and hostname assigned to it, however, it would be better to use the assigned hostname here instead.You need to wait a minute or two for this command to complete. - After your fabric has been created, navigate to the contents of the external Git repository in your browser (assuming that your Git server supports this functionality). The external repository should now be populated with the default configuration of your fabric, with two branches available:
master
and1.0
. The1.0
branch is the branch that is initially used by your fabric. - Create a local clone of the external Git repository, which you can then use to push or pull profile configurations. Open a new command prompt and, in a convenient location on the file system, enter the following command:
git clone -b 1.0
ExternalGitHttpUrl
Thisgit
command will prompt you to enter the username and password credentials for the external Git repository.This command clones the Fabric Git repository and checks out the1.0
branch. You should now be able to see the profile configuration files under thefabric/profiles
subdirectory. - You can now use regular
git
commands to configure your Fabric profiles. Simply edit the files in your local Git repository, add the changes, commit, and then push the changes to the external Git repository (working in the1.0
branch). Shortly after the changes are pushed to the external Git repository, the containers in your Fabric ensemble (the Fabric servers) will poll the repository, pull the changes, and redeploy any changed profiles..
16.4. Using an HTTP Proxy with a Git Cluster
- Start up JBoss Fuse, and create a fabric. For details, see the section called “Steps to create the fabric”.
- At the
JBossFuse:karaf@root>
command line, type:profile-edit --pid io.fabric8.git.proxy/proxyHost=serverName default profile-edit --pid io.fabric8.git.proxy/proxyPort=portNumber default
These commands specify the hostname and port to use, and thedefault
profile is updated with the new configuration.For example:profile-edit --pid io.fabric8.git.proxy/proxyHost=10.8.50.60 default profile-edit --pid io.fabric8.git.proxy/proxyPort=3128 default
All changes made to the fabric configuration will now be redirected to the Git HTTP proxy on host10.8.50.60
's port3128
.
Chapter 17. Patching
17.1. Patching a Fabric Container with a Rollup Patch
Abstract
Overview
- Distribution of patched artifacts
- Profiles
- Configuration of the underlying container
Distribution of patch artifacts
- Through the Maven proxy (default approach)—when you add a rollup patch to your root container (using the
patch:add
command), the patch artifacts are installed into the root container'ssystem/
directory, whose directory structure is laid out like a Maven repository. The root container can then serve up these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to download the required Maven artifacts (this process is managed by the Fabric agent running on each Fabric container). Alternatively, if you have installed the rollup patch to a container that is not hosting the Maven proxy, you can ensure that the patch artifacts are uploaded to the Maven proxy by invoking thepatch:fabric-install
command with the--upload
option.The Maven proxy approach sufferes from a potential drawback, however. If the Fabric ensemble consists of multiple containers, it can happen that the Maven proxy fails over to a different ensemble container (not the original root container). This can result in the patch artifacts suddenly becoming unavailable to other containers in the fabric. If this occurs during the patching procedure, it will cause problems.For more details, see Chapter 14, Fabric Maven Proxies. - Through a local repository (recommended approach)—to overcome the limitations of the Maven proxy approach, we recommend that you make the patch artifacts available directly to all of the containers in the Fabric by setting up a local repository on the file system. Assuming that you have a networked file system, all containers will be able to access the patch artifacts directly.For example, you might set up a local repository of patch artifacts, as follows:
- Given a rollup patch file, extract the contents of the
system/
directory from the rollup patch file into therepositories/
subdirectory of a local Maven repository (which could be~/.m2/repositories
or any other location). - Configure the Fabric agent and the Maven proxy to pick up artifacts from the local repository by editing the current version of the
default
profile, as follows:profile-edit --append --pid io.fabric8.agent/org.ops4j.pax.url.mvn.defaultRepositories="file:///PathToRepository" default
ReplacePathToRepository
by the actual location of the local repository on your file system.NoteMake sure that you make the edits to thedefault
profile for all relevant profile versions. If some of your containers are using a non-default profile version, repeat theprofile-edit
commands while specifying the profile version explicitly as the last parameter.
Profiles
default
, fabric
, karaf
, and so on), the patching mechanism attempts to merge your changes with the changes introduced by the patch.
default
profile).
Configuration of the underlying container
etc/
, lib/
, and so on). When a Fabric container is upgraded to a patched version (for example, using the fabric:container-upgrade
command), the container's Fabric agent checks whether the underlying container must be patched. If yes, the Fabric agent triggers the patching mechanism to update the underlying container. Moreover, if certain critical files are updated (for example, lib/karaf.jar
), the container status changes to requires full restart
after the container is upgraded. This status indicates that a full manual restart is required (an automatic restart is not possible in this case).
io.fabric.version in the default profile
io.fabric.version
resource in the default
profile plays a key role in the patching mechanism. This resource defines the version and build of JBoss A-MQ and of all of its main components. When upgrading (or rolling back) a Fabric container to a new version, the Fabric agent checks the version and build of JBoss A-MQ as defined in the io.fabric.version
resource. If the JBoss A-MQ version changes between the original profile version and the upgraded profile version, the Fabric agent knows that an upgrade of the underlying container is required when upgrading to this profile version.
Patching the patch mechanism
- Download the appropriate patch management package. From the JBoss A-MQ 6.2.0 Software Downloads page, select a package named Red Hat JBoss A-MQ 6.2.1 Rollup N on Karaf Update Installer, where N is the number of the particular rollup patch you are about to install.ImportantThe rollup number, N, of the downloaded patch management package must match the rollup number of the rollup patch you are about to install.NoteThe 6.2.1 patch management packages are made available from the 6.2.0 Software Downloads page. This is because the 6.2.1 patch management packages can also be used when upgrading from version 6.2.0.
- Install the patch management package,
patch-management-for-amq-620-TargetVersion.zip
, on top of every Karaf container installation (root container, SSH containers, and so on). Use an archive utility to extract the contents on top of the existing container installation (installing files under thesystem/
andpatches/
subdirectories).NoteIt does not matter whether the container is running or not when you extract these files. - Start the root container, if it is not already running.
- Create a new version, using the
fabric:version-create
command (where we assume that the current profile version is1.0
):JBossFuse:karaf@root> fabric:version-create --parent 1.0 1.0.1 Created version: 1.0.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 [.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Update the
patch
property in theio.fabric8.version
PID in the version1.0.1
of thedefault
profile, by entering the following Karaf console command:profile-edit --pid io.fabric8.version/patch=1.2.0.redhat-621xxx default 1.0.1
Where you must replace1.2.0.redhat-621xxx
with the actual build version of the patch commands you are installing (for example, the build versionxxx
can be taken from the last three digits of theTargetVersion
in the downloaded patch management package file name). - Reconfigure the Fabric agent so that the version of the patch mechanism it uses is determined by the
patch
version property (set in the previous step). Enter the following console command:profile-edit --pid 'io.fabric8.agent/repository.fabric8-patch=mvn:io.fabric8.patch/patch-features/${version:patch}/xml/features' default 1.0.1
- Upgrade the root container to use the new patching mechanism, as follows:
container-upgrade 1.0.1 root
- Likewise, for all other containers in your fabric that need to be patched (SSH, child, and so on), provision them with the new patching mechanism by upgrading them to profile version
1.0.1
. For example:container-upgrade 1.0.1 container1 container2 container3
Applying a rollup patch
- Before applying the rollup patch to your fabric, you must patch the patch mechanism, as described in the section called “Patching the patch mechanism”.
- For every top-level container (that is, any container that is not a child container), perform these steps, one container at a time:
- In the Karaf installation, remove the
lib/endorsed/org.apache.karaf.exception-2.4.0.redhat-621xxx.jar
file (where the build number,xxx
, depends on the build being patched). - Restart the container.
- Add the patch to the root container's environment using the patch:add command. For example, to add the
patch.zip
patch file:JBossFuse:karaf@root> patch:add file://patch.zip [name] [installed] [description] PatchID false Description
ImportantIf you have decided to use a local repository to distribute the patch artifacts (recommended), set up the local repository now—see the section called “Distribution of patch artifacts”. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0.1
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 [.description]
. If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
patch:fabric-install
command. Note that in order to run this command you must provide the credentials,Username
andPassword
, of a user withAdministrator
privileges. For example, to apply thePatchID
patch to version1.1
:patch:fabric-install --username Username --password Password --upload --version 1.1 PatchID
NoteWhen you invoke thepatch:fabric-install
command with the--upload
option, Fabric looks up the ZooKeeper registry to discover the URL of the currently active Maven proxy, and uploads all of the patch artifacts to this URL. Using this approach it is possible to make the patch artifacts available through the Maven proxy, even if the container you are currently logged into is not hosting the Maven proxy. - Synchronize the patch information across the fabric, to ensure that the profile changes in version
1.1
are propagated to all containers in the fabric (particularly remote SSH containers). Enter the following console command:patch:fabric-synchronize
- Upgrade each existing container in the fabric using the
fabric:container-upgrade
command (but leaving the root container, where you installed the patch, until last). For example, to upgrade a container namedremote
, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 remote Upgraded container remote from version 1.0.1 to 1.1
At this point, not only does the Fabric agent download and install the patched bundles into the specified container, but the agent also applies the patch to the underlying container (updating any static files in the container, if necessary). If necessary, the agent will then restart the target container automatically or set the container status torequires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. - If the current status of the upgraded container is
requires full restart
, you must now use one of the standard mechanisms to stop and restart the container manually. In some cases, it will be possible to do this using Fabric commands from the console of the root container.For example, you could stop theremote
container as follows:fabric:container-stop remote
And restart theremote
container as follows:fabric:container-start remote
- Upgrade the root container last (that is, the container that you originally installed the patch on):
fabric:container-upgrade 1.1 root
- (Windows only) If the root container status has changed to
requires full restart
and it is running on a Windows operating system, you must first shut down all of the root container's child containers (if any) before manually restarting the root container.For example, if the root container has three child containers,child1
,child2
, andchild3
, you would first shut them down, as follows:fabric:container-stop child1 child2 child3
You can then shut down the root container with theshutdown
command:shutdown
Rolling back a rollup patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the remote
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 remote
requires full restart
(if an automatic restart is not possible), so that any changes made to the static files are applied to the running container.
17.2. Patching a Fabric Container with an Incremental Patch
Abstract
Overview
- Distribution of patched artifacts through Maven proxy
- Profiles
Distribution of patched artifacts through Maven proxy
system/
directory, whose directory structure is laid out like a Maven repository. The local container distributes these patch artifacts to remote containers by behaving as a Maven proxy, enabling remote containers to upload bundle JARs as needed (this process is managed by the Fabric agent running on each Fabric container). For more details, see Chapter 14, Fabric Maven Proxies.
Profiles
- The patch mechanism creates a new profile,
patch-PatchProfileID
, which defines bundle overrides for all of the patched bundles. - The new patch profile,
patch-PatchProfileID
, is inserted as the parent of thedefault
profile (at the base of the entire profile tree). - All of the profiles that inherit from default now use the bundle versions defined by the overrides in
patch-PatchProfileID
. The contents of the existing profiles themselves are not modified in any way.
Is it necessary to patch the underlying container?
fabric:create
command). Always read the patch README
file to find out whether there are any special steps required to install a particular patch. In these cases, however, it is more likely that the patch would be distributed in the form of a rollup patch, which has the capability to patch the underlying container automatically—see Section 17.1, “Patching a Fabric Container with a Rollup Patch”.
Applying an incremental patch
- Before you proceed to install the incremental patch, make sure to read the text of the
README
file that comes with the patch, as there might be additional manual steps required to install a particular incremental patch. - Create a new version, using the
fabric:version-create
command:JBossFuse:karaf@root> fabric:version-create 1.1 Created version: 1.1 as copy of: 1.0
ImportantVersion names are important! The tooling sorts version names based on the numeric version string, according to major.minor numbering, to determine the version on which to base a new one. You can safely add a text description to a version name as long as you append it to the end of the generated default name like this:1.3 <.description >
.If you abandon the default naming convention and use a textual name instead (for example, Patch051312), the next version you create will be based, not on the last version (Patch051312), but on the highest-numbered version determined by dot syntax. - Apply the patch to the new version, using the
fabric:patch-apply
command. For example, to apply theactivemq.zip
patch file to version1.1
:JBossFuse:karaf@root> fabric:patch-apply --version 1.1 file:///patches/activemq.zip
- Upgrade a container using the
fabric:container-upgrade
command, specifying which container you want to upgrade. For example, to upgrade thechild1
container, enter the following command:JBossFuse:karaf@root> fabric:container-upgrade 1.1 child1 Upgraded container child1 from version 1.0 to 1.1
ImportantIt is recommended that you upgrade only one or two containers to the patched profile version, to ensure that the patch does not introduce any new issues. Upgrade theroot
container (the one that you applied the patch to, using thefabric:patch-apply
command) last. - You can check that the new patch profile has been created using the
fabric:profile-list
command, as follows:BossFuse:karaf@root> fabric:profile-list --version 1.1 | grep patch default 0 patch-activemq-patch patch-activemq-patch
Where we presume that the patch was applied to profile version 1.1.TipIf you want to avoid specifying the profile version (with--version
) every time you invoke a profile command, you can change the default profile version using thefabric:version-set-default Version
command.You can also check whether specific JARs are included in the patch, for example:JBossFuse:karaf@root> list | grep -i activemq [ 131] [Active ] [Created ] [ ] [ 50] activemq-osgi (5.9.0.redhat-61037X) [ 139] [Active ] [Created ] [ ] [ 50] activemq-karaf (5.9.0.redhat-61037X) [ 207] [Active ] [ ] [ ] [ 60] activemq-camel (5.9.0.redhat-61037X)
Rolling back an incremental patch
fabric:container-rollback
command. For example, assuming that 1.0
is an unpatched profile version, you can roll the child1
container back to the unpatched version 1.0
as follows:
fabric:container-rollback 1.0 child1
Appendix A. Editing Profiles with the Built-In Text Editor
Abstract
profile-edit
command with no arguments except for the profile's name (and optionally, version); or adding the --pid
option for editing OSGi PID properties; or adding the --resource
option for editing general resources.
A.1. Editing Agent Properties
Overview
Open the agent properties resource
JBossFuse:karaf@root> profile-edit Profile [Version]
Profile
is the name of the profile to edit and you can optionally specify the profile version, Version, as well. The text editor opens in the console window, showing the current profile name and version in the top-left corner of the Window. The bottom row of the editor screen summarizes the available editing commands and you can use the arrow keys to move about the screen.
Specifying feature repository locations
repository.ID=URL
ID
is an arbitrary unique identifier and URL
gives the location of a single feature repository (only one repository URL can be specified on a line).
Specifying deployed features
feature.ID=FeatureName
ID
is an arbitrary unique identifier and FeatureName
is the name of a feature.
Specifying deployed bundles
bundle.ID=URL
ID
is an arbitrary unique identifier and URL
specifies the bundle's location.
blueprint:
(or spring:
) URL handler to deploy a Blueprint XML resource (or a Spring XML resource) as an OSGi bundle.
Specifying bundle overrides
override.ID=URL
ID
is an arbitrary unique identifier and URL
specifies the bundle's location.
Specifying etc/config.properties properties
etc/config.properties
in a standalone container), add a line in the following format:
config.Property=Value
Specifying etc/system.properties properties
etc/system.properties
in a standalone container), add a line in the following format:
system.Property=Value
Property
, is already set at the JVM level (for example, through the --jvm-opts
option to the fabric:container-create
command), the preceding fabric:profile-edit
command will not override the JVM level setting. To override a JVM level setting, set the system property as follows:
system.karaf.override.Property=Value
Specifying libraries to add to Java runtime lib/
lib/
directory of the underlying Java runtime), add a line in the following format:
lib.ID=URL
ID
is an arbitrary unique identifier and URL
specifies the library's location.
Specifying libraries to add to Java runtime lib/ext/
lib/ext/
directory of the underlying Java runtime), add a line in the following format:
ext.ID=URL
ID
is an arbitrary unique identifier and URL
specifies the extension library's location.
Specifying libraries to add to Java runtime lib/endorsed/
lib/endorsed/
directory of the underlying Java runtime), add a line in the following format:
endorsed.ID=URL
ID
is an arbitrary unique identifier and URL
specifies the endorsed library's location.
Example
mq-client
profile's agent properties for editing, enter the following console command:
JBossFuse:karaf@root> profile-edit mq-client
Profile:mq-client 1.0 L:1 C:1 # # Copyright (C) Red Hat, Inc. # http://redhat.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # repository.activemq=mvn:org.apache.activemq/activemq-karaf/${version:activemq}/xml/features repository.karaf-standard=mvn\:org.apache.karaf.assemblies.features/standard/${version:karaf}/ xml/features ^X Quit ^S Save ^Z Undo ^R Redo ^G Go To ^F Find ^N Next ^P Previous
^X
to quit the text editor and get back to the console prompt.
A.2. Editing OSGi Config Admin Properties
Overview
Persistent ID
PID
persistent ID are defined in the PID.properties
resource.
Open the Config Admin properties resource
PID
persistent ID, enter the following console command:
JBossFuse:karaf@root> profile-edit --pid PID Profile [Version]
--resource PID.properties
in the profile-edit
command, instead of using the --pid PID
option.
Specifying OSGi config admin properties
PID.properties
resource (which is actually stored in the ZooKeeper registry). To edit the properties, add, modify, or delete lines of the following form:
Property=Value
Example
io.fabric8.hadoop
PID in the hadoop-base
profile, enter the following console command:
JBossFuse:karaf@root> profile-edit --resource io.fabric8.hadoop.properties hadoop-base 1.0
Profile:hadoop-base 1.0 L:1 C:1 # # Copyright (C) Red Hat, Inc. # http://redhat.com # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at # # http://www.apache.org/licenses/LICENSE-2.0 # # Unless required by applicable law or agreed to in writing, software # distributed under the License is distributed on an "AS IS" BASIS, # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. # fs.default.name=hdfs\://localhost\:9000 dfs.replication=1 mapred.job.tracker=localhost\:9001 dfs.name.dir=${karaf.data}/hadoop/dfs/name dfs.http.address=0.0.0.0\:9002 dfs.data.dir=${karaf.data}/hadoop/dfs/data dfs.name.edits.dir=${karaf.data}/hadoop/dfs/name ^X Quit ^S Save ^Z Undo ^R Redo ^G Go To ^F Find ^N Next ^P Previous
\:
). Strictly speaking, it is only necessary to escape a colon if it appears as part of a property name (left hand side of the equals sign), but the profile-edit
command automatically escapes all colons when it writes to a resource. When manually editing resources using the text editor, however, you do not need to escape colons in URLs appearing on the right hand side of the equals sign.
^X
to quit the text editor and get back to the console prompt.
A.3. Editing Other Resources
Overview
Creating and editing an arbitrary resource
JBossFuse:karaf@root> profile-edit --resource Resource Profile [Version]
Resource
is the name of the profile resource you want to edit. If Resource
does not already exist, it will be created.
broker.xml example
mq-base
profile has the broker.xml
resource, which stores the contents of an Apache ActiveMQ broker configuration file. To edit the broker.xml
resource, enter the following console command:
JBossFuse:karaf@root> profile-edit --resource broker.xml mq-base 1.0
Profile:mq-base 1.0 L:1 C:1 <!-- Copyright (C) FuseSource, Inc. http://fusesource.com Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. --> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:amq="http://activemq.apache.org/schema/core" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://activemq.apache.org/schema/core http://activemq.apache.org/schema/core/activemq-core.xsd"> <!-- Allows us to use system properties and fabric as variables in this configuration file --> <bean class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer"> <property name="properties"> <bean class="io.fabric8.mq.fabric.ConfigurationProperties"/> </property> ^X Quit ^S Save ^Z Undo ^R Redo ^G Go To ^F Find ^N Next ^P Previous
^X
to quit the text editor and get back to the console prompt.
Referencing a profile resource
broker.xml
resource from the previous example is stored under the following ZooKeeper location:
zk:/fabric/configs/versions/1.0/profiles/mq-base/broker.xml
Version
, of the Profile
profile's Resource
resource at the following location:
zk:/fabric/configs/versions/Version/profiles/Profile/Resource
mq
profile's io.fabric8.mq.fabric.server-broker
PID defines the following properties, where the config
property references the broker.xml
resource:
connectors=openwire
config=zk\:/fabric/configs/versions/1.0/profiles/mq-base/broker.xml
group=default
standby.pool=default
A.4. Profile Attributes
Overview
parents attribute
parents
attribute is a list of one or more parent profiles. This attribute can be set using the profile-change-parents
console command. For example, to assign the parent profiles camel
and cxf
to the my-camel-cxf-profile
profile, you would enter the following console command:
JBossFuse:karaf@root> profile-change-parents --version 1.0 my-camel-cxf-profile camel cxf
abstract attribute
abstract
attribute is set to true
, the profile cannot be directly deployed to a container. This is useful for profiles that are only intended to be the parents of other profiles—for example, mq-base
. You can set the abstract attribute from the Management Console.
locked attribute
hidden attribute
hidden
attribute is a flag that is typically set on profiles that Fabric creates automatically (for example, to customize the setup of a registry server). By default, hidden profiles are not shown when you run the profile-list
command, but you can see them when you add the --hidden
flag, as follows:
JBossFuse:karaf@root> profile-list --hidden ... fabric 1 karaf fabric-ensemble-0000 0 fabric-ensemble-0000-1 1 fabric-ensemble-0000 fmc 0 default ...
Appendix B. Fabric URL Handlers
Abstract
B.1. Profile URL handler
profile:ResourceName
- The profile URL handler first tries to find the named resource,
ResourceName
, in the current version of the current profile (where the current version is a property of the container in which the profile is running). - If the specified resource is not found in the current profile, the profile URL tries to find the resource in the current version of the parent profile.
fabric:container-upgrade
or fabric:container-rollback
console commands), the referenced resources are also, automatically, upgraded or rolled back.
B.2. Zk URL handler
zk:/PathToNode
zk:ContainerName/Property
zk:/fabric/registry/containers/config/ContainerName/Property
B.3. Blueprint URL handler
blueprint:
scheme can be prefixed to any of the usual location URL handlers (for example, file:
, http:
, profile:
, zk:
).
bundle
entry in the agent properties (equivalent to the io.fabric8.agent
PID) in the following format:
bundle.ID=blueprint:LocationScheme:LocationOfBlueprintXML
camel.xml
resource (Blueprint file) from the current profile, you would add the following bundle
entry:
bundle.camel-fabric=blueprint:profile:camel.xml
B.4. Spring URL handler
spring:
scheme can be prefixed to any of the usual location URL handlers (for example, file:
, http:
, profile:
, zk:
).
bundle
entry in the agent properties (equivalent to the io.fabric8.agent
PID) in the following format:
bundle.ID=spring:LocationScheme:LocationOfBlueprintXML
camel-spring.xml
, from the current profile, you could add the following entry to the profile's agent properties:
bundle.spring-resource=spring:profile:camel-spring.xml
B.5. MVEL
profile
variable and runtime properties by using the runtime
variable.
mvel:profile:jetty.xml
file refers to the template file called jetty.xml
either in the current profile or in a parent profile directory. For more information about the mvel language, refer https://en.wikisource.org/wiki/MVEL_Language_Guide
bundle.foo = blueprint:mvel:profile:foo.xml bundle.bar = spring:mvel:profile:bar.xml
Appendix C. Profile Property Resolvers
Abstract
${ResourceReference}
. This variable substitution mechanism can be used in any profile resource, including the agent properties, PID properties, and other resources—for example, the mq-base
profile's broker.xml
resource references the ${broker.name}
and ${data}
variables.
C.1. Substituting system properties
Syntax
${PropName}
PropName
can be the name of any Java system property. In particular, Java system properties can be defined in the following locations:
- The
etc/system.properties
file, relative to the container's home directory. - System property settings in the profile's agent properties.
etc/system.properties
file are, as follows:
Table C.1. System Properties
System Property | Description |
---|---|
${karaf.home} | The directory where Apache Karaf is installed. |
${karaf.data} | Location of the current container's data directory, which is usually ${karaf.home}/data for a main container or ${karaf.home}/instances/InstanceName/data for a child container. |
${karaf.name} | The name of the current container. |
C.2. Substituting environment variables
Syntax
${env:VarName}
C.3. Substituting container attributes
Syntax
${container:Attribute}
Table C.2. Container Attributes
Attribute | Description |
---|---|
${container:resolver} | The effective resolver policy for the current container. Possible values are: localip , localhostname , publicip , publichostname , manualip . |
${container:ip} | The effective IP address used by the current container, which has been selected by applying the resolver policy. This is the form of host address that is advertised to other containers and applications. |
${container:localip} | The numerical IP address of the current container, which is suitable for accessing the container on a LAN. |
${container:localhostname} | The host name of the current container, which is suitable for accessing the container on a LAN. |
${container:publicip} | The numerical IP address of the current container, which is suitable for accessing the container from a WAN (on the Internet). |
${container:publichostname} | The host name of the current container, which is suitable for accessing the container from a WAN (on the Internet). |
${container:manualip} | An IP address that is specified manually, by setting the value of the relevant node in the ZooKeeper registry. |
${container:bindaddress} | |
${container:sshurl} | The URL of the SSH service, which can be used to log on to the container console. |
${container:jmxurl} | The URL of the JMX service, which can be used to monitor the container. |
${container:jolokiaurl} | The URL of the Jolokia service, which is used by the Fuse Management Console to access the container. |
${container:httpurl} | The base URL of the container's default Jetty HTTP server. |
${container:domains} | List of JMX domains registered by the container. |
${container:processid} | Returns the process ID of the container process (on Linux-like and UNIX-like operating systems). |
${container:openshift} | A boolean flag that returns true , if the container is running on OpenShift; otherwise, false . |
${container:blueprintstatus} | The aggregate status of all the deployed Blueprint contexts. If all of the deployed contexts are ok, the status is ok ; if one or more deployed contexts have failed, the status is failed . |
${container:springstatus} | The aggregate status of all the deployed Spring contexts. If all of the deployed contexts are ok, the status is ok ; if one or more deployed contexts have failed, the status is failed . |
${container:provisionstatus} | Returns the container provision status. |
${container:provisionexception} | If the container provisioning has failed, this variable returns the provisioning exception. |
${container:provisionlist} | The list of provisioned artefacts in the container. |
${container:geolocation} | The geographic location of the container (which is obtained by making a Web request to a public service that gives the GPS coordinates of the container host). |
C.4. Substituting PID properties
Syntax
${profile:PID/Property}
Example using a profile property resolver
fabric
profile's io.fabric8.maven.properties
PID resource includes the following property setting:
remoteRepositories=${profile:io.fabric8.agent/org.ops4j.pax.url.mvn.repositories}
remoteRepositories
property is set to the value of the org.ops4j.pax.url.mvn.repositories
agent property (io.fabric8.agent
is the PID for the agent properties).
C.5. Substituting ZooKeeper node contents
Syntax
${zk:/PathToNode}
${zk:ContainerName/Property}
${zk:/fabric/registry/containers/config/ContainerName/Property}
Recursive variable substitution
dosgi
profile's io.fabric8.dosgi.properties
resource defines the following property:
exportedAddress=${zk:${karaf.name}/ip}
How to reference the current version of a resource
my-profile
profile's my-resource
resource, which can be done using the following ZooKeeper URL:
${zk:/fabric/configs/versions/1.0/profiles/my-profile/my-resource}
1.0
, is embedded in this path. But if you decide to upgrade this profile to version 1.1
, this means you must manually edit all occurrences of this ZooKeeper URL, changing the version number to 1.1
in order to reference the upgraded resource. To avoid this extra work, and to ensure that the resolver always references the current version of the resource, you can use the following trick which exploits recursive variable substitution:
${zk:/fabric/configs/versions/${zk:/fabric/configs/containers/${karaf.name}}/profiles/my-profile/my-resource}
/fabric/configs/containers/${karaf.name}
ZooKeeper node contains the current profile version deployed in the container.
C.6. Checksum property resolver
Syntax
checksum:
scheme can be prefixed to any of the usual location URL handlers (for example, file:
, http:
, profile:
, zk:
).
default
profile defines the following checksum property in the org.ops4j.pax.web
PID:
org.ops4j.pax.web.config.checksum=${checksum:profile\:jetty.xml}
C.7. Port property resolver
Syntax
${port:Min,Max}
Min
and Max
specify the minimum and maximum values of the allocated IP port.
Appendix D. Technology-specific Discovery Mechanisms
Abstract
D.1. ActiveMQ endpoint discovery
discovery:(fabric:us-east)
us-east
represents a cluster of brokers deployed in the us-east
cloud.
D.2. Camel endpoint discovery
fabric:
- The
fabric:
prefix provides location transparency and load-balancing functionality for Camel endpoints. A consumer endpoint (acting like a server port), defines its endpoint URI using the following syntax:fabric:ClusterID:EndpointURI
So that the Camel endpoint URI,EndpointURI
, is stored in the Fabric registry under the cluster ID, ClusterID. Producer endpoints (acting like clients) can then access the Camel endpoint by specifying just the ClusterID, as follows:fabric:ClusterID
Fabric then resolves the cluster ID to the registered endpoint URI. If multiple endpoint URIs are registered under the same cluster ID, Fabric randomly selects one of the available URIs, thus providing load-balancing functionality. master:
- The
master:
prefix provides failover functionality for Camel endpoints. Two or more consumer endpoints (server ports) must register their URIs with the Fabric registry, using the following syntax:master:ClusterID:EndpointURI
Producer endpoints (acting like clients) can then access the failover cluster by defining a URI with the following syntax:master:ClusterID
Initially, Fabric chooses one of the consumer endpoints to be the master instance and always resolves the client URIs to this master location. If the master fails, however, Fabric will fail over to one of the other registered endpoint URIs and start resolving to that endpoint instead.
D.3. CXF endpoint discovery
D.4. OSGi service discovery
service.exported.interfaces
property (having a value of *
or an explicit list of interfaces to export) is automatically exported to the Fabric registry and becomes accessible to other remote containers in the same fabric.
<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>
Legal Notice
Trademark Disclaimer