mirror of https://github.com/apache/cloudstack.git
CLOUDSTACK-815. Docs. Add new documentation for Regions. This feature currently is available through the API only.
This commit is contained in:
Jessica Tomechak
parent
ff63854b4d
commit
a0257bc533
|
|
@ -0,0 +1,49 @@
|
|||
<?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="about-regions">
|
||||
<title>About Regions</title>
|
||||
<para>To increase reliability of the cloud, you can optionally group resources into multiple geographic regions.
|
||||
A region is the largest available organizational unit within a &PRODUCT; deployment.
|
||||
A region is made up of several availability zones, where each zone is roughly equivalent to a datacenter.
|
||||
Each region is controlled by its own cluster of Management Servers, running in one of the zones.
|
||||
The zones in a region are typically located in close geographical proximity.
|
||||
Regions are a useful technique for providing fault tolerance and disaster recovery.</para>
|
||||
<para>By grouping zones into regions, the cloud can achieve higher availability and scalability.
|
||||
User accounts can span regions, so that users can deploy VMs in multiple, widely-dispersed regions.
|
||||
Even if one of the regions becomes unavailable, the services are still available to the end-user through VMs deployed in another region.
|
||||
And by grouping communities of zones under their own nearby Management Servers, the latency of communications within the cloud is reduced
|
||||
compared to managing widely-dispersed zones from a single central Management Server.
|
||||
</para>
|
||||
<para>
|
||||
Usage records can also be consolidated and tracked at the region level, creating reports or invoices for each geographic region.
|
||||
</para>
|
||||
<mediaobject>
|
||||
<imageobject>
|
||||
<imagedata fileref="./images/region-overview.png" />
|
||||
</imageobject>
|
||||
<textobject><phrase>region-overview.png: Nested structure of a region.</phrase></textobject>
|
||||
</mediaobject>
|
||||
<para>Regions are visible to the end user. When a user starts a guest VM, the user must select a region for their guest.
|
||||
Users might also be required to copy their private templates to additional regions to enable creation of guest VMs using their templates in those regions.</para>
|
||||
</section>
|
||||
|
|
@ -23,7 +23,12 @@
|
|||
-->
|
||||
<section id="about-zones">
|
||||
<title>About Zones</title>
|
||||
<para>A zone is the largest organizational unit within a &PRODUCT; deployment. A zone typically corresponds to a single datacenter, although it is permissible to have multiple zones in a datacenter. The benefit of organizing infrastructure into zones is to provide physical isolation and redundancy. For example, each zone can have its own power supply and network uplink, and the zones can be widely separated geographically (though this is not required).</para>
|
||||
<para>A zone is the second largest organizational unit within a &PRODUCT; deployment. A zone
|
||||
typically corresponds to a single datacenter, although it is permissible to have multiple
|
||||
zones in a datacenter. The benefit of organizing infrastructure into zones is to provide
|
||||
physical isolation and redundancy. For example, each zone can have its own power supply and
|
||||
network uplink, and the zones can be widely separated geographically (though this is not
|
||||
required).</para>
|
||||
<para>A zone consists of:</para>
|
||||
<itemizedlist>
|
||||
<listitem><para>One or more pods. Each pod contains one or more clusters of hosts and one or more primary storage servers.</para></listitem>
|
||||
|
|
@ -46,5 +51,6 @@
|
|||
<listitem><para>How many primary storage servers to place in each cluster and total capacity for the storage servers.</para></listitem>
|
||||
<listitem><para>How much secondary storage to deploy in a zone.</para></listitem>
|
||||
</itemizedlist>
|
||||
<para>When you add a new zone, you will be prompted to configure the zone’s physical network and add the first pod, cluster, host, primary storage, and secondary storage.</para>
|
||||
<para>When you add a new zone using the &PRODUCT; UI, you will be prompted to configure the zone’s physical network
|
||||
and add the first pod, cluster, host, primary storage, and secondary storage.</para>
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
under the License.
|
||||
-->
|
||||
<section id="added-API-commands-4.1">
|
||||
<title>Added API Commands in 4.1-incubating</title>
|
||||
<title>Added API Commands in 4.1</title>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>createEgressFirewallRules (creates an egress firewall rule on the guest network.)</para>
|
||||
|
|
@ -65,5 +65,10 @@
|
|||
<para>getUser (This API can only be used by the Admin. Get user details by using the API Key.)
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem><para>addRegion (Add a region)</para></listitem>
|
||||
<listitem><para>removeRegion (Delete a region)</para></listitem>
|
||||
<listitem><para>updateRegion (Modify attributes of a region)</para></listitem>
|
||||
<listitem><para>listRegions (List regions)</para></listitem>
|
||||
<listitem><para></para></listitem>
|
||||
</itemizedlist>
|
||||
</section>
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
under the License.
|
||||
-->
|
||||
<section id="changed-apicommands-4.1">
|
||||
<title>Changed API Commands in 4.1-incubating</title>
|
||||
<title>Changed API Commands in 4.1</title>
|
||||
<informaltable>
|
||||
<tgroup cols="2" align="left" colsep="1" rowsep="1">
|
||||
<colspec colwidth="1.0*" colname="1" colnum="1"/>
|
||||
|
|
@ -232,9 +232,21 @@
|
|||
<para>listZones</para>
|
||||
</entry>
|
||||
<entry>
|
||||
<para>The following request parameters is added: securitygroupenabled</para>
|
||||
<para>The following request parameter is added: securitygroupenabled</para>
|
||||
</entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><para>createAccount</para></entry>
|
||||
<entry><para>The following new request parameters are added: accountid, userid</para></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><para>createUser</para></entry>
|
||||
<entry><para>The following new request parameter is added: userid</para></entry>
|
||||
</row>
|
||||
<row>
|
||||
<entry><para>createDomain</para></entry>
|
||||
<entry><para>The following new request parameter is added: domainid</para></entry>
|
||||
</row>
|
||||
</tbody>
|
||||
</tgroup>
|
||||
</informaltable>
|
||||
|
|
|
|||
|
|
@ -23,7 +23,8 @@
|
|||
-->
|
||||
|
||||
<chapter id="cloud-infrastructure-concepts">
|
||||
<title>Cloud Infrastructure Concepts</title>
|
||||
<title>Cloud Infrastructure Concepts</title>
|
||||
<xi:include href="about-regions.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="about-zones.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="about-pods.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="about-clusters.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
|
|
|||
Binary file not shown.
|
After Width: | Height: | Size: 22 KiB |
|
|
@ -26,12 +26,13 @@
|
|||
<para>After the Management Server is installed and running, you can add the compute resources for it to manage. For an overview of how a &PRODUCT; cloud infrastructure is organized, see <xref linkend="cloud-infrastructure-overview" />.</para>
|
||||
<para>To provision the cloud infrastructure, or to scale it up at any time, follow these procedures:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Add a zone. See <xref linkend="zone-add" />.</para></listitem>
|
||||
<listitem><para>Add more pods (optional). See <xref linkend="pod-add" />.</para></listitem>
|
||||
<listitem><para>Add more clusters (optional). See <xref linkend="cluster-add" />.</para></listitem>
|
||||
<listitem><para>Add more hosts (optional). See <xref linkend="host-add" />.</para></listitem>
|
||||
<listitem><para>Add primary storage. See <xref linkend="primary-storage-add" />.</para></listitem>
|
||||
<listitem><para>Add secondary storage. See <xref linkend="secondary-storage-add" />.</para></listitem>
|
||||
<listitem><para>Define regions (optional). See <xref linkend="region-add"/>.</para></listitem>
|
||||
<listitem><para>Add a zone to the region. See <xref linkend="zone-add" />.</para></listitem>
|
||||
<listitem><para>Add more pods to the zone (optional). See <xref linkend="pod-add" />.</para></listitem>
|
||||
<listitem><para>Add more clusters to the pod (optional). See <xref linkend="cluster-add" />.</para></listitem>
|
||||
<listitem><para>Add more hosts to the cluster (optional). See <xref linkend="host-add" />.</para></listitem>
|
||||
<listitem><para>Add primary storage to the cluster. See <xref linkend="primary-storage-add" />.</para></listitem>
|
||||
<listitem><para>Add secondary storage to the zone. See <xref linkend="secondary-storage-add" />.</para></listitem>
|
||||
<listitem><para>Initialize and test the new cloud. See <xref linkend="initialize-and-test" />.</para></listitem>
|
||||
</orderedlist>
|
||||
<para>When you have finished these steps, you will have a deployment with the following basic structure:</para>
|
||||
|
|
|
|||
|
|
@ -23,8 +23,9 @@
|
|||
-->
|
||||
<chapter id="provisioning-steps">
|
||||
<title>Steps to Provisioning Your Cloud Infrastructure</title>
|
||||
<para>This section tells how to add zones, pods, clusters, hosts, storage, and networks to your cloud. If you are unfamiliar with these entities, please begin by looking through <xref linkend="cloud-infrastructure-concepts" />.</para>
|
||||
<para>This section tells how to add regions, zones, pods, clusters, hosts, storage, and networks to your cloud. If you are unfamiliar with these entities, please begin by looking through <xref linkend="cloud-infrastructure-concepts" />.</para>
|
||||
<xi:include href="provisioning-steps-overview.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="region-add.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="zone-add.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="pod-add.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
<xi:include href="cluster-add.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
|
||||
|
|
|
|||
|
|
@ -0,0 +1,128 @@
|
|||
<?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="region-add">
|
||||
<title>Adding Regions (optional)</title>
|
||||
<para>Grouping your cloud resources into geographic regions is an optional step when provisioning the cloud.
|
||||
For an overview of regions, see <xref linkend="about-regions"/>.</para>
|
||||
<section id="region-first">
|
||||
<title>The First Region: The Default Region</title>
|
||||
<para>If you do not take action to define regions, then all the zones in your cloud will be
|
||||
automatically grouped into a single default region. This region is assigned the region
|
||||
ID of 1.</para>
|
||||
<para>You can change the name or URL of the default region by using the API command updateRegion. For example:</para>
|
||||
<programlisting>http://<IP_of_Management_Server>:8080/client/api?command=updateRegion&id=1&name=Northern&endpoint=http://<region_1_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting>
|
||||
</section>
|
||||
<section id="region-add-2">
|
||||
<title>Adding a Region</title>
|
||||
<para>Use these steps to add a second region in addition to the default region.</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Each region has its own &PRODUCT; instance. Therefore, the first step of creating a new region
|
||||
is to install the Management Server software, on one or more nodes, in the
|
||||
geographic area where you want to set up the new region. Use the steps in the
|
||||
Installation guide. When you come to the step where you set up the database, use
|
||||
the additional command-line flag <code>-r <region_id></code> to set a
|
||||
region ID for the new region. The default region is automatically assigned a
|
||||
region ID of 1, so your first additional region might be region 2.</para>
|
||||
<programlisting>cloud-setup-databases cloud:<dbpassword>@localhost --deploy-as=root:<password> -e <encryption_type> -m <management_server_key> -k <database_key> -r <region_id></programlisting>
|
||||
</listitem>
|
||||
<listitem><para>By the end of the installation procedure, the Management Server should have been started. Be sure that the Management Server installation was successful and complete.</para></listitem>
|
||||
<listitem><para>Add region 2 to region 1. Use the API command addRegion. (For information about how to make an API call, see the Developer's Guide.)</para>
|
||||
<programlisting>http://<IP_of_region_1_Management_Server>:8080/client/api?command=addRegion&id=2&name=Western&endpoint=http://<region_2_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Now perform the same command in reverse, adding region 1 to region 2.</para>
|
||||
<programlisting>http://<IP_of_region_2_Management_Server>:8080/client/api?command=addRegion&id=2&name=Western&endpoint=http://<region_1_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Copy the account, user, and domain tables from the region 1 database to the region 2 database.</para>
|
||||
<para>In the following commands, it is assumed that you have set the root password on the
|
||||
database, which is a &PRODUCT; recommended best practice. Substitute your own MySQL
|
||||
root password.</para>
|
||||
<orderedlist numeration="loweralpha">
|
||||
<listitem><para>First, run this command to copy the contents of the database:</para>
|
||||
<programlisting># mysqldump -u root -p<mysql_password> -h <region1_db_host> cloud account user domain > region1.sql</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Then run this command to put the data onto the region 2 database:</para>
|
||||
<programlisting># mysql -u root -p<mysql_password> -h <region2_db_host> cloud < region1.sql</programlisting>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
<listitem><para>Remove project accounts. Run these commands on the region 2 database:</para>
|
||||
<programlisting>mysql> delete from account where type = 5;</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Set the default zone as null:</para>
|
||||
<programlisting>mysql> update account set default_zone_id = null;</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Restart the Management Servers in region 2.</para></listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
<section id="region-add-n">
|
||||
<title>Adding Third and Subsequent Regions</title>
|
||||
<para>To add the third region, and subsequent additional regions, the steps are similar to those for adding the second region.
|
||||
However, you must repeat certain steps additional times for each additional region:</para>
|
||||
<orderedlist>
|
||||
<listitem><para>Install &PRODUCT; in each additional region. Set the region ID for each region during the database setup step.</para>
|
||||
<programlisting>cloud-setup-databases cloud:<dbpassword>@localhost --deploy-as=root:<password> -e <encryption_type> -m <management_server_key> -k <database_key> -r <region_id></programlisting></listitem>
|
||||
<listitem><para>Once the Management Server is running, add your new region to all existing regions by
|
||||
repeatedly calling the API command addRegion. For example, if you were adding
|
||||
region 3:</para>
|
||||
<programlisting>http://<IP_of_region_1_Management_Server>:8080/client/api?command=addRegion&id=3&name=Eastern&endpoint=http://<region_3_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
|
||||
|
||||
http://<IP_of_region_2_Management_Server>:8080/client/api?command=addRegion&id=3&name=Eastern&endpoint=http://<region_3_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting></listitem>
|
||||
<listitem><para>Repeat the procedure in reverse to add all existing regions to the new region. For example,
|
||||
for the third region, add the other two existing regions:</para>
|
||||
<programlisting>http://<IP_of_region_3_Management_Server>:8080/client/api?command=addRegion&id=1&name=Northern&endpoint=http://<region_1_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
|
||||
|
||||
http://<IP_of_region_3_Management_Server>:8080/client/api?command=addRegion&id=2&name=Western&endpoint=http://<region_2_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting></listitem>
|
||||
<listitem><para>Copy the account, user, and domain tables from any existing region's database to the new
|
||||
region's database.</para>
|
||||
<para>In the following commands, it is assumed that you have set the root password on the
|
||||
database, which is a &PRODUCT; recommended best practice. Substitute your own MySQL
|
||||
root password.</para>
|
||||
<orderedlist numeration="loweralpha">
|
||||
<listitem><para>First, run this command to copy the contents of the database:</para>
|
||||
<programlisting># mysqldump -u root -p<mysql_password> -h <region1_db_host> cloud account user domain > region1.sql</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Then run this command to put the data onto the new region's database. For example, for region
|
||||
3:</para>
|
||||
<programlisting># mysql -u root -p<mysql_password> -h <region3_db_host> cloud < region1.sql</programlisting>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
<listitem><para>Remove project accounts. Run these commands on the region 2 database:</para>
|
||||
<programlisting>mysql> delete from account where type = 5;</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Set the default zone as null:</para>
|
||||
<programlisting>mysql> update account set default_zone_id = null;</programlisting>
|
||||
</listitem>
|
||||
<listitem><para>Restart the Management Servers in the new region.</para></listitem>
|
||||
</orderedlist>
|
||||
</section>
|
||||
<section id="region-delete">
|
||||
<title>Deleting a Region</title>
|
||||
<para>To delete a region, use the API command removeRegion. Repeat the call to remove the region from all other regions. For example, to remove the 3rd region in a three-region cloud:</para>
|
||||
<programlisting>http://<IP_of_region_1_Management_Server>:8080/client/api?command=removeRegion&id=3&name=Eastern&endpoint=http://<region_3_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
|
||||
|
||||
http://<IP_of_region_2_Management_Server>:8080/client/api?command=removeRegion&id=3&name=Eastern&endpoint=http://<region_3_IP_address_here>:8080/client&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D</programlisting>
|
||||
</section>
|
||||
</section>
|
||||
Loading…
Reference in New Issue