Configuring a Liberty collective

You can organize Liberty servers into collectives to support clustering, administration, and other operations that act on multiple Liberty servers. By using collectives, you can efficiently and accurately deliver application services to your application.

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.

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.

Multimedia 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

  1. Create and configure your controller.
    1. Create a server to act as the collective controller.
      wlp/bin/server create myController
    2. Create the collective controller configuration.

      The collective controller configuration 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 as in the following example:
      <include location="c:\wlp\usr\servers\myController\collective-create-include.xml" />
    3. Update the server.xml file of the collective controller.
      • Copy and paste output.

        If the command wrote output to a console screen, proceed with the following steps.

        1. Copy output from the collective command and paste it into the server.xml file.
        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 will resemble the following example:
        <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="yourPassword"
                      location="${server.config.dir}/resources/security/key.jks" />
        
            <!-- inbound (HTTPS) truststore -->
            <keyStore id="defaultTrustStore" password="yourPassword"
                      location="${server.config.dir}/resources/security/trust.jks" />
        
            <!-- server identity keystore -->
            <keyStore id="serverIdentity" password="yourPassword"
                      location="${server.config.dir}/resources/collective/serverIdentity.jks" />
        
            <!-- collective trust keystore -->
            <keyStore id="collectiveTrust" password="yourPassword"
                      location="${server.config.dir}/resources/collective/collectiveTrust.jks" />
        
            <!-- collective root signers keystore -->
            <keyStore id="collectiveRootKeys" password="yourPassword"
                      location="${server.config.dir}/resources/collective/rootKeys.jks" />
        </server>
      • Add an include statement.
        If you wrote the output to a file by 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. After editing, the contents of the file resemble the following 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 the outputted file sets administrative user ID and password values for the collective as in the following example:
        <quickStartSecurity userName="adminUser" userPassword="adminPassword" />
    4. Start the collective controller server.
      wlp/bin/server start myController
      Figure 1. Collective of one
      Collective of one
    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. 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.

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

      The optional parameter --hostname specifies the host name to use for the system. Set --hostname only if the system has multiple host names or does not have its host name configured. If set, the value must match the defaultHostName variable that is defined in the server.xml file.

      [18.0.0.1 and later]To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port.

      wlp/bin/collective join myMember 
      --controller=user[:password]@host:HttpsPort 
      --keystorePassword=memberKSPassword

      You can specify deployment variables by using the optional parameter genDeployVariable. For more information, see Generating deployment variables when joining a member server to a collective.

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

      By default, the join operation leaves remote procedure call (RPC) credentials undefined. You must specify values for rpcUser, rpcUserPassword, and 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.

      For information about these required parameters and other optional parameters, run collective help join at a command line.

    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, proceed with the following steps:

        1. Copy output from the collective command and paste it into the member server.xml file.
        2. Modify the ports so that 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.
        After editing, the file $WLP_USER_DIR/servers/myMember/server.xml resembles the following 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="yourPassword"
                      location="${server.config.dir}/resources/security/key.jks" />
        
            <!-- inbound (HTTPS) truststore -->
            <keyStore id="defaultTrustStore" password="yourPassword"
                      location="${server.config.dir}/resources/security/trust.jks" />
        
            <!-- server identity keystore -->
            <keyStore id="serverIdentity" password="yourPassword"
                      location="${server.config.dir}/resources/collective/serverIdentity.jks" />
        
            <!-- collective truststore -->
            <keyStore id="collectiveTrust" password="yourPassword"
                      location="${server.config.dir}/resources/collective/collectiveTrust.jks" />
        </server>
      • Add an include statement.
        If you wrote the output to a file by using the --createConfigFile=outputFilePath parameter, add an include statement to $WLP_USER_DIR/servers/myMember/server.xml to include the outputted file as in the following 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 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:
      • 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 in to the member computer with user test1 and password test1pwd, then change the hostAuthInfo element:
        <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. For z/OS only, issue the updateHost command to specify the member JAVA_HOME directory for the controller.
      wlp/bin/collective updateHost controllerHostname --host=controllerHostname
      --port=9443 --user=adminUser --password=adminPassword
      --hostWritePath=/dir1 --rpcUser=rpcUser
      --rpcUserPassword=rpcUserPassword --hostJavaHome=JAVA_HOME

      [18.0.0.1 and later]To reduce the number of options needed, use the --controller option instead of --user, --password, --host, and --port:

      wlp/bin/collective updateHost controllerHostname 
      --controller=adminUser:adminPassword@controllerHostname:9443
      --hostWritePath=/dir1 --rpcUser=rpcUser
      --rpcUserPassword=rpcUserPassword --hostJavaHome=JAVA_HOME

      The hostWritePath parameter specifies the directories to which the collective controller can write. Paths that are specified by the parameter are also readable.

      hostWritePath

      The hostJavaHome parameter specifies the absolute path to where the JVM is on the system and where the member server runs, for example /usr/lpp/java/java_1.7_64.

      For more information about specifying JAVA_HOME, see Setting the JAVA_HOME variable for Liberty collective members and controllers.

    7. Start the member server.
      wlp/bin/server start myMember
      Figure 2. Simple collective
      Simple collective
    8. 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.
    9. Optional: [18.0.0.1 and later]Use the testConnection command to validate connectivity. The command validates RXA connectivity between the controller and the host where the member resides. It also validates JMX secure connectivity between the collective controller and the collective member.
      wlp/bin/collective testConnection hostName,usrDirPath,serverName  --host=controllerHost
      --port=controllerHTTPSPort --user=controllerAdmin 
      --password=controllerAdminPassword--autoAcceptCertificates
      Where hostName,usrDirPath,serverName is the tuple that describes the member server just joined: hostName is the name of the host where the collective member resides. userDirPath is the collective member's usr directory. serverName is the name of the collective member.
      [18.0.0.1 and later]Alternatively, use the simplified --controller option to provide the controller specific information.
      wlp/bin/collective testConnection hostName,usrDirPath,serverName 
      --controller=user[:password]@host:HttpsPort 
      --autoAcceptCertificates

Icon that indicates the type of topic Task topic

File name: tagt_wlp_configure_collective.html