CLOUDSTACK-5103 DB HA doc
diff --git a/en-US/db-ha.xml b/en-US/db-ha.xml new file mode 100644 index 0000000..ace1c10 --- /dev/null +++ b/en-US/db-ha.xml
@@ -0,0 +1,90 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent"> +%BOOK_ENTITIES; +]> + +<!-- 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. +--> + +<section id="db-ha"> + <title>Database High Availability</title> + <para>To help ensure high availability of the databases that store the internal data for &PRODUCT;, + you can set up database replication. + This covers both the main &PRODUCT; database and the Usage database. + Replication is achieved using the MySQL connector parameters and two-way replication. Tested with MySQL 5.1 and 5.5. + </para> + <section id="db-ha-howto"> + <title>How to Set Up Database Replication</title> + <para>Database replication in &PRODUCT; is provided using the MySQL replication capabilities. + The steps to set up replication can be found in the MySQL documentation (links are provided below). + It is suggested that you set up two-way replication, which involves two database nodes. + In this case, for example, you might have node1 and node2.</para> + <para>You can also set up chain replication, which involves more than two nodes. + In this case, you would first set up two-way replication with node1 and node2. + Next, set up one-way replication from node2 to node3. + Then set up one-way replication from node3 to node4, and so on for all the additional nodes.</para> + <para>References:</para> + <itemizedlist> + <listitem><para><ulink url="http://dev.mysql.com/doc/refman/5.0/en/replication-howto.html">http://dev.mysql.com/doc/refman/5.0/en/replication-howto.html</ulink></para></listitem> + <listitem><para><ulink url="https://wikis.oracle.com/display/CommSuite/MySQL+High+Availability+and+Replication+Information+For+Calendar+Server">https://wikis.oracle.com/display/CommSuite/MySQL+High+Availability+and+Replication+Information+For+Calendar+Server</ulink></para></listitem> + </itemizedlist> + </section> + <section id="db-ha-configure"> + <title>Configuring Database High Availability</title> + <para>To control the database high availability behavior, use the following configuration + settings in the file /etc/cloudstack/management/db.properties.</para> + <para><emphasis role="bold">Required Settings</emphasis></para> + <para>Be sure you have set the following in db.properties:</para> + <itemizedlist> + <listitem><para>db.ha.enabled: set to true if you want to use the replication feature.</para> + <para>Example: db.ha.enabled=true</para></listitem> + <listitem><para>db.cloud.slaves: set to a comma-delimited set of slave hosts for the cloud database. This is the list of nodes set up with replication. + The master node is not in the list, since it is already mentioned elsewhere in the properties file.</para> + <para>Example: db.cloud.slaves=node2,node3,node4</para></listitem> + <listitem><para>db.usage.slaves: set to a comma-delimited set of slave hosts for the usage database. This is the list of nodes set up with replication. + The master node is not in the list, since it is already mentioned elsewhere in the properties file.</para> + <para>Example: db.usage.slaves=node2,node3,node4</para></listitem> + </itemizedlist> + <para><emphasis role="bold">Optional Settings</emphasis></para> + <para>The following settings must be present in db.properties, but you are not required to change the default values unless you wish to do so for tuning purposes:</para> + <itemizedlist> + <listitem><para>db.cloud.secondsBeforeRetryMaster: The number of seconds the MySQL connector should wait before trying again to connect to the master + after the master went down. Default is 1 hour. + The retry might happen sooner if db.cloud.queriesBeforeRetryMaster is reached first.</para> + <para>Example: db.cloud.secondsBeforeRetryMaster=3600</para></listitem> + <listitem><para>db.cloud.queriesBeforeRetryMaster: The minimum number of queries to be sent to the database before trying again to connect to the master + after the master went down. Default is 5000. + The retry might happen sooner if db.cloud.secondsBeforeRetryMaster is reached first.</para> + <para>Example: db.cloud.queriesBeforeRetryMaster=5000</para></listitem> + <listitem><para>db.cloud.initialTimeout: Initial time the MySQL connector should wait before trying again to connect to the master. + Default is 3600.</para> + <para>Example: db.cloud.initialTimeout=3600</para></listitem> + </itemizedlist> + </section> + <section id="db-ha-limitations"> + <title>Limitations on Database High Availability</title> + <para>The following limitations exist in the current implementation of this feature.</para> + <itemizedlist> + <listitem><para>Slave hosts can not be monitored through &PRODUCT;. You will need to have a separate means of monitoring.</para></listitem> + <listitem><para>Events from the database side are not integrated with the &PRODUCT; Management Server events system.</para></listitem> + <listitem><para>You must periodically perform manual clean-up of bin log files generated by replication on database nodes. + If you do not clean up the log files, the disk can become full.</para></listitem> + </itemizedlist> + </section> +</section> \ No newline at end of file
diff --git a/en-US/sys-reliability-and-ha.xml b/en-US/sys-reliability-and-ha.xml index e3c1cd9..ecba7d9 100644 --- a/en-US/sys-reliability-and-ha.xml +++ b/en-US/sys-reliability-and-ha.xml
@@ -21,14 +21,16 @@ specific language governing permissions and limitations under the License. --> - <chapter id="sys-reliability-and-ha"> - <title>System Reliability and High Availability</title> - <xi:include href="ha-management-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="management-server-lb.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> - <xi:include href="ha-enabled-vm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="ha-for-hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="primary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="secondary-storage-outage-and-data-loss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <xi:include href="api-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <title>System Reliability and High Availability</title> + <xi:include href="ha-management-server.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="management-server-lb.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="ha-enabled-vm.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="ha-for-hosts.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="primary-storage-outage-and-data-loss.xml" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="secondary-storage-outage-and-data-loss.xml" + xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="db-ha.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> + <xi:include href="api-throttling.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> </chapter>