Setting up dynamic routing for multiple Liberty collectives

You can configure the Dynamic Routing feature to route application requests to all application instances when the application is deployed in multiple collectives.

1. Enable Dynamic Routing in a controller by adding the following code to the featureManager tag in the server.xml of the controller.

   <feature>dynamicRouting-1.0</feature>

2. Optional: Add the <dynamicRouting> element to the controller server.xml to specify properties for dynamic routing.

   The connectorClusterName property specifies the name that dynamic routing associates with the collective. If the connectorClusterName property is not specified, the name of the collective is used.

   For example, in the first collective, specify the following name on all of the controllers:

   <dynamicRouting connectorClusterName="collective1"/>

   For example, in the second collective, specify the following name on all of the controllers:

   <dynamicRouting connectorClusterName="collective2"/>

   If a connection fails, the retryInterval property specifies wait time before it attempts another connection to a controller. The maxRetries property specifies the number of times to try to reconnect to a failed collective controller. See the following example:

   <dynamicRouting maxRetries="4" retryInterval="20" 
   connectorClusterName="collective1"/>
    <TraceSpecification name="default" specification=":DEBUG"/>
   </dynamicRouting>

   The generated plugin-cfg.xml contains the ConnectorCluster properties. See the following example:

   <IntelligentMangement>
    …
     <ConnectorCluster enabled="true" maxRetries="4" name="collective1" retryInterval="20">
     <Property name="uri" value="/ibm/api/dynamicRouting"/>
     <Connector host="controller1.acme.com" port="9444" protocol="https">
     <Property name="keyring" value="/opt/HTTPServer_Plugins/config/webServer1/plugin-key.kdb"/>
     </Connector>
    </ConnectorCluster>
    …
   </IntelligentManagement>
   

3. Start all controllers that are enabled with the Dynamic Routing feature.
4. Run the dynamicRouting setup command on one of the controllers to generate the keystore and plug-in configuration files.
   To create the artifacts that are needed for multiple-collective dynamic routing, use the --collectives option instead of the --port, --host, --user, or --password options. Specify collectives in the collective_user:user_password@collective_host:port format with a comma (,) separating each collective. See the following example:

   ./dynamicRouting setup --collectives user1:password1@host1:port1,user2:password2@host2:port2,...
   --keystorePassword=webAS --pluginInstallRoot=/opt/HTTPServer_Plugins/ --webServerNames=webserver1

   Ensure that each collective has a unique name. Also, ensure that the users exist in the user registries of their collectives and have an administrative role. If you do not specify a password, you are prompted.

   See requirements for the --collectives option.

   For more information about the dynamicRouting setup command, see Dynamic routing command.

5. Copy all the generated plugin-key*.p12 files and the plugin-cfg.xml file to a temporary directory on the web server host.

   For the --collectives option, multiple keystore files are created:

   • The plugin-key.p12 allows collective member servers in all collectives to accept requests that are proxied through the web server.
   • The plugin-key-collective_name.p12 provides a plug-in key file for each collective specified with the --collectives option.

   These files enable the WebSphere plug-in to communicate securely with the collective controllers in the specific collective.

   Attention: The dynamicRouting command creates a PKCS12 keystore. For more information, see Configuring a Liberty collective.
6. On the web server host, run gskcapicmd (included in the IHS package) to convert the keystore to CMS format and to set personal certificate as the default. CMS format is the supported format of the WebSphere plug-in. See the following example:

   gskcapicmd -keydb -convert -pw <password> -db /tmp/plugin-key.p12 -old_format pkcs12 -target /tmp/plugin-key.kdb -new_format cms -stash

   Run the gskcapicmd on all the generated plugin-key*.p12 files. Change the -db and -target options to specify each file.

   For z/OS®, see Conversion of the keystore to CMS format on z/OS.

7. Use chown <user>:<group> plugin-key.kdb plugin-key.rdb plugin-key.sth on the files that are created by the gskcapicmd in the temporary directory. The user and group should match the ones found listed as User and Group in the file IHSinstallRoot/conf/httpd.conf.
   For example:

   chown nobody:nobody plugin-key.kdb plugin-key.rdb plugin-key.sth

8. Copy all the plugin-key.kdb, plugin-key.rdb, and plugin-key.sth files that are created by gskcapicmd from the temporary directory to the --pluginInstallRootargument_value/config/web_server_name/ directory.
9. Copy the plugin-cfg.xml file to the directory specified in the WebSpherePluginConfig directive in the web server httpd.conf file.

   The plugin-cfg.xml file is generated with the <IntelligentManagement> stanza. When Dynamic Routing is enabled in a collective, the file has one <Connector> stanza for each collective controller. For multiple-collective routing, each collective has one <ConnectorCluster> stanza. See the following example:

   <Property Name="Keyfile" Value="/opt/IBM/WebSphere/Plugins/config/webserver1/plugin-key.kdb"/>
   <Property Name="Stashfile" Value="/opt/IBM/WebSphere/Plugins/config/webserver1/plugin-key.sth"/>
   <IntelligentMangement>
    <Property name="webserverName" value="webserver1"/>
    <Property name="RoutingRulesConnectorClusterName" value="collective1"/>
    <ConnectorCluster enabled="true" maxRetries="-1" name="collective1" retryInterval="60">
     <Property name="uri" value="/ibm/api/dynamicRouting"/>
     <Connector host="controller1.acme.com" port="9444" protocol="https">
      <Property name="keyring" value="/opt/HTTPServer_Plugins/config/webserver1/plugin-key-collective1.kdb"/>
     </Connector>
    </ConnectorCluster>
   <ConnectorCluster enabled="true" maxRetries="-1" name="collective2" retryInterval="60">
     <Property name="uri" value="/ibm/api/dynamicRouting"/>
     <Connector host="controller2.acme.com" port="9444" protocol="https">
      <Property name="keyring" value="/opt/HTTPServer_Plugins/config/webserver1/plugin-key-collective2.kdb"/>
     </Connector>
    </ConnectorCluster>
   </IntelligentManagement>

10. Start the web server and begin routing to the application installed in the collective.
11. Optional: Create routing rules to specify how particular requests are handled.

    Routing rules can specify to:

    • Reject specific requests.
    • Redirect specific requests.
    • Allow specific requests to go to a subset of the available servers.
    • Failover specific requests from one set of servers to another set of servers.

    See Routing rules for Liberty dynamic routing and Configuring routing rules for Liberty dynamic routing.