Environment
Situation
If you have a multi-server installation of Verastream Host Integrator (VHI), you can establish failover capability for the management server cluster by creating and using a DNS alias name.
Verastream Management Server is a component of Verastream Host Integrator that provides support for the following features:
- Administrative Console
- Session Server load distribution domains
- Authentication and authorization security (including LDAP directory services)
- Web Services Explorer (beginning in version 7.1)
- Session pool scheduling
Multiple management servers in an installation environment are called a “cluster†or “management cluster.†Data is automatically replicated between the management server peers in a cluster. Note: Each management server is a member of only one cluster.
Resolution
With a Management Server failover configuration, if one of the management servers fails or is offline, another management server in the cluster can provide services. Failover configuration provides fault tolerance for production environments.
Note the following:
- Management Server and Session Server components have separate failover mechanisms. Session Server failover and load distribution is addressed separately in KB 7021566.
- In a multi-server failover environment, all servers (running management server and/or session server components) must be able to communicate with each other, and the clients (running connector API) must be able to communicate with all servers.
- Each management server (and each session server) can belong to only one cluster/installation.
- Management Server failover is based on standard IP name resolution functionality, which allows an alias name to be mapped to multiple IP addresses.
Implementing Management Server Failover
To configure failover for Management Server, perform the following steps:
- Install Host Integrator software (including the Management Server component) on your systems. When installing on a second (or additional) server, select “Join an existing installation†and use the host name or IP address of the first server.
Note: Beginning in version 7.0, you do not need to enter the DNS alias during installation. You can create and change your DNS alias (step 2 below) anytime before or after installation. (In version 6.6 and earlier, you were required to create an AADS common name prior to installing the first server, and any subsequent changes to this name required re-installation.)
- Create a single DNS alias (common name) for all the IP addresses of Management Servers in the installation environment. Each Management Server IP address must be assigned to the same common name.
Recommended Method: For ease of maintenance, it is recommended that you configure your DNS server.
Beginning in version 7.0, it is acceptable for the DNS server to return results in round-robin or random order for load distribution, as the default management server configuration (ManagementServer/conf/container.conf file) has DNS caching disabled (-Dsun.net.inetaddr.ttl=0).
Alternative Method: If it is impractical to configure your DNS server, you can edit the hosts file on each system with Host Integrator server or client components installed (including connectors used by client applications). Example:
# Hosts file example# Verastream Host Integrator production environment in Seattle# "vhi-prod-sea" is the common name for the management server cluster# One line for each VHI server (running management server service)# Each line has the IP address, unique server name, and cluster name# The values within each line are delimited by spaces or tabs10.0.0.1 workhorse01 vhi-prod-sea10.0.0.2 workhorse02 vhi-prod-sea10.0.0.3 workhorse03 vhi-prod-seaNote the following:
- If using this method, the hosts file should be updated on all systems in the environment. All servers (running management server and/or session server components) must be able to communicate with each other, and the clients (running connector API) must be able to communicate with all servers.
- The local unique system name is listed separately first to avoid problems with reverse DNS lookups on some platforms. This is followed by lines for the cluster common name (one line for each system running the Management Server service).
- For systems that have multiple network interfaces, all IP addresses should be listed.
- On Windows systems, the hosts file is typically located in the C:\Windows\System32\drivers\etc folder. On UNIX/Linux systems, the hosts file is located in the /etc directory.
- Networking protocols mandate that the hostname contain only ASCII letters a through z (case insensitive), digits 0 through 9, and the hyphen character (-).
- Comments beginning with the # character (through the end of the line) are ignored.
- In Administrative Console, it is suggested that you also change the name of the Management Cluster (Perspective > Management > Servers > Management Cluster > Properties). The default cluster name is the system host name where Management Server was first installed, but you can change it to the cluster DNS alias for your installation environment.
The cluster name displays in the Administrative Console status bar (lower right) when connected.
- To achieve failover capability, enter the cluster DNS alias name whenever you are required to provide a Management Server address:
- In Administrative Console, when prompted to connect.
- In your client application, when calling ConnectToSessionViaDomain or ConnectToModelViaDomain method in the connector API.
- In your Web Builder project properties, when “Connect to model via domain†or “Connect to session pool via domain†is selected for the model connection.
- In the web service functionality, using one of the following methods:
Option 1: Edit the %VHI_ROOT%/sesssrvr/services/ws/META-INF/plugin-cfg.xml file (in version 7.1.1142 or higher) which is created after web services are configured in Administrative Console. Change the serverName key value to the management cluster alias (instead of the default localhost). Example:
<entry key="serverName">mycluster</entry>Option 2: Alternatively, you can specify the ServerName environment variable in your SOAP/REST request, which takes precedence over any plugin-cfg.xml configuration.
However, when deploying models (using activatemodel and deactivatemodel commands, or Design Tool), use the specific individual session server system names (not the cluster common alias name).
What Happens At Runtime
When establishing a connection to the management server alias name, IP name resolution returns the list of IP addresses. An attempt is made to contact the first address in the list. If no response is received, the next address is tried, and so forth.
When deploying models, the session server contacts the management server for authentication and authorization. If you see the following errors when deploying a model, you may have an incorrect configuration in step 2 above.
[VHI 3852] Deployment of model failed: Cannot establish management session[VHI 3852] Deployment of model failed: Token binding is invalid