Set up dynamic routing for a single Liberty collective

Overview

We can configure the Dynamic Routing feature to route HTTP requests to members of Liberty collectives without having to regenerate the WebSphere plug-in configuration file when the environment changes.

To use Intelligent Management to route HTTP requests to a Liberty collective, we must enable the dynamicRouting-1.0 feature on one or more collective controllers in a collective. The feature provides the Dynamic Routing service, which dynamically retrieves routing information from the collective repository and delivers this information to the WebSphere plug-in. The feature also provides the dynamicRouting command. Use its setup, genPluginCfg, and genKeystore command actions together to generate the keystores needed for secure communication between the plug-in and the Dynamic Routing service, and a plug-in configuration file that enables Intelligent Management in the WebSphere plug-in.

The routing rules capability enables incoming requests to the WebSphere plug-in to be routed to a specified set of servers. Additionally, requests can selectively be rejected or redirected. Selection of whether a rule applies to an incoming request is done through matching of attributes of the incoming request.

Set up dynamic routing

  1. Install the web server plugin and fixpack.

  2. Add the following code to the featureManager tag in the server.xml of the controller.

      <feature>dynamicRouting-1.0</feature>

  3. Start all controllers enabled by the Dynamic Routing feature.

  4. On one of the controllers generate the keystore and plug-in configuration files.

      ./dynamicRouting setup \
          --port=9444 \
          --host=controller1.acme.com \
          --user=admin \
          --password=passw0rd \
          --keystorePassword=webAS \
          --pluginInstallRoot=/opt/HTTPServer_Plugins/ \
          --webServerNames=webserver1

    Note: Ensure a specified value of the --user argument exists in a user registry and is assigned an administrative role.

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

  6. On the web server host convert the keystore to CMS format and set personal certificate as the default.

      gskcapicmd \
          -keydb \
          -convert \
          -pw webAS \
          -db /tmp/plugin-key.p12 \
          -old_format pkcs12 \
          -target /tmp/plugin-key.kdb \
          -new_format cms \
          -stash

    CMS format is the supported format of the WebSphere plug-in. The dynamicRouting command creates a PKCS12 keystore.

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

  7. Chown ownershp of the files created by gskcapicmd:

      chown user:group plugin-key.kdb plugin-key.rdb plugin-key.sth

    For example:

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

    The user and group should match the ones found listed as User and Group in the file...

      IHS_HOME/conf/httpd.conf

  8. Copy the plugin-key.kdb, plugin-key.rdb, and plugin-key.sth files created by gskcapicmd from the temporary directory to the directory

      --pluginInstallRootargument_value/config/web_server_name/

  9. Copy the plugin-cfg.xml to the directory specified in the WebSpherePluginConfig directive in the web server httpd.conf file.

    The plugin-cfg.xml is generated with the <IntelligentManagement> stanza. When Dynamic Routing is enabled in a collective, one <Connector> stanza exists for each collective controller. For example: 

      <IntelligentManagement>
  <Property name="webserverName" value="webServer1"/>

     <ConnectorCluster 
         enabled="true" 
         maxRetries="-1" 
         name="default" 
         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.kdb"/>
     </Connector>
  </ConnectorCluster>

</IntelligentManagement>

  10. Start the web server and begin routing to the application installed in the collective.

  11. 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. The retryInterval property specifies how long to wait before a reconnection to a controller if a connection fails. The maxRetries property specifies the number of times to try to reconnect to a failed collective controller. For example: 

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

    The generated plugin-cfg.xml has the <ConnectorCluster> properties:

      <IntelligentManagement> <TraceSpecification name="default" specification=":DEBUG"/> <Property name="webserverName" value="webServer1"/> <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>

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

With the dynamicRouting-1.0 feature enabled, Intelligent Management can now dynamically route HTTP requests to Liberty collectives.

Parent: Set up dynamic routing for Liberty collectives


Related concepts