Configure a Liberty collective

We can organize Liberty servers into collectives to support clustering, administration, and other operations that act on multiple Liberty servers at a time in order to efficiently and accurately deliver application services to the organization.

The collectiveController-1.0 feature and its capabilities are available only in...

• WebSphere Application Server Liberty Network Deployment
• WebSphere Application Server Liberty for z/OS

The feature is not available in...

• WebSphere Application Server Liberty
• WebSphere Application Server Liberty - Express
• WebSphere Application Server Liberty Core

If we have a WAS Liberty ND installation, we can use the collectiveController-1.0 feature to work with collective members from...

• WAS Liberty
• WAS Liberty - Express
• WAS Liberty Core

A Liberty collective is a set of Liberty servers 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.

Watch: Video: Introduction to creating a collective demonstrates the procedure. This video, and other information about collectives, is available on the WASdev website. [Transcript]

1. Create and configure the controller.

   1. Create a server to act as the collective controller.
      wlp/bin/server create myController

   2. Create the collective controller configuration.

      This consists primarily of the administrative domain.used for secure communication between controllers and members.

      wlp/bin/collective create myController --keystorePassword=controllerKSPassword

      By default, this collective command writes output to a console screen. In the next step, we copy the output into server.xml. To write the output to a file, instead of to a console screen, specify an optional parameter: --createConfigFile=outputFilePath

      wlp/bin/collective create myController --keystorePassword=controllerKSPassword --createConfigFile=c:/wlp/usr/servers/myController/collective-create-include.xml

      After running the create command, the include statement to use is displayed. To include the outputted file in the collective configuration, add the include statement to server.xml; for example:

      <include location="c:\wlp\usr\servers\myController\collective-create-include.xml" />

   3. Update server.xml of the collective controller.

      • Copy and paste output.

        If the command wrote output to a console screen:

        1. Copy output from the collective command and paste it into server.xml.

        2. Specify administrative user ID and password values for the collective. For example, change:
           <quickStartSecurity userName="" userPassword="" />

           to:

           <quickStartSecurity userName="adminUser" userPassword="adminPassword" />

        The default path for the collective controller server.xml file is ${wlp.install.dir}/usr/servers/myController/server.xml or, if the $WLP_USER_DIR variable is set in a server.env file or command window, $WLP_USER_DIR/servers/myController/server.xml. After editing, the file resembles:

        <server description="controller server">
        
            <!-- Enable features -->
        
            <featureManager>
                <feature>jsp-2.2</feature>
            </featureManager>
        
            <httpEndpoint id="defaultHttpEndpoint"
                          host="*"
                          httpPort="9080"
                          httpsPort="9443" />
        
            <featureManager>
                <feature>collectiveController-1.0</feature>
            </featureManager>
        
            <!-- Define the host name for use by the collective. 
            If the host name needs to be changed, the server should be     
            removed from the collective and re-joined or re-replicated. -->
        
            <variable name="defaultHostName" value="controllerHostname" />
        
            <!-- TODO: Set the security configuration for Administrative access -->
        
            <quickStartSecurity userName="adminUser" userPassword="adminPassword" />
        
            <!-- clientAuthenticationSupported set to enable bidirectional trust -->
        
            <ssl id="defaultSSLConfig"
                 keyStoreRef="defaultKeyStore"
                 trustStoreRef="defaultTrustStore"
                 clientAuthenticationSupported="true" />
        
            <!-- inbound (HTTPS) keystore -->
            <keyStore id="defaultKeyStore" password="myPassword"
                      location="${server.config.dir}/resources/security/key.jks" />
        
            <!-- inbound (HTTPS) truststore -->
            <keyStore id="defaultTrustStore" password="myPassword"
                      location="${server.config.dir}/resources/security/trust.jks" />
        
            <!-- server identity keystore -->
            <keyStore id="serverIdentity" password="myPassword"
                      location="${server.config.dir}/resources/collective/serverIdentity.jks" />
        
            <!-- collective trust keystore -->
            <keyStore id="collectiveTrust" password="myPassword"
                      location="${server.config.dir}/resources/collective/collectiveTrust.jks" />
        
            <!-- collective root signers keystore -->
            <keyStore id="collectiveRootKeys" password="myPassword"
                      location="${server.config.dir}/resources/collective/rootKeys.jks" />
        </server>

      • 

        Add an include statement.

        If you wrote the output to a file using the --createConfigFile=outputFilePath parameter, add an include statement to $WLP_USER_DIR/servers/myController/server.xml to include the outputted file in the collective configuration; for example:

        <server description="controller server">
        
            <!-- Enable features -->
        
            <featureManager>
                <feature>jsp-2.2</feature>
            </featureManager>
        
            <httpEndpoint id="defaultHttpEndpoint"
                          host="*"
                          httpPort="9080"
                          httpsPort="9443" />
        
            <include location="c:\wlp\usr\servers\myController\collective-create-include.xml" />
        
        </server>

        Ensure that the outputted file sets administrative user ID and password values for the collective; for example:

        <quickStartSecurity userName="adminUser" userPassword="adminPassword" />

   4. Start the collective controller server.
      wlp/bin/server start myController

      

   5. Verify that the collective controller server started correctly and is ready to receive members.

      1. Open an editor on the collective controller messages log...
         $WLP_USER_DIR/servers/myController/logs/messages.log

      2. Look for the following message:
         CWWKX9003I: CollectiveRegistration MBean is available.

2. 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.

   1. Create a member server.
      wlp/bin/server create myMember

   2. Join the member.

      Run the collective join command to join the server to the collective as a member. 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 server.xml 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. We 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 prompt.

      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, specify an optional --useHostCredentials parameter to enable the member to inherit RPC credentials from its host registration on the controller. Specifying --useHostCredentials adds <hostAuthInfo useHostCredentials="true" /> to the member server.xml file. We 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.

      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 />

   3. If prompted to accept the certificate chain, enter y (yes).

   4. Update the member server.xml file.

      • Copy and paste output.

        If the command wrote output to a console screen:

        1. Copy output from the collective command and paste it into the member server.xml file.

        2. Modify the ports so the server can open its HTTP ports. Ensure the member server.xml sets unique HTTP port numbers on its host. For example, if the member is on the same host as the collective controller, change the HTTP port numbers:
           <httpEndpoint id="defaultHttpEndpoint" httpPort="9081" httpsPort="9444" />

           Optionally, to access the member server from a remote client, also set host="*" in the httpEndpoint element.

        In $WLP_USER_DIR/servers/myMember/server.xml, for example:

        <server description="member server">
        
            <!-- Enable features -->
        
            <featureManager>
                <feature>jsp-2.2</feature>
            </featureManager>
        
            <httpEndpoint id="defaultHttpEndpoint"
                          host="*"
                          httpPort="9081"
                          httpsPort="9444" />
        
            <featureManager>
                <feature>collectiveMember-1.0</feature>
            </featureManager>
        
            <!-- Define the host name for use by the collective.
            If the host name needs to be changed, the server should be     removed from the collective and re-joined or re-replicated. -->
        
            <variable name="defaultHostName" value="memberHostname" />
        
         <!-- Remote host authentication configuration -->
            <hostAuthInfo rpcUser="admin_user_id" rpcUserPassword="admin_user_password" />
        
            <!-- Connection to the collective controller -->
            <collectiveMember controllerHost="controllerHostname"
                              controllerPort="9443" />
        
            <!-- clientAuthenticationSupported set to enable bidirectional trust -->
        
            <ssl id="defaultSSLConfig"
                 keyStoreRef="defaultKeyStore"
                 trustStoreRef="defaultTrustStore"
                 clientAuthenticationSupported="true" />
        
            <!-- inbound (HTTPS) keystore -->
            <keyStore id="defaultKeyStore" password="myPassword"
                      location="${server.config.dir}/resources/security/key.jks" />
        
            <!-- inbound (HTTPS) truststore -->
            <keyStore id="defaultTrustStore" password="myPassword"
                      location="${server.config.dir}/resources/security/trust.jks" />
        
            <!-- server identity keystore -->
            <keyStore id="serverIdentity" password="myPassword"
                      location="${server.config.dir}/resources/collective/serverIdentity.jks" />
        
            <!-- collective truststore -->
            <keyStore id="collectiveTrust" password="myPassword"
                      location="${server.config.dir}/resources/collective/collectiveTrust.jks" />
        </server>

      • 

        Add an include statement.

        If you wrote the output to a file using the --createConfigFile=outputFilePath parameter, add an include statement to $WLP_USER_DIR/servers/myMember/server.xml to include the outputted file; for example:

        <server description="member server">
        
            <!-- Enable features -->
        
            <featureManager>
                <feature>jsp-2.2</feature>
            </featureManager>
        
            <httpEndpoint id="defaultHttpEndpoint"
                          host="*"
                          httpPort="9081"
                          httpsPort="9444" />
        
            <include location="c:\wlp\usr\servers\myMember\collective-join-include.xml" />
        
        </server>

   5. If we did not specify --useHostCredentials in the join command, set RPC credentials for hostAuthInfo in the member server.xml file or the outputted file. We can set RPC credentials for the member server in either of two ways:

      • Set hostAuthInfo RPC user and password values. Set rpcUser to an operating system login user ID for the host on which the member server resides, and set rpcUserPassword to the operating system login password for the user ID. For example, if you log into the member computer with user test1 and password test1pwd, then change the hostAuthInfo element to the following:
        <hostAuthInfo rpcUser="test1" rpcUserPassword="test1pwd" />

      • If the member host is registered with the collective controller, set hostAuthInfo useHostCredentials to true for the member server to inherit RPC credentials from its host.
        <hostAuthInfo useHostCredentials="true" />

      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.

   6. Start the member server.
      wlp/bin/server start myMember

      

   7. Verify that the member server started correctly and is publishing information to the controller.

      1. Open an editor on the member messages log, $WLP_USER_DIR/servers/myMember/logs/messages.log.

      2. 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.

defaultCollective

By default, a Liberty collective has the name defaultCollective. A different name can be specified with the --collectiveName option of the collective create command. Although the name is not visible in the Admin Center, it is used by the dynamic routing feature in multi-collective scenarios.

In collectives with multiple controllers the collective name will sporadically change between the given name and defaultName.

See: PI74526: A collective name sporadically changes between its given name and the default name

Subtopics

• Configure a Liberty collective using the developer tools
  

Parent topic: Set up collectives

Concepts:

Collective architecture
File transfer in a Liberty collective
Collective security
File transfer
Liberty collective troubleshooting

Tasks:

Access local and JMX REST connectors
Set the default host name of a Liberty server
Generating collective controller SSL keys
Example of setting up a JMX routing environment
List of provided MBeans