List of operations in the Cluster Web Service

The Cluster Web Service contains operations for creating the node profile and managing nodes in the Endeca Server cluster. It also contains operations for defining and managing data domain profiles, and for checking the status of the cluster and data domains.

Operation description

Use the Cluster Web Service to:
  • Define a node profile. The node profile provides the underlying hardware characteristics for the Endeca Server nodes. The Endeca Server cluster uses the node profile at deployment time for all its nodes, to allocate hardware to nodes on which the data domains will reside.
  • Define data domain profiles. Data domain profiles are templates for different kinds of data domains; before you add data domains to the Endeca Server cluster, data domain profiles must be created.

After you install and deploy Endeca Server nodes, you can configure Endeca Server node profiles and data domain profiles. Next, use the Manage Web Service to add and manage data domains that will be hosted by the Endeca Server nodes and will use defined data domain profiles.

Request

The input to the Cluster Web Service depends on the element in its request. For example:
  • To configure a node profile, use the setNodeProfile element, specifying the number of CPUs and the amount of available RAM.
  • To list Endeca Server nodes, use the listNodes element (no parameters are required for this operation).
Other operations are discussed in the list of operations in this topic.

Response

Depending on the success of the request, the Cluster Web Service returns:
  • If there are no problems and the response was successful, an empty response element is returned (except for listNodes and listDataDomainProfiles operations, which return information).
  • The request returns a SOAP fault, in the instances including the following: a data domain with the specified name already exists, the data domain profile is not defined in the Endeca Server cluster, or the Endeca Server cluster has insufficient resources to accommodate the request.

List of operations

The Cluster Web Service lets you perform the following operations, where operations are represented by elements in the request:

Request element Description
setNodeProfile Define the custom node profile. The custom node profile lets you set the hardware characteristics for all Endeca Server cluster nodes, specifying the number of CPUs and the amount of available RAM. If the custom node profile does not exist, the default node profile is used by the Endeca Server cluster when it adds new nodes. You can use the setNodeProfile operation at any time when deploying new Endeca Server nodes in the cluster, for example, after the first Endeca Server node has been deployed based on the default node profile.

Once you set a custom node profile, when you deploy new Endeca Server nodes in the cluster, this profile will be used for all Endeca Server nodes, including the current node.

It is recommended to configure the custom node profile before creating data domain profiles and data domains (this is because they rely on the capacity of the Endeca Server cluster nodes determined by the node profile). Also, if you change the node profile after the data domains have been created, this may affect the data domains.

To define a custom node profile, specify:
  • numCpuCores
  • ramSizeMB
getNodeProfile Return the hardware profile of nodes in the Endeca Server cluster as set by setNodeProfile. The request returns the number of CPUs and the amount of available RAM. This operation does not have any arguments.
deleteNode Remove a node from the Endeca Server cluster, specifying its hostname.

If the node you are attempting to delete is hosting data domains, the Endeca Server cluster attempts to migrate the data domains to other nodes, if the cluster has enough resources for this operation.

The request returns a fault if the specified node does not exist in the cluster, or if the data domains hosted on the node cannot be migrated to other nodes due to insufficient resources in the Endeca Server cluster.

listNodes Return a list containing the hostname and port of each node in the cluster. This operation does not require any arguments.
putDataDomainProfile Configure a new data domain profile, which defines resources available to a data domain when it is created. Specify these values:
  • name and description are the name and description of the data domain profile.
  • allowQueriesOnLeader indicates whether the leader node should share query requests with follower nodes (if set to true), or should be dedicated exclusively to handling update queries (if set to false). The default is true.
  • numFollowers is the number of follower Dgraph nodes to handle query load. The default is 0. When allowQueriesOnLeader is set to false, numFollowers must be equal to or greater than one.
  • allowOversubscribe indicates whether the Endeca Server cluster can exceed its capacity while sharing nodes hosting this data domain with other data domains (if set to true), or should share its resources only within its capacity (if set to false). The default is true.
  • numComputeThreads is the number of threads to allocate for processing requests on each Dgraph node in the data domain using this profile. If no value is specified or 0 is specified, this defaults to the larger of 2 or the number of available processors.
  • computeCacheSizeMB is the amount of RAM, in MB, to allocate to the result cache on each Dgraph node. If no value is specified or 0 is specified, this defaults to the Dgraph default cache size computed as 10% of the amount of RAM available on the Endeca Server node hosting the Dgraph node.
  • startupTimeoutSeconds is the time, in seconds, to allow for the Dgraph process to start up. The default is 600 seconds. shutdownTimeoutSeconds is the time, in seconds, to allow for the Dgraph process to shut down. The default is 30 seconds.
  • sessionIdType is the method used for establishing session affinity when routing requests to the data domain. The default is HEADER. The value is not case-sensitive. sessionIdKey is the name of the object checked by the sessionIdType session affinity method. The default is X-Endeca-Session-ID.
  • readOnly. Indicates whether the data domain should process only read requests to its index. The default is false.
  • args (Optional). The list of Dgraph flags, on each data domain node. For a list, see the Oracle Endeca Server Administrator's Guide.
getDataDomainProfile Return the data domain profile with the specified name. The request returns the same information as specified with putDataDomainProfile.
deleteDataDomainProfile Remove a specified data domain profile from the Endeca Server.
listDataDomainProfiles Return a list of all defined data domain profiles containing the same information as specified with putDataDomainProfile.
getClusterHealth Return the Endeca Server nodes and their status, the host names and ports of the nodes running the Cluster Coordinator and their status, and the data domains and their status.
getDataDomainHealth Return the health of the data domain with the specified name, and list the status of the Dgraph nodes in the data domain.
getNodeHealth Return the Endeca Server node's host name and port and the status of the node. Additionally, it lists the status of the Dgraph nodes hosted on this Endeca Server node (these Dgraph nodes belong to different data domain clusters).

Requires you to specify the host name of the node.

usage Return a list of flags for the Dgraph process. These flags could be used as values in args element of the putDataDomainProfile operation.

Example of a request to the Cluster Web Service

The following examples show the Cluster Web Service request and response for the getDataDomainHealth operation.

This abbreviated example shows the request for the health of the data domain test2:
<ns1:getDataDomainHealth xmlns:ns1="http://www.endeca.com/endeca-server/cluster/1/0">
            <ns1:name>test2</ns1:name>
        </ns1:getDataDomainHealth>
Note: This documentation is complemented by the API reference. For reference information about the elements and types used in the Cluster Web Service, see the Cluster Web Service API Reference in the Oracle Endeca Server API Reference.