From c10d32f1c864a7abcf1b08b894e6912572d265c5 Mon Sep 17 00:00:00 2001 From: Stephen Finucane Date: Sun, 30 Oct 2016 13:29:51 +0000 Subject: [PATCH] doc: Convert OVSDB-replication to rST Signed-off-by: Stephen Finucane Signed-off-by: Russell Bryant --- Documentation/OVSDB-replication.md | 152 ------------------------ Documentation/OVSDB-replication.rst | 172 ++++++++++++++++++++++++++++ Documentation/automake.mk | 2 +- 3 files changed, 173 insertions(+), 153 deletions(-) delete mode 100644 Documentation/OVSDB-replication.md create mode 100644 Documentation/OVSDB-replication.rst diff --git a/Documentation/OVSDB-replication.md b/Documentation/OVSDB-replication.md deleted file mode 100644 index a9ab5cc4a4b..00000000000 --- a/Documentation/OVSDB-replication.md +++ /dev/null @@ -1,152 +0,0 @@ -OVSDB replication implementation --------------------------------- - -Overview -======== - -Given two Open vSwitch databases with the same schema, OVSDB -replication keeps these databases in the same state, i.e. each of the -databases have the same contents at any given time even if they are -not running in the same host. This document elaborates on the -implementation details to provide this functionality. - -Terminology -=========== - -- Source of truth database: database whose content will be replicated - to another database. - -- Active server: ovsdb-server providing RPC interface to the source of - truth database. - -- Standby server: ovsdb-server providing RPC interface to the database - that is not the source of truth. - -Design -====== - -The overall design of replication consists of one ovsdb-server (active server) -communicating the state of its databases to another ovsdb-server -(standby server) so that the latter keep its own databases in that same state. -To achieve this, the standby server acts as a client of the active -server, in the sense that it sends a monitor request to keep up to date with -the changes in the active server databases. When a notification from the -active server arrives, the standby server executes the necessary set of -operations so its databases reach the same state as the the active server -databases. Below is the design represented as a diagram. - - +--------------+ replication +--------------+ - | Active |<-------------------| Standby | - | OVSDB-server | | OVSDB-server | - +--------------+ +--------------+ - | | - | | - +-------+ +-------+ - | SoT | | | - | OVSDB | | OVSDB | - +-------+ +-------+ - -Setting up the replication -========================== - -To initiate the replication process, the standby server must be executed -indicating the location of the active server via the command line option -"--sync-from=server", where server can take any form described in the -ovsdb-client manpage and it must specify an active connection type (tcp, unix, -ssl). This option will cause the standby server to attempt to send a monitor -request to the active server in every main loop iteration, until the active -server responds. - -When sending a monitor request the standby server is doing the following: - -1. Erase the content of the databases for which it is providing a RPC -interface. - -2. Open the jsonrpc channel to communicate with the active server. - -3. Fetch all the databases located in the active server. - -4. For each database with the same schema in both the active and - standby servers: construct and send a monitor request message - specifying the tables that will be monitored (i.e all the tables on - the database except the ones blacklisted*). - -5. Set the standby database to the current state of the active - database. - -Once the monitor request message is sent, the standby server will continuously -receive notifications of changes occurring to the tables specified in the -request. The process of handling this notifications is detailed in the next -section. - -*A set of tables that will be excluded from replication can be -configure as a blacklist of tables via the command line option -"--sync-exclude-tables=db:table[,db:table]...", where db corresponds -to the database where the table resides. - -Replication process -=================== - -The replication process consists on handling the update notifications received -in the standby server caused by the monitor request that was previously sent to -the active server. In every loop iteration, the standby server attempts to -receive a message from the active server which can be an error, an echo -message (used to keep the connection alive) or an update notification. In case -the message is a fatal error, the standby server will disconnect from the -active without dropping the replicated data. If it is an echo message, the -standby server will reply with an echo message as well. If the message is an -update notification, the following process occurs: - -1. Create a new transaction. - -2. Get the \ object from the "params" member of the - notification. - -3. For each \ in the \ object do: - - 1. For each \ in \ check what kind of - operation should be executed according to the following criteria about - the presence of the object members: - - - If "old" member is not present, execute an insert operation - using \ from the "new" member. - - - If "old" member is present and "new" member is not present, - execute a delete operation using \ from the "old" - member - - - If both "old" and "new" members are present, execute an - update operation using \ from the "new" member. - -4. Commit the transaction. - -If an error occurs during the replication process, all replication is -restarted by resending a new monitor request as described in the section -"Setting up the replication". - - -Runtime management commands -=========================== - -Runtime management commands can be sent to a running standby server via -ovs-appctl in order to configure the replication functionality. The available -commands are the following. - -- ovsdb-server/set-remote-ovsdb-server {server}: sets the name of the active - server. - -- ovsdb-server/get-remote-ovsdb-server: gets the name of the active server - -- ovsdb-server/connect-remote-ovsdb-server: causes the server to attempt to - send a monitor request every main loop iteration. - -- ovsdb-server/disconnect-remote-ovsdb-server: closes the jsonrpc channel - between the active server and frees the memory used for the replication - configuration. - -- ovsdb-server/set-sync-exclude-tables {db:table,...}: sets the tables list - that will be excluded from being replicated. - -- ovsdb-server/get-sync-excluded-tables: gets the tables list that is - currently excluded from replication. - diff --git a/Documentation/OVSDB-replication.rst b/Documentation/OVSDB-replication.rst new file mode 100644 index 00000000000..fbf5a9bb25b --- /dev/null +++ b/Documentation/OVSDB-replication.rst @@ -0,0 +1,172 @@ +.. + Licensed 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. + + Convention for heading levels in Open vSwitch documentation: + + ======= Heading 0 (reserved for the title in a document) + ------- Heading 1 + ~~~~~~~ Heading 2 + +++++++ Heading 3 + ''''''' Heading 4 + + Avoid deeper levels because they do not render well. + +================================ +OVSDB Replication Implementation +================================ + +Given two Open vSwitch databases with the same schema, OVSDB replication keeps +these databases in the same state, i.e. each of the databases have the same +contents at any given time even if they are not running in the same host. This +document elaborates on the implementation details to provide this +functionality. + +Terminology +----------- + +Source of truth database + database whose content will be replicated to another database. + +Active server + ovsdb-server providing RPC interface to the source of truth database. + +Standby server + ovsdb-server providing RPC interface to the database that is not the source + of truth. + +Design +------ + +The overall design of replication consists of one ovsdb-server (active server) +communicating the state of its databases to another ovsdb-server (standby +server) so that the latter keep its own databases in that same state. To +achieve this, the standby server acts as a client of the active server, in the +sense that it sends a monitor request to keep up to date with the changes in +the active server databases. When a notification from the active server +arrives, the standby server executes the necessary set of operations so its +databases reach the same state as the the active server databases. Below is the +design represented as a diagram.:: + + +--------------+ replication +--------------+ + | Active |<-------------------| Standby | + | OVSDB-server | | OVSDB-server | + +--------------+ +--------------+ + | | + | | + +-------+ +-------+ + | SoT | | | + | OVSDB | | OVSDB | + +-------+ +-------+ + +Setting Up The Replication +-------------------------- + +To initiate the replication process, the standby server must be executed +indicating the location of the active server via the command line option +``--sync-from=server``, where server can take any form described in the +ovsdb-client manpage and it must specify an active connection type (tcp, unix, +ssl). This option will cause the standby server to attempt to send a monitor +request to the active server in every main loop iteration, until the active +server responds. + +When sending a monitor request the standby server is doing the following: + +1. Erase the content of the databases for which it is providing a RPC + interface. + +2. Open the jsonrpc channel to communicate with the active server. + +3. Fetch all the databases located in the active server. + +4. For each database with the same schema in both the active and standby + servers: construct and send a monitor request message specifying the tables + that will be monitored (i.e all the tables on the database except the ones + blacklisted [*]). + +5. Set the standby database to the current state of the active database. + +Once the monitor request message is sent, the standby server will continuously +receive notifications of changes occurring to the tables specified in the +request. The process of handling this notifications is detailed in the next +section. + +[*] A set of tables that will be excluded from replication can be configure as +a blacklist of tables via the command line option +``--sync-exclude-tables=db:table[,db:table]...``, where db corresponds to the +database where the table resides. + +Replication Process +------------------- + +The replication process consists on handling the update notifications received +in the standby server caused by the monitor request that was previously sent to +the active server. In every loop iteration, the standby server attempts to +receive a message from the active server which can be an error, an echo message +(used to keep the connection alive) or an update notification. In case the +message is a fatal error, the standby server will disconnect from the active +without dropping the replicated data. If it is an echo message, the standby +server will reply with an echo message as well. If the message is an update +notification, the following process occurs: + +1. Create a new transaction. + +2. Get the ```` object from the ``params`` member of the + notification. + +3. For each ```` in the ```` object do: + + 1. For each ```` in ```` check what kind of + operation should be executed according to the following criteria + about the presence of the object members: + + - If ``old`` member is not present, execute an insert operation using + ```` from the ``new`` member. + + - If ``old`` member is present and ``new`` member is not present, + execute a delete operation using ```` from the ``old`` member + + - If both ``old`` and ``new`` members are present, execute an update + operation using ```` from the ``new`` member. + +4. Commit the transaction. + + If an error occurs during the replication process, all replication is + restarted by resending a new monitor request as described in the section + "Setting up the replication". + +Runtime Management Commands +--------------------------- + +Runtime management commands can be sent to a running standby server via +ovs-appctl in order to configure the replication functionality. The available +commands are the following. + +``ovsdb-server/set-remote-ovsdb-server {server}`` + sets the name of the active server + +``ovsdb-server/get-remote-ovsdb-server`` + gets the name of the active server + +``ovsdb-server/connect-remote-ovsdb-server`` + causes the server to attempt to send a monitor request every main loop + iteration + +``ovsdb-server/disconnect-remote-ovsdb-server`` + closes the jsonrpc channel between the active server and frees the memory + used for the replication configuration. + +``ovsdb-server/set-sync-exclude-tables {db:table,...}`` + sets the tables list that will be excluded from being replicated + +``ovsdb-server/get-sync-excluded-tables`` + gets the tables list that is currently excluded from replication diff --git a/Documentation/automake.mk b/Documentation/automake.mk index d6849e84c4b..77c39f1d1a0 100644 --- a/Documentation/automake.mk +++ b/Documentation/automake.mk @@ -2,5 +2,5 @@ docs += \ Documentation/committer-responsibilities.rst \ Documentation/committer-grant-revocation.rst \ Documentation/group-selection-method-property.txt \ - Documentation/OVSDB-replication.md \ + Documentation/OVSDB-replication.rst \ Documentation/release-process.rst