You can configure the Dynamic Routing feature to route application requests to all
application instances when the application is deployed in multiple collectives.
About this task
Intelligent Management for web servers enables routing of HTTP requests to members of Liberty
collectives without requiring an administrator to regenerate the WebSphere® plug-in configuration file when the environment changes. When servers,
cluster members, applications, or virtual hosts are added, removed, started, stopped, or modified;
the new information is dynamically delivered to the WebSphere plug-in. Requests are routed based on up-to-date information.
Intelligent Management for web servers routes application requests to all application instances
when the application is deployed in multiple collectives. Previously, when requests were routed to
multiple collectives, a particular application was not allowed to be installed in more than one
collective.
To use Intelligent Management for web servers to route HTTP requests to Liberty collectives, enable the
dynamicRouting-1.0 feature in all collective controllers of the collectives. The
dynamicRouting-1.0 feature provides a Dynamic Routing service that delivers routing
information to Intelligent Management for web servers. Use the setup,
genPluginCfg, and genKeystore command actions to generate the
keystores that are needed for secure communication between the plug-in and the Dynamic Routing
service, and a plug-in configuration file that enables Intelligent Management for web servers in the
WebSphere plug-in.
Important: To route to the same application in multiple collectives, each
collective must have a unique name. The unique name of a collective can appear as one of the
following two examples:
- Use the connectorClusterName attribute of the
<dynamicRouting> XML element in the server.xml of the
collective controllers. All controllers in the same collective must use the same value for the
connectorClusterName attribute. Controllers in different collectives must use
different values for the connectorClusterName attribute. If the
connectorClusterName attribute is specified, the value overrides the value that is
specified with the –collectiveName option used when the collective was
created.
- Use the ‑‑collectiveName option when the collective is created with the
collective create command.
Dynamic Routing controllers in each collective inform the WebSphere plug-in about the state of the collective so the plug-in can dynamically route
requests for the same application across multiple collectives. The Dynamic Routing controllers
inform the WebSphere plug-in about each application that
is available in the controller's collective. Thus, the WebSphere plug-in is aware when an application is available in more than one collective.
Unless a rule states otherwise, all requests to an application are balanced across all appropriate
servers.
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.
- 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>
- 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>
- Start all controllers that are enabled with the Dynamic Routing feature.
- 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.
- Copy all the generated plugin-key*.jks 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.jks allows collective member servers in all collectives to
accept requests that are proxied through the web server.
- The plugin-key-collective_name.jks 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.
- On the web server host, run gskcmd (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:
gskcmd -keydb -convert -pw <password> -db /tmp/plugin-key.jks -old_format jks -target /tmp/plugin-key.kdb -new_format cms -stash
gskcmd -cert -setdefault -pw <password> -db /tmp/plugin-key.kdb -label default
Run the gskcmd on all the generated plugin-key*.jks
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.
- Copy all the plugin-key.kdb, plugin-key.rdb, and
plugin-key.sth files that are created by gskcmd from the
temporary directory to the
--pluginInstallRootargument_value/config/web_server_name/
directory.
- 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>
- Start the web server and begin routing to the application installed in the collective.
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.