You can organize Liberty servers into collectives to support clustering, administration,
and other operations that act on multiple Liberty servers at a time to efficiently and accurately
deliver application services to your organization.
Before you begin
Install Liberty with the administrative features. For installation instructions, see the
"Before you begin" section of Setting up the server-management environment for Liberty by using collectives. The Liberty
administrative features provide multiple-server management features for collectives, clusters,
scaling, dynamic routing, and Admin Center.

The collectiveController-1.0 feature and its
capabilities are available only in WebSphere® Application
Server Liberty Network Deployment and WebSphere Application Server Liberty for z/OS®. The feature is not available in WebSphere Application Server Liberty, or
WebSphere Application Server Liberty Core. If you have a WebSphere Application Server Liberty
Network Deployment installation, you can use its collectiveController-1.0 feature
to work with collective members from WebSphere Application Server Liberty, or WebSphere Application
Server Liberty Core installations.
About this task
A Liberty collective is a set of Liberty servers that are configured as part of the same
administrative and operational domain.
Configuration and state data about a Liberty collective is housed in an active operational
repository.
Membership in a Liberty collective is optional. Liberty servers join a collective by registering
with a collective controller to become members. Members share information about themselves through
the operational repository of the controller.
The following rules apply:
- A Liberty server can be a member of only one collective.
- Different Liberty servers on the same host can be in different collectives.
- Liberty servers on the same host that are members of a collective can coexist with Liberty
servers that are not members of a collective.
- All members of a collective must be in the same data center. A collective must not span data
centers.
Watch:
Video:
Introduction to creating a collective demonstrates the procedure. This video, and other
information about collectives, is available on the WASdev website. [Transcript]
Procedure
- Create and configure your controller.
- Create a server to act as the collective controller.
wlp/bin/server create myController
- Create the collective controller configuration.
This consists primarily of the administrative domain security configuration that is used for
secure communication between controllers and members.
wlp/bin/collective create myController --keystorePassword=controllerKSPassword
By default, this collective command writes all output to a console screen. In the next step, you
copy the configuration output into the
server.xml. To write the configuration
to a file instead of to a console screen, specify a
--createConfigFile=outputFilePath parameter, for example:
wlp/bin/collective create myController --keystorePassword=controllerKSPassword --createConfigFile=c:/wlp/usr/servers/myController/collective-create-include.xml
After
you run the
create command, the
include statement to use is
displayed. To include the outputted file in the collective configuration, add the
include statement to the
server.xml file, for
example:
<include location="c:\wlp\usr\servers\myController\collective-create-include.xml" />
- Update the server.xml file of the collective controller.
- Start the collective controller server.
wlp/bin/server start myController
Figure 1. Collective of one
- Verify that the collective controller server started correctly and is ready to receive
members.
- Open an editor on the collective controller messages log, $WLP_USER_DIR/servers/myController/logs/messages.log.
- Look for the following
message:
CWWKX9003I: CollectiveRegistration MBean is available.
- Create and configure a member to join the collective.
The controller and members can be on separate hosts. In this example, the controller and member
are on the same host.
- Create a member server.
wlp/bin/server create myMember
- Join the member.
Run the collective join command to join the server to the collective as a
member. Run the join command from the Liberty installation on the member
host.
The join command requires a network connection to the collective controller
and an administrative user ID and password for performing MBean operations on the controller. Look
at the server.xml file of the collective controller to find the values for the
--host, --port, --user, and
--password parameters. For --keystorePassword, set a value to use
for the member keystore password, such as memberKSPassword. You can specify
different --keystorePassword values for each server that is joined to the
collective. For information about these required parameters and about optional parameters, run
collective help join at a command line.
wlp/bin/collective join myMember --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword
By default, the join operation leaves remote procedure call (RPC) credentials
undefined, requiring you to specify values for rpcUser and
rpcUserPassword, the operating system login user and password for the host, on
which the member server resides. If the member host is registered with the collective controller and
the member host is not enabled for SSH, specify an optional --useHostCredentials
parameter to enable the member to inherit RPC credentials from its host registration on the
controller. Typically, Linux hosts are enabled for SSH and Windows hosts are not enabled for SSH;
thus, the --useHostCredentials parameter is useful for Windows member hosts.
Specifying --useHostCredentials adds <hostAuthInfo
useHostCredentials="true" /> to the member server.xml file. You then
can run collective member server commands such as start or
stop without specifying RPC credentials because the member inherits credentials
from its host. See Overriding Liberty server host information for information about
hostAuthInfo, the --useHostCredentials parameter, and connecting
the collective controller to the server. See Setting up RXA for Liberty collective operations for information about
enabling SSH on your host computer.
To write the output of this collective command to a file, instead of to
a console screen, specify an optional
--createConfigFile=outputFilePath parameter. Then, include the
outputted file in the collective configuration by adding an
include statement to
the member
server.xml
file:
<include location=outputFilePath />
- If prompted to accept the certificate chain, enter y (yes).
- Update the member server.xml file.
- If you did not specify --useHostCredentials in the join
command and the member host is not enabled for SSH, set RPC credentials for
hostAuthInfo in the member server.xml file or the outputted
file. You can set RPC credentials for the member server in either of two ways:
See Overriding Liberty server host information for information about
hostAuthInfo settings and for an example that shows how to register a member host
and run the join command with --useHostCredentials.
- Start the member server.
wlp/bin/server start myMember
Figure 2. Simple collective
- Verify that the member server started correctly and is publishing information to the
controller.
- Open an editor on the member messages log, $WLP_USER_DIR/servers/myMember/logs/messages.log.
- Look for the following messages in any
order:
CWWKX8112I: The server's host information was successfully published to the collective repository.
CWWKX8114I: The server's paths were successfully published to the collective repository.
CWWKX8116I: The server STARTED state was successfully published to the collective repository.