7 Clustering is a mechanism that enables multiple processes and programs to work
8 together as one entity. For example, when you search for something on
9 google.com, it may seem like your search request is processed by only one web
10 server. In reality, your search request is processed by may web servers
11 connected in a cluster. Similarly, you can have multiple instances of
12 OpenDaylight working together as one entity.
14 Advantages of clustering are:
16 * Scaling: If you have multiple instances of OpenDaylight running, you can
17 potentially do more work and store more data than you could with only one
18 instance. You can also break up your data into smaller chunks (shards) and
19 either distribute that data across the cluster or perform certain operations
20 on certain members of the cluster.
21 * High Availability: If you have multiple instances of OpenDaylight running and
22 one of them crashes, you will still have the other instances working and
24 * Data Persistence: You will not lose any data stored in OpenDaylight after a
25 manual restart or a crash.
27 The following sections describe how to set up clustering on both individual and
28 multiple OpenDaylight instances.
30 Multiple Node Clustering
31 ------------------------
33 The following sections describe how to set up multiple node clusters in OpenDaylight.
35 Deployment Considerations
36 ^^^^^^^^^^^^^^^^^^^^^^^^^
38 To implement clustering, the deployment considerations are as follows:
40 * To set up a cluster with multiple nodes, we recommend that you use a minimum
41 of three machines. You can set up a cluster with just two nodes. However, if
42 one of the two nodes fail, the cluster will not be operational.
44 .. note:: This is because clustering in OpenDaylight requires a majority of the
45 nodes to be up and one node cannot be a majority of two nodes.
47 * Every device that belongs to a cluster needs to have an identifier.
48 OpenDaylight uses the node's ``role`` for this purpose. After you define the
49 first node's role as *member-1* in the ``akka.conf`` file, OpenDaylight uses
50 *member-1* to identify that node.
52 * Data shards are used to contain all or a certain segment of a OpenDaylight's
53 MD-SAL datastore. For example, one shard can contain all the inventory data
54 while another shard contains all of the topology data.
56 If you do not specify a module in the ``modules.conf`` file and do not specify
57 a shard in ``module-shards.conf``, then (by default) all the data is placed in
58 the default shard (which must also be defined in ``module-shards.conf`` file).
59 Each shard has replicas configured. You can specify the details of where the
60 replicas reside in ``module-shards.conf`` file.
62 * If you have a three node cluster and would like to be able to tolerate any
63 single node crashing, a replica of every defined data shard must be running
64 on all three cluster nodes.
66 .. note:: This is because OpenDaylight's clustering implementation requires a
67 majority of the defined shard replicas to be running in order to
68 function. If you define data shard replicas on two of the cluster nodes
69 and one of those nodes goes down, the corresponding data shards will not
72 * If you have a three node cluster and have defined replicas for a data shard
73 on each of those nodes, that shard will still function even if only two of
74 the cluster nodes are running. Note that if one of those remaining two nodes
75 goes down, the shard will not be operational.
77 * It is recommended that you have multiple seed nodes configured. After a
78 cluster member is started, it sends a message to all of its seed nodes.
79 The cluster member then sends a join command to the first seed node that
80 responds. If none of its seed nodes reply, the cluster member repeats this
81 process until it successfully establishes a connection or it is shut down.
83 * After a node is unreachable, it remains down for configurable period of time
84 (10 seconds, by default). Once a node goes down, you need to restart it so
85 that it can rejoin the cluster. Once a restarted node joins a cluster, it
86 will synchronize with the lead node automatically.
88 Setting Up a Multiple Node Cluster
89 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
91 To run OpenDaylight in a three node cluster, perform the following:
93 First, determine the three machines that will make up the cluster. After that,
94 do the following on each machine:
96 #. Copy the OpenDaylight distribution zip file to the machine.
97 #. Unzip the distribution.
98 #. Open the following .conf files:
100 * configuration/initial/akka.conf
101 * configuration/initial/module-shards.conf
103 #. In each configuration file, make the following changes:
105 Find every instance of the following lines and replace _127.0.0.1_ with the
106 hostname or IP address of the machine on which this file resides and
107 OpenDaylight will run::
110 hostname = "127.0.0.1"
112 .. note:: The value you need to specify will be different for each node in the
115 #. Find the following lines and replace _127.0.0.1_ with the hostname or IP
116 address of any of the machines that will be part of the cluster::
119 seed-nodes = ["akka.tcp://opendaylight-cluster-data@127.0.0.1:2550"]
121 #. Find the following section and specify the role for each member node. Here
122 we assign the first node with the *member-1* role, the second node with the
123 *member-2* role, and the third node with the *member-3* role::
129 .. note:: This step should use a different role on each node.
131 #. Open the configuration/initial/module-shards.conf file and update the
132 replicas so that each shard is replicated to all three nodes::
140 For reference, view a sample config files <<_sample_config_files,below>>.
142 #. Move into the +<karaf-distribution-directory>/bin+ directory.
143 #. Run the following command::
145 JAVA_MAX_MEM=4G JAVA_MAX_PERM_MEM=512m ./karaf
147 #. Enable clustering by running the following command at the Karaf command line::
149 feature:install odl-mdsal-clustering
151 OpenDaylight should now be running in a three node cluster. You can use any of
152 the three member nodes to access the data residing in the datastore.
157 Sample ``akka.conf`` file::
161 mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
162 mailbox-capacity = 1000
163 mailbox-push-timeout-time = 100ms
166 metric-capture-enabled = true
170 loggers = ["akka.event.slf4j.Slf4jLogger"]
174 provider = "akka.cluster.ClusterActorRefProvider"
176 java = "akka.serialization.JavaSerializer"
177 proto = "akka.remote.serialization.ProtobufSerializer"
180 serialization-bindings {
181 "com.google.protobuf.Message" = proto
186 log-remote-lifecycle-events = off
188 hostname = "10.194.189.96"
190 maximum-frame-size = 419430400
191 send-buffer-size = 52428800
192 receive-buffer-size = 52428800
197 seed-nodes = ["akka.tcp://opendaylight-cluster-data@10.194.189.96:2550"]
199 auto-down-unreachable-after = 10s
211 mailbox-type = "org.opendaylight.controller.cluster.common.actor.MeteredBoundedMailbox"
212 mailbox-capacity = 1000
213 mailbox-push-timeout-time = 100ms
216 metric-capture-enabled = true
220 loggers = ["akka.event.slf4j.Slf4jLogger"]
223 provider = "akka.cluster.ClusterActorRefProvider"
227 log-remote-lifecycle-events = off
229 hostname = "10.194.189.96"
235 seed-nodes = ["akka.tcp://opendaylight-cluster-rpc@10.194.189.96:2551"]
237 auto-down-unreachable-after = 10s
242 Sample ``module-shards.conf`` file::