Add Server Node
Note
A server node can be added at runtime without stopping the cache.
NCache cluster is dynamic and supports adding server nodes to a running cache cluster at runtime. When the new cache server to be added is started, it automatically joins the existing cache cluster. Cache clients that are already connected to the cache cluster up and running automatically connect with the new cache server if the caching topology requires it.
Topology specific behavior on adding a new cache server to a running cache cluster is described below.
Partitioned Cache
State Transfer:
State transfer in NCache means automatically moving or copying data from one cache server to another. In Partitioned cache, data is partitioned among the running cache servers. So when a new cache server joins the cluster, a new partition is automatically created and data distribution is changed accordingly. And then this cache server gets its share of data through state transfer. So, if there are 2 cache servers in the cluster and each cache server has 1GB of cache data in its partition then upon a new cache server joining the cluster and after the corresponding state transfer is completed, every cache server now holds approximately 600MB of data.
Client Connectivity:
In Partitioned cache, data is partitioned among all the running cache servers. Therefore cache clients are connected with every cache server so they can access all data in one hop. When a new cache server joins the cluster, the data distribution map changes and a new
HashMap
is generated. Then,HashMap
change event is raised and all running cache clients are notified through it. They then automatically establish connection with this new cache server and start sending requests to it as well.
Replicated Cache
State Transfer:
In Replicated Cache, each cache server holds the entire cache and therefore the same set of data. So when a new cache sever joins the cluster, it obtains another copy of the entire cache from existing cache servers through state transfer.
Client Connectivity:
In Replicated Cache, each client is connected to only one cache sever since it has the entire cache. Cache clients are load-balanced among all the running cache servers to equally distribute the request load to them. You can turn off load balancing of the clients in the client configuration file (client.ncconf) or by specifying
CacheInitParam.LoadBalance
flag to false inInitializeCache()
method.When a new cache server joins the cache cluster in Replicated Cache and if load-balancing is configured to be "true", then each of existing cache servers asks some of its clients to move to the newly joining cache server. In this way, the clients are rebalanced among all cache servers. If load-balancing is configured to be "false" then none of this happens and the clients stay connected to their previous cache servers.
A server node can be added to a clustered cache at any time.
Consider a cache named demoClusteredCache registered on two running servers i.e. 20.200.20.29 and 20.200.20.30, and a new node i.e 20.200.20.31 is to be added to the cache.
Configuration for Existing Nodes
Step 1: Add Server Node in config.ncconf
In config.ncconf of the existing nodes, add the configuration of the new
node under the <servers>
tag in <cache-deployment>
section.
In the example given below, the server nodes 20.200.20.29 and 20.200.20.30 already existed in the server node list in config.ncconf, and the information of the new server node <server-node ip="20.200.20.31"/>
is added in the server list.
The configuration file (config.ncconf) before adding the server node contains the ip addresses of two nodes as follows.
<cache-config cache-name="demoClusteredCache">
<cache-settings inproc="False">
...
<cache-deployment>
<servers>
<server-node ip="20.200.20.29" />
<server-node ip="20.200.20.30" />
</servers>
...
</cache-deployment>
</cache-settings>
</cache-config>
Whereas the configuration file (config.ncconf) after adding the server node contains the ip address of all three server nodes as follows.
<cache-config cache-name="demoClusteredCache">
<cache-settings inproc="False">
...
<cache-deployment>
<servers>
<server-node ip="20.200.20.29" />
<server-node ip="20.200.20.30" />
<server-node ip="20.200.20.31"/>
</servers>
...
</cache-deployment>
</cache-settings>
</cache-config>
Please note the following points before updating the configurations:
- The
cache-name
in the example used is demoClusteredCache. Make sure to change it to the cache name for which you want to add the server. - Replace the IP addresses given in
<cache-deployment>
section with the IP Addresses of your own cache servers. Note that the IP addresses must be the binded IPs.
Important
Make sure to add the configurations in config.ncconf of all pre existing server machines.
Step 2: Restart Cache (Optional)
In case the cache has critical data and is already running on the existing nodes, it is not necessary to restart the service on the existing nodes at this step. The cache will update the server list the next time NCache service will be restarted.
If the cache is not running or has no critical data and restarting the cache will not affect cache performance, restart the NCache service on the existing nodes so the configuration is updated accordingly on all the nodes.
Step 3: Add Server Node in client.ncconf
In client.ncconf of the same machines, update the information about server nodes under the <configuration>
tag. This is done because the client application reads client.ncconf in order to connect to the cache on the server(s) specified in this file.
Please refer to the Add Client to Cache section for more detail.
Important
Repeat this step on all existing server nodes.
Configuration for New Node
Step 4: Add Cache Configuration in config.ncconf
The updated cache configuration of the existing node needs to copied in config.ncconf of the new server node (20.200.20.31 in this case) for consistency of configuration on all nodes of the cluster.
<configuration>
<cache-config cache-name="demoClusteredCache">
<cache-settings inproc="False">
<logging enable-logs="True" trace-errors="True"
trace-notices="False" log-path=""/>
<performance-counters enable-counters="True"/>
<cache-notifications item-remove="False" item-add="False"
item-update="False"/>
<cleanup interval="15sec"/>
<storage type="heap" cache-size="1024mb"/>
<eviction-policy default-priority="normal"
eviction-ratio="5%"/>
<cache-topology topology="partitioned">
<cluster-settings operation-timeout="60sec"
stats-repl-interval="60sec"
use-heart-beat="False">
<cluster-connection-settings cluster-port="7806"
port-range="1" connection-retries="2"
connection-retry-interval="2secs"/>
</cluster-settings>
</cache-topology>
</cache-settings>
<cache-deployment>
<servers>
<server-node ip="20.200.20.29"/>
<server-node ip="20.200.20.30"/>
<server-node ip="20.200.20.31"/>
</servers>
</cache-deployment>
</cache-config>
</configuration>
Please note the following points before updating the configurations:
There might be other caches already registered on cache server. Please paste the following configuration under the
<configuration>
section so that this new<cache-config>
section is at the same level as of other sample caches shipped with setup.Make sure that the name of the cache is the same as the
cache-name
on the existing nodes.
Note
Please make sure that the cache-config
is the same as the cache-config
on the existing nodes.
Step 5: Restart NCache Service
For the configuration changes made to take effect, restart NCache Service using Windows PowerShell. Make sure you have enough privileges to restart the service. If the user is not the part of the Administrator's group, make sure to run Windows PowerShell as administrator, otherwise you might get an error message that "Cannot open ncachesvc service on computer".
Execute the following command to restart NCache Service:
Restart-Service -Name NCacheSvc
Step 6: Start Cache on New Node
Once cache creation has been verified, start the cache on each server through Windows PowerShell using the Start-Cache cmdlet.
Start-Cache -Name demoLocalCache
Step 7: Add Server Node in client.ncconf
In client.ncconf of the same machine, add the following description about cache under the <cache>
tag. This is done because the client application reads client.ncconf in order to connect to the cache on the server(s) specified in this file.
Please refer to the Add Client to Cache section for more detail.
Step 8: Verify Successful Addition of Node
In order to verify successful addition of the server node from the cache, open Windows PowerShell and use Get-Caches cmdlet with -Detail
parameter which displays all caches registered on the server and their respective servers along with additional information.
Get-Caches -Detail
If the node has been successfully added to the cache, the list will display the Cluster Size
for the cache along with all registered nodes. The node which has been added will exist in the list now. If it does not, there might have been some mistake while changing configuration or NCache Service may not have been restarted.
Important
Repeat this step for all server nodes.