apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Baseline Topology
16

17
:javaFile: {javaCodeDir}/ClusterAPI.java
18
:csharpFile: {csharpCodeDir}/BaselineTopology.cs
19

20
The _baseline topology_ is a set of nodes meant to hold data.
21
The concept of baseline topology was introduced to give you the ability to control when you want to
22
link:data-modeling/data-partitioning#rebalancing[rebalance the data in the cluster]. For example, if
23
you have a cluster of 3 nodes where the data is distributed between the nodes, and you add 2 more nodes, the rebalancing
24
process re-distributes the data between all 5 nodes. The rebalancing process happens when the
25
baseline topology changes, which can either happen automatically or be triggered manually.
26

27
The baseline topology only includes server nodes; client nodes are never included because they do not store data.
28

29
The purpose of the baseline topology is to:
30

31
* Avoid unnecessary data transfer when a server node leaves the cluster for a short period of time, for example, due to
32
occasional network failures or scheduled server maintenance.
33
* Give you the ability to control when you want to rebalance the data.
34

35
Baseline topology changes automatically when <<Baseline Topology Autoadjustment>> is enabled. This is the default
36
behavior for pure in-memory clusters. For persistent clusters, the baseline topology autoadjustment feature must be enabled
37
manually. By default, it is disabled and you have to change the baseline topology manually. You can change the baseline
38
topology using the link:tools/control-script#activation-deactivation-and-topology-management[control script].
39

40
[CAUTION]
41
====
42
Any attempt to create a cache while the baseline topology is being changed results in an exception.
43
For more details, see link:key-value-api/basic-cache-operations#creating-caches-dynamically[Creating Caches Dynamically].
44
====
45

46
== Baseline Topology in Pure In-Memory Clusters
47
In pure in-memory clusters, the default behavior is to adjust the baseline topology to the set of all server nodes
48
automatically when you add or remove server nodes from the cluster. The data is rebalanced automatically, too.
49
You can disable the baseline autoadjustment feature and manage baseline topology manually.
50

51
NOTE: In previous releases, baseline topology was relevant only to clusters with persistence.
52
However, since version 2.8.0, it applies to in-memory clusters as well.
53
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.
54

55
== Baseline Topology in Persistent Clusters
56

57
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.
58
In the inactive state, all operations are prohibited.
59
The cluster must be activated before you can create caches and upload data.
60
Cluster activation sets the current set of server nodes as the baseline topology.
61
When you restart the cluster, it is activated automatically as soon as all nodes that are registered in the baseline topology join in.
62
However, if some nodes do not join after a restart, you must to activate the cluster manually.
63

64
You can activate the cluster using one of the following tools:
65

66
* link:tools/control-script#activating-cluster[Control script]
67
* link:restapi#change-cluster-state[REST API command]
68
* Programmatically:
69
+
70
[tabs]
71
--
72
tab:Java[]
73

74
[source, java]
75
----
76
include::{javaFile}[tags=activate,indent=0]
77
----
78

79
tab:C#/.NET[]
80
[source, csharp]
81
----
82
include::{csharpFile}[tags=activate,indent=0]
83
----
84
tab:C++[]
85
--
86

87
== Baseline Topology Autoadjustment
88

89
Instead of changing the baseline topology manually, you can let the cluster do it automatically. This feature is called
90
Baseline Topology Autoadjustment. When it is enabled, the cluster monitors the state of its server nodes and sets the
91
baseline on the current topology automatically when the cluster topology is stable for a configurable period of time.
92

93
Here is what happens when the set of nodes in the cluster changes:
94

95
* The cluster waits for a configurable amount of time (5 min by default).
96
* If there are no other topology changes during this period, Ignite sets the baseline topology to the current set of nodes.
97
* If the set of nodes changes during this period, the timeout is updated.
98

99
Each change in the set of nodes resets the timeout for autoadjustment.
100
When the timeout expires and the current set of nodes is different from the baseline topology (for example, new nodes
101
are present or some old nodes left), Ignite changes the baseline topology to the current set of nodes.
102
This also triggers data rebalancing.
103

104
The autoadjustment timeout allows you to avoid data rebalancing when a node disconnects for a short period due to a
105
temporary network problem or when you want to quickly restart the node.
106
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
107
the baseline topology.
108

109
Baseline topology is autoadjusted only if the cluster is in the active state.
110

111
To enable automatic baseline adjustment, you can use the
112
link:tools/control-script#enabling-baseline-topology-autoadjustment[control script] or the
113
programmatic API methods shown below:
114

115
[tabs]
116
--
117
tab:Java[]
118

119
[source, java]
120
----
121
include::{javaFile}[tags=enable-autoadjustment,indent=0]
122
----
123

124
tab:C#/.NET[]
125
[source, csharp]
126
----
127
include::{csharpFile}[tags=enable-autoadjustment,indent=0]
128
----
129
tab:C++[]
130
--
131

132

133
To disable automatic baseline adjustment, use the same method with `false` passed in:
134

135

136
[tabs]
137
--
138
tab:Java[]
139
[source, java]
140
----
141
include::{javaFile}[tags=disable-autoadjustment,indent=0]
142
----
143

144
tab:C#/.NET[]
145
[source, csharp]
146
----
147
include::{csharpFile}[tags=disable-autoadjustment,indent=0]
148
----
149
tab:C++[]
150
--
151

152

153
== Monitoring Baseline Topology
154

155
You can use the following tools to monitor and/or manage the baseline topology:
156

157
* link:tools/control-script[Control Script]
158
* link:monitoring-metrics/metrics#monitoring-topology[JMX Beans]
159

160