Configure a Liberty collective

A collective supports clustering and other operations that act on multiple servers at a time. 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 (collectiveController-1.0) to become members. Members share information about themselves through the operational repository of the controller. The collectionController-1.0 feature and its capabilities are available only in WAS Liberty Network Deployment and WAS Liberty for z/OS. The controller can work with collective members from WAS Liberty, WAS Liberty - Express, and WAS Liberty Core.

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.

Configure the collective controller

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

2. Create the collective controller configuration.
   wlp/bin/collective create myController --keystorePassword=controllerKSPassword

   The above writes output to the console. To write output into a file.

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

3. Update server.xml of the collective controller.

   • If we wrote output to the console, copy and paste output into the collective controller server.xml file in...
     ${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

     Specify administrative user ID and password values for the collective.

     For example, change:

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

     to:

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

     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>

   • If you wrote the output to a file using the --createConfigFile=outputFilePath parameter, edit
     $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.

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.

   wlp/bin/collective join myMember --host=controllerHostname --port=9443 --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword

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

   wlp/bin/collective help join

   By default, the join operation leaves remote procedure call (RPC) credentials undefined, requiring 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