| // Licensed to the Apache Software Foundation (ASF) under one or more |
| // contributor license agreements. See the NOTICE file distributed with |
| // this work for additional information regarding copyright ownership. |
| // The ASF licenses this file to You under the Apache License, Version 2.0 |
| // (the "License"); you may not use this file except in compliance with |
| // the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| = Baseline Topology |
| |
| :javaFile: {javaCodeDir}/ClusterAPI.java |
| :csharpFile: {csharpCodeDir}/BaselineTopology.cs |
| |
| The _baseline topology_ is a set of nodes meant to hold data. |
| The concept of baseline topology was introduced to give you the ability to control when you want to |
| link:data-modeling/data-partitioning#rebalancing[rebalance the data in the cluster]. For example, if |
| you have a cluster of 3 nodes where the data is distributed between the nodes, and you add 2 more nodes, the rebalancing |
| process re-distributes the data between all 5 nodes. The rebalancing process happens when the |
| baseline topology changes, which can either happen automatically or be triggered manually. |
| |
| The baseline topology only includes server nodes; client nodes are never included because they do not store data. |
| |
| The purpose of the baseline topology is to: |
| |
| * Avoid unnecessary data transfer when a server node leaves the cluster for a short period of time, for example, due to |
| occasional network failures or scheduled server maintenance. |
| * Give you the ability to control when you want to rebalance the data. |
| |
| Baseline topology changes automatically when <<Baseline Topology Autoadjustment>> is enabled. This is the default |
| behavior for pure in-memory clusters. For persistent clusters, the baseline topology autoadjustment feature must be enabled |
| manually. By default, it is disabled and you have to change the baseline topology manually. You can change the baseline |
| topology using the link:control-script#activation-deactivation-and-topology-management[control script]. |
| |
| [CAUTION] |
| ==== |
| Any attempt to create a cache while the baseline topology is being changed results in an exception. |
| For more details, see link:key-value-api/basic-cache-operations#creating-caches-dynamically[Creating Caches Dynamically]. |
| ==== |
| |
| == Baseline Topology in Pure In-Memory Clusters |
| In pure in-memory clusters, the default behavior is to adjust the baseline topology to the set of all server nodes |
| automatically when you add or remove server nodes from the cluster. The data is rebalanced automatically, too. |
| You can disable the baseline autoadjustment feature and manage baseline topology manually. |
| |
| NOTE: In previous releases, baseline topology was relevant only to clusters with persistence. |
| However, since version 2.8.0, it applies to in-memory clusters as well. |
| If you have a pure in-memory cluster, the transition should be transparent for you because, by default, the baseline topology changes automatically when a server node leaves or joins the cluster. |
| |
| == Baseline Topology in Persistent Clusters |
| |
| If your cluster has at least one data region in which persistence is enabled, the cluster is inactive when you start it for the first time. |
| In the inactive state, all operations are prohibited. |
| The cluster must be activated before you can create caches and upload data. |
| Cluster activation sets the current set of server nodes as the baseline topology. |
| When you restart the cluster, it is activated automatically as soon as all nodes that are registered in the baseline topology join in. |
| However, if some nodes do not join after a restart, you must to activate the cluster manually. |
| |
| You can activate the cluster using one of the following tools: |
| |
| * link:control-script#activating-cluster[Control script] |
| * link:restapi#change-cluster-state[REST API command] |
| * Programmatically: |
| + |
| [tabs] |
| -- |
| tab:Java[] |
| |
| [source, java] |
| ---- |
| include::{javaFile}[tags=activate,indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| [source, csharp] |
| ---- |
| include::{csharpFile}[tags=activate,indent=0] |
| ---- |
| tab:C++[] |
| -- |
| |
| == Baseline Topology Autoadjustment |
| |
| Instead of changing the baseline topology manually, you can let the cluster do it automatically. This feature is called |
| Baseline Topology Autoadjustment. When it is enabled, the cluster monitors the state of its server nodes and sets the |
| baseline on the current topology automatically when the cluster topology is stable for a configurable period of time. |
| |
| Here is what happens when the set of nodes in the cluster changes: |
| |
| * The cluster waits for a configurable amount of time (5 min by default). |
| * If there are no other topology changes during this period, Ignite sets the baseline topology to the current set of nodes. |
| * If the set of nodes changes during this period, the timeout is updated. |
| |
| Each change in the set of nodes resets the timeout for autoadjustment. |
| When the timeout expires and the current set of nodes is different from the baseline topology (for example, new nodes |
| are present or some old nodes left), Ignite changes the baseline topology to the current set of nodes. |
| This also triggers data rebalancing. |
| |
| The autoadjustment timeout allows you to avoid data rebalancing when a node disconnects for a short period due to a |
| temporary network problem or when you want to quickly restart the node. |
| You can set the timeout to a higher value if you expect temporary changes in the set of nodes and don't want to change |
| the baseline topology. |
| |
| Baseline topology is autoadjusted only if the cluster is in the active state. |
| |
| To enable automatic baseline adjustment, you can use the |
| link:control-script#enabling-baseline-topology-autoadjustment[control script] or the |
| programmatic API methods shown below: |
| |
| [tabs] |
| -- |
| tab:Java[] |
| |
| [source, java] |
| ---- |
| include::{javaFile}[tags=enable-autoadjustment,indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| [source, csharp] |
| ---- |
| include::{csharpFile}[tags=enable-autoadjustment,indent=0] |
| ---- |
| tab:C++[] |
| -- |
| |
| |
| To disable automatic baseline adjustment, use the same method with `false` passed in: |
| |
| |
| [tabs] |
| -- |
| tab:Java[] |
| [source, java] |
| ---- |
| include::{javaFile}[tags=disable-autoadjustment,indent=0] |
| ---- |
| |
| tab:C#/.NET[] |
| [source, csharp] |
| ---- |
| include::{csharpFile}[tags=disable-autoadjustment,indent=0] |
| ---- |
| tab:C++[] |
| -- |
| |
| |
| == Monitoring Baseline Topology |
| |
| You can use the following tools to monitor and/or manage the baseline topology: |
| |
| * link:control-script[Control Script] |
| * link:monitoring-metrics/metrics#monitoring-topology[JMX Beans] |
| |