You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cloudstack.apache.org by se...@apache.org on 2014/05/28 19:13:26 UTC
[1/4] fixed the formatting in all the files and added the license to
each file: This closes #4
Repository: cloudstack-docs
Updated Branches:
refs/heads/master 4629e0298 -> e55976f35
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/plugins.rst
----------------------------------------------------------------------
diff --git a/rtd/source/plugins.rst b/rtd/source/plugins.rst
index 6e365a1..56f0259 100644
--- a/rtd/source/plugins.rst
+++ b/rtd/source/plugins.rst
@@ -1,7 +1,22 @@
+.. 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.
+
+
Plugins
=======
-
Storage Plugins
---------------
@@ -40,13 +55,14 @@ provider is selected, additional input fields may appear so that the
user can provide the additional details required by that provider, such
as a user name and password for a third-party storage account.
+
Overview of How to Write a Storage Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To add a third-party storage option to CloudStack, follow these general
steps (explained in more detail later in this section):
-1. Implement the following interfaces in Java:
+#. Implement the following interfaces in Java:
- DataStoreDriver
@@ -57,14 +73,16 @@ steps (explained in more detail later in this section):
- VMSnapshotStrategy (if you want to customize the VM snapshot
functionality)
-2. Hardcode your plugin's required additional input fields into the code
+#. Hardcode your plugin's required additional input fields into the code
for the Add Secondary Storage or Add Primary Storage dialog box.
-3. Place your .jar file in `plugins/storage/volume/` or `plugins/storage/image/`.
+#. Place your .jar file in `plugins/storage/volume/` or
+ `plugins/storage/image/`.
-4. Edit `/client/tomcatconf/componentContext.xml.in`.
+#. Edit `/client/tomcatconf/componentContext.xml.in`.
+
+#. Edit `client/pom.xml`.
-5. Edit `client/pom.xml`.
Implementing DataStoreDriver
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -89,6 +107,7 @@ The following methods are optional:
- canCopy() is optional. If you set it to true, then you must implement
copyAsync().
+
Implementing DataStoreLifecycle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -107,8 +126,8 @@ You must implement the following methods:
- deleteDataStore()
- Implement one of the attach\*() methods depending on what scope you
- want the storage to have: attachHost(), attachCluster(), or
- attachZone().
+ want the storage to have: attachHost(), attachCluster(), or attachZone().
+
Implementing DataStoreProvider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -134,8 +153,8 @@ You must implement the following methods:
The following methods are optional:
-- getHostListener() is optional; it's for monitoring the status of the
- host.
+- getHostListener() is optional; it's for monitoring the status of the host.
+
Implementing VMSnapshotStrategy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -151,6 +170,7 @@ VMSnapshotStrategy has the following methods:
- canHandle(). For a given VM snapshot, tells whether this
implementation of VMSnapshotStrategy can handle it.
+
Place the .jar File in the Right Directory
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -158,13 +178,14 @@ For a secondary storage plugin, place your .jar file here:
::
- plugins/storage/image/
+ plugins/storage/image/
For a primary storage plugin, place your .jar file here:
::
- plugins/storage/volume/
+ plugins/storage/volume/
+
Edit Configuration Files
~~~~~~~~~~~~~~~~~~~~~~~~
@@ -175,29 +196,30 @@ now has a dependency on your code:
::
- client/pom.xml
+ client/pom.xml
Place some facts about your code in the following file so CloudStack can
run it:
::
- /client/tomcatconf/componentContext.xml.in
+ /client/tomcatconf/componentContext.xml.in
In the section “Deployment configurations of various adapters,” add
this:
::
- <bean>id=”some unique ID” class=”package name of your implementation of DataStoreProvider”</bean>
+ <bean>id=”some unique ID” class=”package name of your implementation of DataStoreProvider”</bean>
In the section “Storage Providers,” add this:
::
- <property name=”providers”>
- <ref local=”same ID from the bean tag's id attribute”>
- </property>
+ <property name=”providers”>
+ <ref local=”same ID from the bean tag's id attribute”>
+ </property>
+
Minimum Required Interfaces
~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -207,6 +229,7 @@ Services (AWS) Java SDK are listed in this section. An object storage
that supports the S3 interface is minimally required to support the
below in order to be compatible with CloudStack.
+
Interface AmazonS3
^^^^^^^^^^^^^^^^^^
@@ -322,18 +345,19 @@ time after CloudStack installation. The new plugin appears only when it is
enabled by the cloud administrator.
.. figure:: /_static/images/plugin_intro.jpg
- :align: center
- :alt: New plugin button in CloudStack navbar
+ :align: center
+ :alt: New plugin button in CloudStack navbar
The left navigation bar of the CloudStack UI has a new Plugins button to
help you work with UI plugins.
+
How to Write a Plugin: Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The basic procedure for writing a plugin is:
-1. Write the code and create the other files needed. You will need the
+#. Write the code and create the other files needed. You will need the
plugin code itself (in Javascript), a thumbnail image, the plugin
listing, and a CSS file.
@@ -345,40 +369,41 @@ The basic procedure for writing a plugin is:
::
- +-- cloudstack/
- +-- ui/
- +-- plugins/
- +-- csMyFirstPlugin/
- +-- config.js --> Plugin metadata (title, author, vendor URL, etc.)
- +-- icon.png --> Icon, shown on side nav bar and plugin listing
- (should be square, and ~50x50px)
- +-- csMyFirstPlugin.css --> CSS file, loaded automatically when plugin loads
- +-- csMyFirstPlugin.js --> Main JS file, containing plugin code
+ +-- cloudstack/
+ +-- ui/
+ +-- plugins/
+ +-- csMyFirstPlugin/
+ +-- config.js --> Plugin metadata (title, author, vendor URL, etc.)
+ +-- icon.png --> Icon, shown on side nav bar and plugin listing
+ (should be square, and ~50x50px)
+ +-- csMyFirstPlugin.css --> CSS file, loaded automatically when plugin loads
+ +-- csMyFirstPlugin.js --> Main JS file, containing plugin code
The same files must also be present at
`/tomcat/webapps/client/plugins`.
-2. The CloudStack administrator adds the folder containing your plugin code
+#. The CloudStack administrator adds the folder containing your plugin code
under the CloudStack PLUGINS folder.
.. figure:: /_static/images/plugin2.jpg
- :align: center
- :alt: The plugin code is placed in the PLUGINS folder
+ :align: center
+ :alt: The plugin code is placed in the PLUGINS folder
-3. The administrator also adds the name of your plugin to the plugin.js
+#. The administrator also adds the name of your plugin to the plugin.js
file in the PLUGINS folder.
.. figure:: /_static/images/plugin3.jpg
- :align: center
- :alt: The plugin name is added to `plugin.js` in the PLUGINS folder
+ :align: center
+ :alt: The plugin name is added to `plugin.js` in the PLUGINS folder
-4. The next time the user refreshes the UI in the browser, your plugin
+#. The next time the user refreshes the UI in the browser, your plugin
will appear in the left navigation bar.
.. figure:: /_static/images/plugin4.jpg
- :align: center
- :alt: The plugin appears in the UI
+ :align: center
+ :alt: The plugin appears in the UI
+
How to Write a Plugin: Implementation Details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -394,302 +419,299 @@ countless options and variations. The best reference right now is to
read the existing code for the main UI, which is in the /ui folder.
Plugins are written in a very similar way to the main UI.
-1. **Create the directory to hold your plugin.**
+#. **Create the directory to hold your plugin.**
- All plugins are composed of set of required files in the directory
- /ui/plugins/pluginID, where pluginID is a short name for your
- plugin. It's recommended that you prefix your folder name (for
- example, bfMyPlugin) to avoid naming conflicts with other people's
- plugins.
+ All plugins are composed of set of required files in the directory
+ /ui/plugins/pluginID, where pluginID is a short name for your
+ plugin. It's recommended that you prefix your folder name (for
+ example, bfMyPlugin) to avoid naming conflicts with other people's
+ plugins.
- In this example, the plugin is named csMyFirstPlugin.
+ In this example, the plugin is named csMyFirstPlugin.
- ::
+ ::
- $ cd cloudstack/ui/plugins
- $ mkdir csMyFirstPlugin
- $ ls -l
+ $ cd cloudstack/ui/plugins
+ $ mkdir csMyFirstPlugin
+ $ ls -l
- total 8
- drwxr-xr-x 2 bgregory staff 68 Feb 11 14:44 csMyFirstPlugin
- -rw-r--r-- 1 bgregory staff 101 Feb 11 14:26 plugins.js
+ total 8
+ drwxr-xr-x 2 bgregory staff 68 Feb 11 14:44 csMyFirstPlugin
+ -rw-r--r-- 1 bgregory staff 101 Feb 11 14:26 plugins.js
+#. **Change to your new plugin directory.**
-2. **Change to your new plugin directory.**
+ ::
- ::
+ $ cd csMyFirstPlugin
+
+#. **Set up the listing.**
- $ cd csMyFirstPlugin
-
+ Add the file `config.js`, using your favorite editor.
-3. **Set up the listing.**
+ ::
- Add the file `config.js`, using your favorite editor.
+ $ vi config.js
- ::
+ Add the following content to config.js. This information will be
+ displayed on the plugin listing page in the UI:
- $ vi config.js
+ ::
- Add the following content to config.js. This information will be
- displayed on the plugin listing page in the UI:
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin.config = {
+ title: 'My first plugin',
+ desc: 'Tutorial plugin',
+ externalLink: 'http://www.cloudstack.org/',
+ authorName: 'Test Plugin Developer',
+ authorEmail: 'plugin.developer@example.com'
+ };
+ }(cloudStack));
+
- ::
+#. **Add a new main section.**
- (function (cloudStack) {
- cloudStack.plugins.csMyFirstPlugin.config = {
- title: 'My first plugin',
- desc: 'Tutorial plugin',
- externalLink: 'http://www.cloudstack.org/',
- authorName: 'Test Plugin Developer',
- authorEmail: 'plugin.developer@example.com'
- };
- }(cloudStack));
-
+ Add the file csMyFirstPlugin.js, using your favorite editor.
-4. **Add a new main section.**
+ ::
- Add the file csMyFirstPlugin.js, using your favorite editor.
+ $ vi csMyFirstPlugin.js
- ::
+ Add the following content to csMyFirstPlugin.js:
- $ vi csMyFirstPlugin.js
+ ::
- Add the following content to csMyFirstPlugin.js:
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin = function(plugin) {
+ plugin.ui.addSection({
+ id: 'csMyFirstPlugin',
+ title: 'My Plugin',
+ preFilter: function(args) {
+ return isAdmin();
+ },
+ show: function() {
+ return $('<div>').html('Content will go here');
+ }
+ });
+ };
+ }(cloudStack));
+
+
+#. **Register the plugin.**
+
+ You now have the minimal content needed to run the plugin, so you
+ can activate the plugin in the UI by adding it to plugins.js. First,
+ edit the file:
- ::
+ ::
- (function (cloudStack) {
- cloudStack.plugins.csMyFirstPlugin = function(plugin) {
- plugin.ui.addSection({
- id: 'csMyFirstPlugin',
- title: 'My Plugin',
- preFilter: function(args) {
- return isAdmin();
- },
- show: function() {
- return $('<div>').html('Content will go here');
- }
- });
- };
- }(cloudStack));
-
+ $ cd cloudstack/ui/plugins
+ $ vi plugins.js
+
-5. **Register the plugin.**
+ Now add the following to plugins.js:
- You now have the minimal content needed to run the plugin, so you
- can activate the plugin in the UI by adding it to plugins.js. First,
- edit the file:
+ ::
- ::
+ (function($, cloudStack) {
+ cloudStack.plugins = [
+ 'csMyFirstPlugin'
+ ];
+ }(jQuery, cloudStack));
+
- $ cd cloudstack/ui/plugins
- $ vi plugins.js
-
+#. **Check the plugin in the UI.**
- Now add the following to plugins.js:
+ First, copy all the plugin code that you have created so far to
+ `/tomcat/webapps/client/plugins`. Then refresh the browser and click
+ Plugins in the side navigation bar. You should see your new plugin.
- ::
+#. **Make the plugin do something.**
- (function($, cloudStack) {
- cloudStack.plugins = [
- 'csMyFirstPlugin'
- ];
- }(jQuery, cloudStack));
-
+ Right now, you just have placeholder content in the new plugin. It's
+ time to add real code. In this example, you will write a basic list
+ view, which renders data from an API call. You will list all virtual
+ machines owned by the logged-in user. To do this, replace the 'show'
+ function in the plugin code with a 'listView' block, containing the
+ required syntax for a list view. To get the data, use the
+ listVirtualMachines API call. Without any parameters, it will return
+ VMs only for your active user. Use the provided 'apiCall' helper
+ method to handle the server call. Of course, you are free to use any
+ other method for making the AJAX call (for example, jQuery's $.ajax
+ method).
-6. **Check the plugin in the UI.**
+ First, open your plugin's JavaScript source file in your favorite
+ editor:
- First, copy all the plugin code that you have created so far to
- `/tomcat/webapps/client/plugins`. Then refresh the browser and click
- Plugins in the side navigation bar. You should see your new plugin.
+ ::
-7. **Make the plugin do something.**
+ $ cd csMyFirstPlugin
+ $ vi csMyFirstPlugin.js
+
- Right now, you just have placeholder content in the new plugin. It's
- time to add real code. In this example, you will write a basic list
- view, which renders data from an API call. You will list all virtual
- machines owned by the logged-in user. To do this, replace the 'show'
- function in the plugin code with a 'listView' block, containing the
- required syntax for a list view. To get the data, use the
- listVirtualMachines API call. Without any parameters, it will return
- VMs only for your active user. Use the provided 'apiCall' helper
- method to handle the server call. Of course, you are free to use any
- other method for making the AJAX call (for example, jQuery's $.ajax
- method).
+ Add the following code in csMyFirstPlugin.js:
- First, open your plugin's JavaScript source file in your favorite
- editor:
+ ::
- ::
+ (function (cloudStack) {
+ cloudStack.plugins.csMyFirstPlugin = function(plugin) {
+ plugin.ui.addSection({
+ id: 'csMyFirstPlugin',
+ title: 'My Plugin',
+ preFilter: function(args) {
+ return isAdmin();
+ },
+
+ // Render page as a list view
+ listView: {
+ id: 'testPluginInstances',
+ fields: {
+ name: { label: 'label.name' },
+ instancename: { label: 'label.internal.name' },
+ displayname: { label: 'label.display.name' },
+ zonename: { label: 'label.zone.name' }
+ },
+ dataProvider: function(args) {
+ // API calls go here, to retrive the data asynchronously
+ //
+ // On successful retrieval, call
+ // args.response.success({ data: [data array] });
+ plugin.ui.apiCall('listVirtualMachines', {
+ success: function(json) {
+ var vms = json.listvirtualmachinesresponse.virtualmachine;
+
+ args.response.success({ data: vms });
+ },
+ error: function(errorMessage) {
+ args.response.error(errorMessage)
+ }
+ });
+ }
+ }
+ });
+ };
+ }(cloudStack));
+
- $ cd csMyFirstPlugin
- $ vi csMyFirstPlugin.js
-
+#. **Test the plugin.**
- Add the following code in csMyFirstPlugin.js:
+ First, copy all the plugin code that you have created so far to
+ `/tomcat/webapps/client/plugins`. Then refresh the browser. You can
+ see that your placeholder content was replaced with a list table,
+ containing 4 columns of virtual machine data.
- ::
+#. **Add an action button.**
- (function (cloudStack) {
- cloudStack.plugins.csMyFirstPlugin = function(plugin) {
- plugin.ui.addSection({
- id: 'csMyFirstPlugin',
- title: 'My Plugin',
- preFilter: function(args) {
- return isAdmin();
- },
+ Let's add an action button to the list view, which will reboot the
+ VM. To do this, add an actions block under listView. After
+ specifying the correct format, the actions will appear automatically
+ to the right of each row of data.
- // Render page as a list view
- listView: {
- id: 'testPluginInstances',
- fields: {
- name: { label: 'label.name' },
- instancename: { label: 'label.internal.name' },
- displayname: { label: 'label.display.name' },
- zonename: { label: 'label.zone.name' }
- },
- dataProvider: function(args) {
- // API calls go here, to retrive the data asynchronously
- //
- // On successful retrieval, call
- // args.response.success({ data: [data array] });
- plugin.ui.apiCall('listVirtualMachines', {
- success: function(json) {
- var vms = json.listvirtualmachinesresponse.virtualmachine;
-
- args.response.success({ data: vms });
- },
- error: function(errorMessage) {
- args.response.error(errorMessage)
- }
- });
- }
- }
- });
- };
- }(cloudStack));
-
+ ::
-8. **Test the plugin.**
-
- First, copy all the plugin code that you have created so far to
- `/tomcat/webapps/client/plugins`. Then refresh the browser. You can
- see that your placeholder content was replaced with a list table,
- containing 4 columns of virtual machine data.
-
-9. **Add an action button.**
-
- Let's add an action button to the list view, which will reboot the
- VM. To do this, add an actions block under listView. After
- specifying the correct format, the actions will appear automatically
- to the right of each row of data.
-
- ::
-
- $ vi csMyFirstPlugin.js
-
-
- Now add the following new code in csMyFirstPlugin.js. (The dots ...
- show where we have omitted some existing code for the sake of space.
- Don't actually cut and paste that part):
-
- ::
-
- ...
- listView: {
- id: 'testPluginInstances',
- ...
-
- actions: {
- // The key/ID you specify here will determine what icon is
- // shown in the UI for this action,
- // and will be added as a CSS class to the action's element
- // (i.e., '.action.restart')
- //
- // -- here, 'restart' is a predefined name in CloudStack that will
- // automatically show a 'reboot' arrow as an icon;
- // this can be changed in csMyFirstPlugin.css
- restart: {
- label: 'Restart VM',
- messages: {
- confirm: function() { return 'Are you sure you want to restart this VM?' },
- notification: function() { return 'Rebooted VM' }
- },
- action: function(args) {
- // Get the instance object of the selected row from context
- //
- // -- all currently loaded state is stored in 'context' as objects,
- // such as the selected list view row,
- // the selected section, and active user
- //
- // -- for list view actions, the object's key will be the same as
- // listView.id, specified above;
- // always make sure you specify an 'id' for the listView,
- // or else it will be 'undefined!'
- var instance = args.context.testPluginInstances[0];
-
- plugin.ui.apiCall('rebootVirtualMachine', {
- // These will be appended to the API request
- //
- // i.e., rebootVirtualMachine&id=...
- data: {
- id: instance.id
- },
- success: function(json) {
- args.response.success({
- // This is an async job, so success here only indicates
- // that the job was initiated.
- //
- // To pass the job ID to the notification UI
- // (for checking to see when action is completed),
- // '_custom: { jobID: ... }' needs to always be passed on success,
- // in the same format as below
- _custom: { jobId: json.rebootvirtualmachineresponse.jobid }
- });
- },
-
-
- error: function(errorMessage) {
- args.response.error(errorMessage); // Cancel action, show error message returned
- }
- });
- },
-
- // Because rebootVirtualMachine is an async job, we need to add
- // a poll function, which will perodically check
- // the management server to see if the job is ready
- // (via pollAsyncJobResult API call)
- //
- // The plugin API provides a helper function, 'plugin.ui.pollAsyncJob',
- / which will work for most jobs
- // in CloudStack
- notification: {
- poll: plugin.ui.pollAsyncJob
- }
- }
- },
+ $ vi csMyFirstPlugin.js
+
+
+ Now add the following new code in csMyFirstPlugin.js. (The dots ...
+ show where we have omitted some existing code for the sake of space.
+ Don't actually cut and paste that part):
- dataProvider: function(args) {
- ...
- ...
+ ::
+
+ ...
+ listView: {
+ id: 'testPluginInstances',
+ ...
+
+ actions: {
+ // The key/ID you specify here will determine what icon is
+ // shown in the UI for this action,
+ // and will be added as a CSS class to the action's element
+ // (i.e., '.action.restart')
+ //
+ // -- here, 'restart' is a predefined name in CloudStack that will
+ // automatically show a 'reboot' arrow as an icon;
+ // this can be changed in csMyFirstPlugin.css
+ restart: {
+ label: 'Restart VM',
+ messages: {
+ confirm: function() { return 'Are you sure you want to restart this VM?' },
+ notification: function() { return 'Rebooted VM' }
+ },
+ action: function(args) {
+ // Get the instance object of the selected row from context
+ //
+ // -- all currently loaded state is stored in 'context' as objects,
+ // such as the selected list view row,
+ // the selected section, and active user
+ //
+ // -- for list view actions, the object's key will be the same as
+ // listView.id, specified above;
+ // always make sure you specify an 'id' for the listView,
+ // or else it will be 'undefined!'
+ var instance = args.context.testPluginInstances[0];
+
+ plugin.ui.apiCall('rebootVirtualMachine', {
+ // These will be appended to the API request
+ //
+ // i.e., rebootVirtualMachine&id=...
+ data: {
+ id: instance.id
+ },
+ success: function(json) {
+ args.response.success({
+ // This is an async job, so success here only indicates
+ // that the job was initiated.
+ //
+ // To pass the job ID to the notification UI
+ // (for checking to see when action is completed),
+ // '_custom: { jobID: ... }' needs to always be passed on success,
+ // in the same format as below
+ _custom: { jobId: json.rebootvirtualmachineresponse.jobid }
+ });
+ },
+
+
+ error: function(errorMessage) {
+ args.response.error(errorMessage); // Cancel action, show error message returned
+ }
+ });
+ },
+
+ // Because rebootVirtualMachine is an async job, we need to add
+ // a poll function, which will perodically check
+ // the management server to see if the job is ready
+ // (via pollAsyncJobResult API call)
+ //
+ // The plugin API provides a helper function, 'plugin.ui.pollAsyncJob',
+ / which will work for most jobs
+ // in CloudStack
+ notification: {
+ poll: plugin.ui.pollAsyncJob
+ }
+ }
+ },
+
+ dataProvider: function(args) {
+ ...
+ ...
-10. **Add the thumbnail icon.**
+#. **Add the thumbnail icon.**
- Create an icon file; it should be square, about 50x50 pixels, and
- named `icon.png`. Copy it into the same directory with your plugin
- code: `cloudstack/ui/plugins/csMyFirstPlugin/icon.png`.
+ Create an icon file; it should be square, about 50x50 pixels, and
+ named `icon.png`. Copy it into the same directory with your plugin
+ code: `cloudstack/ui/plugins/csMyFirstPlugin/icon.png`.
-11. **Add the stylesheet.**
+#. **Add the stylesheet.**
+
+ Create a CSS file, with the same name as your `.js` file. Copy it into
+ the same directory with your plugin code:
+ `cloudstack/ui/plugins/csMyFirstPlugin/csMyFirstPlugin.css`.
- Create a CSS file, with the same name as your `.js` file. Copy it into
- the same directory with your plugin code:
- `cloudstack/ui/plugins/csMyFirstPlugin/csMyFirstPlugin.css`.
.. | plugin_intro.jpg: New plugin button in CloudStack navbar | image:: _static/images/plugin_intro.jpg
.. | plugin1.jpg: Write the plugin code | image:: _static/images/plugin1.jpg
.. | plugin2.jpg: The plugin code is placed in the PLUGINS folder | image:: _static/images/plugin2.jpg
.. | plugin3.jpg: The plugin name is added to plugin.js in the PLUGINS folder | image:: _static/images/plugin3.jpg
.. | plugin4.jpg: The plugin appears in the UI | image:: _static/images/plugin4.jpg
-
-
[4/4] git commit: fixed the formatting in all the files and added the
license to each file: This closes #4
Posted by se...@apache.org.
fixed the formatting in all the files and added the license to each file: This closes #4
Signed-off-by: Sebastien Goasguen <ru...@gmail.com>
Project: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/repo
Commit: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/commit/e55976f3
Tree: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/tree/e55976f3
Diff: http://git-wip-us.apache.org/repos/asf/cloudstack-docs/diff/e55976f3
Branch: refs/heads/master
Commit: e55976f35a822e2a369b1341db35307b2cb2dde2
Parents: 4629e02
Author: Will Stevens <ws...@cloudops.com>
Authored: Wed May 28 12:25:35 2014 -0400
Committer: Sebastien Goasguen <ru...@gmail.com>
Committed: Wed May 28 19:13:00 2014 +0200
----------------------------------------------------------------------
rtd/source/administration_guide.rst | 742 +++++++++++++++----
rtd/source/alloc.rst | 123 +--
rtd/source/ansible.rst | 197 ++---
rtd/source/concepts.rst | 358 +++++----
rtd/source/conf.py | 9 +
rtd/source/dev.rst | 477 ++++++------
rtd/source/developer_guide.rst | 323 ++++----
rtd/source/index.rst | 80 +-
.../networking/autoscale_without_netscaler.rst | 168 ++++-
rtd/source/networking/ipv6.rst | 173 ++---
rtd/source/networking/midonet.rst | 69 +-
rtd/source/networking/nicira-plugin.rst | 102 ++-
rtd/source/networking/ovs-plugin.rst | 205 ++---
rtd/source/networking/vxlan.rst | 332 +++++----
rtd/source/plugins.rst | 590 ++++++++-------
15 files changed, 2342 insertions(+), 1606 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/administration_guide.rst
----------------------------------------------------------------------
diff --git a/rtd/source/administration_guide.rst b/rtd/source/administration_guide.rst
index c79632a..fffcc91 100644
--- a/rtd/source/administration_guide.rst
+++ b/rtd/source/administration_guide.rst
@@ -1,55 +1,92 @@
+.. 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.
+
+
Apache CloudStack Administration Guide
======================================
Backups
-------
+
Monitoring
----------
+
SNMP
-____
+----
CloudStack will send alerts for a number of
+
Syslog
-_______
+------
+
AMQP
-_____
+----
+
JMX
-____
+---
+
API Queries
-___________
+-----------
Usage
-----
+
Tuning
------
+
Configuration Parameters
------------------------
+
System Reliability and Availability
-----------------------------------
+
HA for Management Server
-_________________________
+------------------------
+
+The CloudStack Management Server should be deployed in a multi-node
+configuration such that it is not susceptible to individual server failures.
+The Management Server itself (as distinct from the MySQL database) is
+stateless and may be placed behind a load balancer.
-The CloudStack Management Server should be deployed in a multi-node configuration such that it is not susceptible to individual server failures. The Management Server itself (as distinct from the MySQL database) is stateless and may be placed behind a load balancer.
+Normal operation of Hosts is not impacted by an outage of all Management
+Serves. All guest VMs will continue to work.
-Normal operation of Hosts is not impacted by an outage of all Management Serves. All guest VMs will continue to work.
+When the Management Server is down, no new VMs can be created, and the end
+user and admin UI, API, dynamic load distribution, and HA will cease to work.
-When the Management Server is down, no new VMs can be created, and the end user and admin UI, API, dynamic load distribution, and HA will cease to work.
Management Server Load Balancing
-________________________________
+--------------------------------
-CloudStack can use a load balancer to provide a virtual IP for multiple Management Servers. The administrator is responsible for creating the load balancer rules for the Management Servers. The application requires persistence or stickiness across multiple sessions. The following chart lists the ports that should be load balanced and whether or not persistence is required.
+CloudStack can use a load balancer to provide a virtual IP for multiple
+Management Servers. The administrator is responsible for creating the load
+balancer rules for the Management Servers. The application requires
+persistence or stickiness across multiple sessions. The following chart lists
+the ports that should be load balanced and whether or not persistence is
+required.
============ ======================== ============== ======================
Source port Destination port Protocol Persistence Required?
@@ -58,304 +95,626 @@ Source port Destination port Protocol Persistence Required?
8250 8250 TCP Yes
============ ======================== ============== ======================
-In addition to above settings, the administrator is responsible for setting the 'host' global config value from the management server IP to load balancer virtual IP address. If the 'host' value is not set to the VIP for Port 8250 and one of your management servers crashes, the UI is still available but the system VMs will not be able to contact the management server.
+In addition to above settings, the administrator is responsible for setting
+the 'host' global config value from the management server IP to load balancer
+virtual IP address. If the 'host' value is not set to the VIP for Port 8250
+and one of your management servers crashes, the UI is still available but the
+system VMs will not be able to contact the management server.
+
Limiting the Rate of API Requests
-__________________________________
+---------------------------------
+
+You can limit the rate at which API requests can be placed for each account.
+This is useful to avoid malicious attacks on the Management Server, prevent
+performance degradation, and provide fairness to all accounts.
-You can limit the rate at which API requests can be placed for each account. This is useful to avoid malicious attacks on the Management Server, prevent performance degradation, and provide fairness to all accounts.
+If the number of API calls exceeds the threshold, an error message is returned
+for any additional API calls. The caller will have to retry these API calls at
+another time.
-If the number of API calls exceeds the threshold, an error message is returned for any additional API calls. The caller will have to retry these API calls at another time.
Configuring the API Request Rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To control the API request rate, use the following global configuration settings:
+To control the API request rate, use the following global configuration
+settings:
+
+- api.throttling.enabled - Enable/Disable API throttling. By default, this
+ setting is false, so API throttling is not enabled.
+
+- api.throttling.interval (in seconds) - Time interval during which the
+ number of API requests is to be counted. When the interval has passed, the
+ API count is reset to 0.
+
+- api.throttling.max - Maximum number of APIs that can be placed within the
+ api.throttling.interval period.
+
+- api.throttling.cachesize - Cache size for storing API counters. Use a value
+ higher than the total number of accounts managed by the cloud. One cache
+ entry is needed for each account, to store the running API total for that
+ account.
-* api.throttling.enabled - Enable/Disable API throttling. By default, this setting is false, so API throttling is not enabled.
-* api.throttling.interval (in seconds) - Time interval during which the number of API requests is to be counted. When the interval has passed, the API count is reset to 0.
-* api.throttling.max - Maximum number of APIs that can be placed within the api.throttling.interval period.
-* api.throttling.cachesize - Cache size for storing API counters. Use a value higher than the total number of accounts managed by the cloud. One cache entry is needed for each account, to store the running API total for that account.
Limitations on API Throttling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following limitations exist in the current implementation of this feature:
-* In a deployment with multiple Management Servers, the cache is not synchronized across them. In this case, CloudStack might not be able to ensure that only the exact desired number of API requests are allowed. In the worst case, the number of API calls that might be allowed is (number of Management Servers) * (api.throttling.max).
-* The API commands resetApiLimit and getApiLimit are limited to the Management Server where the API is invoked.
+- In a deployment with multiple Management Servers, the cache is not
+ synchronized across them. In this case, CloudStack might not be able to
+ ensure that only the exact desired number of API requests are allowed. In
+ the worst case, the number of API calls that might be allowed is ``(number
+ of Management Servers) * (api.throttling.max)``.
+
+- The API commands resetApiLimit and getApiLimit are limited to the
+ Management Server where the API is invoked.
+
HA-Enabled Virtual Machines
-___________________________
+---------------------------
-The user can specify a virtual machine as HA-enabled. By default, all virtual router VMs and Elastic Load Balancing VMs are automatically configured as HA-enabled. When an HA-enabled VM crashes, CloudStack detects the crash and restarts the VM automatically within the same Availability Zone. HA is never performed across different Availability Zones. CloudStack has a conservative policy towards restarting VMs and ensures that there will never be two instances of the same VM running at the same time. The Management Server attempts to start the VM on another Host in the same cluster.
+The user can specify a virtual machine as HA-enabled. By default, all virtual
+router VMs and Elastic Load Balancing VMs are automatically configured as
+HA-enabled. When an HA-enabled VM crashes, CloudStack detects the crash and
+restarts the VM automatically within the same Availability Zone. HA is never
+performed across different Availability Zones. CloudStack has a conservative
+policy towards restarting VMs and ensures that there will never be two
+instances of the same VM running at the same time. The Management Server
+attempts to start the VM on another Host in the same cluster.
VM HA is not supported when the VM is using local storage.
+
Dedicated HA Hosts
~~~~~~~~~~~~~~~~~~
-One or more hosts can be designated for use only by HA-enabled VMs that are restarting due to a host failure. Setting up a pool of such dedicated HA hosts as the recovery destination for all HA-enabled VMs is useful to:
+One or more hosts can be designated for use only by HA-enabled VMs that are
+restarting due to a host failure. Setting up a pool of such dedicated HA hosts
+as the recovery destination for all HA-enabled VMs is useful to:
+
+#. Make it easier to determine which VMs have been restarted as part of the
+ CloudStack high-availability function. If a VM is running on a dedicated HA
+ host, then it must be an HA-enabled VM whose original host failed. (With
+ one exception: It is possible for an administrator to manually migrate any
+ VM to a dedicated HA host.).
+
+#. Keep HA-enabled VMs from restarting on hosts which may be reserved for
+ other purposes.
-#. Make it easier to determine which VMs have been restarted as part of the CloudStack high-availability function. If a VM is running on a dedicated HA host, then it must be an HA-enabled VM whose original host failed. (With one exception: It is possible for an administrator to manually migrate any VM to a dedicated HA host.).
-#. Keep HA-enabled VMs from restarting on hosts which may be reserved for other purposes.
+The dedicated HA option is set through a special host tag when the host is
+created. To allow the administrator to dedicate hosts to only HA-enabled VMs,
+set the global configuration variable ha.tag to the desired tag (for example,
+"ha_host"), and restart the Management Server. Enter the value in the Host
+Tags field when adding the host(s) that you want to dedicate to HA-enabled VMs.
-The dedicated HA option is set through a special host tag when the host is created. To allow the administrator to dedicate hosts to only HA-enabled VMs, set the global configuration variable ha.tag to the desired tag (for example, "ha_host"), and restart the Management Server. Enter the value in the Host Tags field when adding the host(s) that you want to dedicate to HA-enabled VMs.
Primary Storage Outage and Data Loss
-____________________________________
+------------------------------------
+
+When a primary storage outage occurs the hypervisor immediately stops all VMs
+stored on that storage device. Guests that are marked for HA will be restarted
+as soon as practical when the primary storage comes back on line. With NFS,
+the hypervisor may allow the virtual machines to continue running depending on
+the nature of the issue. For example, an NFS hang will cause the guest VMs to
+be suspended until storage connectivity is restored.Primary storage is not
+designed to be backed up. Individual volumes in primary storage can be backed
+up using snapshots.
-When a primary storage outage occurs the hypervisor immediately stops all VMs stored on that storage device. Guests that are marked for HA will be restarted as soon as practical when the primary storage comes back on line. With NFS, the hypervisor may allow the virtual machines to continue running depending on the nature of the issue. For example, an NFS hang will cause the guest VMs to be suspended until storage connectivity is restored.Primary storage is not designed to be backed up. Individual volumes in primary storage can be backed up using snapshots.
Secondary Storage Outage and Data Loss
-______________________________________
+--------------------------------------
+
+For a Zone that has only one secondary storage server, a secondary storage
+outage will have feature level impact to the system but will not impact
+running guest VMs. It may become impossible to create a VM with the selected
+template for a user. A user may also not be able to save snapshots or
+examine/restore saved snapshots. These features will automatically be
+available when the secondary storage comes back online.
-For a Zone that has only one secondary storage server, a secondary storage outage will have feature level impact to the system but will not impact running guest VMs. It may become impossible to create a VM with the selected template for a user. A user may also not be able to save snapshots or examine/restore saved snapshots. These features will automatically be available when the secondary storage comes back online.
+Secondary storage data loss will impact recently added user data including
+templates, snapshots, and ISO images. Secondary storage should be backed up
+periodically. Multiple secondary storage servers can be provisioned within
+each zone to increase the scalability of the system.
-Secondary storage data loss will impact recently added user data including templates, snapshots, and ISO images. Secondary storage should be backed up periodically. Multiple secondary storage servers can be provisioned within each zone to increase the scalability of the system.
Managing System VMs
-------------------
-CloudStack uses several types of system virtual machines to perform tasks in the cloud. In general CloudStack manages these system VMs and creates, starts, and stops them as needed based on scale and immediate needs. However, the administrator should be aware of them and their roles to assist in debugging issues.
+CloudStack uses several types of system virtual machines to perform tasks in
+the cloud. In general CloudStack manages these system VMs and creates, starts,
+and stops them as needed based on scale and immediate needs. However, the
+administrator should be aware of them and their roles to assist in debugging
+issues.
+
+You can configure the system.vm.random.password parameter to create a random
+system VM password to ensure higher security. If you reset the value for
+system.vm.random.password to true and restart the Management Server, a random
+password is generated and stored encrypted in the database. You can view the
+decrypted password under the system.vm.password global parameter on the
+CloudStack UI or by calling the listConfigurations API.
-You can configure the system.vm.random.password parameter to create a random system VM password to ensure higher security. If you reset the value for system.vm.random.password to true and restart the Management Server, a random password is generated and stored encrypted in the database. You can view the decrypted password under the system.vm.password global parameter on the CloudStack UI or by calling the listConfigurations API.
The System VM Template
-______________________
+----------------------
+
+The System VMs come from a single template. The System VM has the following
+characteristics:
+
+- Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security patches from
+ the Debian security APT repository
+
+- Has a minimal set of packages installed thereby reducing the attack surface
+
+- 32-bit for enhanced performance on Xen/VMWare
-The System VMs come from a single template. The System VM has the following characteristics:
+- pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware tools for
+ optimum performance on all hypervisors
+
+- Xen tools inclusion allows performance monitoring
+
+- Latest versions of HAProxy, iptables, IPsec, and Apache from debian
+ repository ensures improved security and speed
+
+- Latest version of JRE from Sun/Oracle ensures improved security and speed
-* Debian 6.0 ("Squeeze"), 2.6.32 kernel with the latest security patches from the Debian security APT repository
-* Has a minimal set of packages installed thereby reducing the attack surface
-* 32-bit for enhanced performance on Xen/VMWare
-* pvops kernel with Xen PV drivers, KVM virtio drivers, and VMware tools for optimum performance on all hypervisors
-* Xen tools inclusion allows performance monitoring
-* Latest versions of HAProxy, iptables, IPsec, and Apache from debian repository ensures improved security and speed
-* Latest version of JRE from Sun/Oracle ensures improved security and speed
Accessing System VMs
-____________________
+--------------------
-It may sometimes be necessary to access System VMs for diagnostics of certain issues, for example if you are experiencing SSVM (Secondary Storage VM) connection issues. Use the steps below in order to connect to the SSH console of a running System VM.
+It may sometimes be necessary to access System VMs for diagnostics of certain
+issues, for example if you are experiencing SSVM (Secondary Storage VM)
+connection issues. Use the steps below in order to connect to the SSH console
+of a running System VM.
+
+Accessing System VMs over the network requires the use of private keys and
+connecting to System VMs SSH Daemon on port 3922. XenServer/KVM Hypervisors
+store this key at /root/.ssh/id_rsa.cloud on each CloudStack agent. To access
+System VMs running on ESXi, the key is stored on the management server at
+/var/lib/cloudstack/management/.ssh/id_rsa.
-Accessing System VMs over the network requires the use of private keys and connecting to System VMs SSH Daemon on port 3922. XenServer/KVM Hypervisors store this key at /root/.ssh/id_rsa.cloud on each CloudStack agent. To access System VMs running on ESXi, the key is stored on the management server at /var/lib/cloudstack/management/.ssh/id_rsa.
#. Find the details of the System VM
+
#. Log in with admin privileges to the CloudStack UI.
- #. Click Infrastructure, then System VMs, and then click the name of a running VM.
- #. Take a note of the 'Host', 'Private IP Address' and 'Link Local IP Address' of the System VM you wish to access.
+
+ #. Click Infrastructure, then System VMs, and then click the name of a
+ running VM.
+
+ #. Take a note of the 'Host', 'Private IP Address' and 'Link Local IP
+ Address' of the System VM you wish to access.
+
#. XenServer/KVM Hypervisors
+
#. Connect to the Host of which the System VM is running.
- #. SSH to the 'Link Local IP Address' of the System VM from the Host on which the VM is running.
+
+ #. SSH to the 'Link Local IP Address' of the System VM from the Host on
+ which the VM is running.
+
Format: ssh -i <path-to-private-key> <link-local-ip> -p 3922
+
Example: root@faith:~# ssh -i /root/.ssh/id_rsa.cloud 169.254.3.93 -p 3922
+
#. ESXi Hypervisors
+
#. Connect to your CloudStack Management Server.
+
#. ESXi users should SSH to the private IP address of the System VM.
+
Format: ssh -i <path-to-private-key> <vm-private-ip> -p 3922
+
Example: root@management:~# ssh -i /var/lib/cloudstack/management/.ssh/id_rsa 172.16.0.250 -p 3922
+
Multiple System VM Support for VMware
-______________________________________
+-------------------------------------
+
+Every CloudStack zone has single System VM for template processing tasks such
+as downloading templates, uploading templates, and uploading ISOs. In a zone
+where VMware is being used, additional System VMs can be launched to process
+VMware-specific tasks such as taking snapshots and creating private templates.
+The CloudStack management server launches additional System VMs for
+VMware-specific tasks as the load increases. The management server monitors
+and weights all commands sent to these System VMs and performs dynamic load
+balancing and scaling-up of more System VMs.
-Every CloudStack zone has single System VM for template processing tasks such as downloading templates, uploading templates, and uploading ISOs. In a zone where VMware is being used, additional System VMs can be launched to process VMware-specific tasks such as taking snapshots and creating private templates. The CloudStack management server launches additional System VMs for VMware-specific tasks as the load increases. The management server monitors and weights all commands sent to these System VMs and performs dynamic load balancing and scaling-up of more System VMs.
Console Proxy
-_____________
+-------------
-The Console Proxy is a type of System Virtual Machine that has a role in presenting a console view via the web UI. It connects the user’s browser to the VNC port made available via the hypervisor for the console of the guest. Both the administrator and end user web UIs offer a console connection.
+The Console Proxy is a type of System Virtual Machine that has a role in
+presenting a console view via the web UI. It connects the user’s browser to
+the VNC port made available via the hypervisor for the console of the guest.
+Both the administrator and end user web UIs offer a console connection.
-Clicking a console icon brings up a new window. The AJAX code downloaded into that window refers to the public IP address of a console proxy VM. There is exactly one public IP address allocated per console proxy VM. The AJAX application connects to this IP. The console proxy then proxies the connection to the VNC port for the requested VM on the Host hosting the guest.
+Clicking a console icon brings up a new window. The AJAX code downloaded into
+that window refers to the public IP address of a console proxy VM. There is
+exactly one public IP address allocated per console proxy VM. The AJAX
+application connects to this IP. The console proxy then proxies the connection
+to the VNC port for the requested VM on the Host hosting the guest.
-The console proxy VM will periodically report its active session count to the Management Server. The default reporting interval is five seconds. This can be changed through standard Management Server configuration with the parameter consoleproxy.loadscan.interval.
+The console proxy VM will periodically report its active session count to the
+Management Server. The default reporting interval is five seconds. This can be
+changed through standard Management Server configuration with the parameter
+consoleproxy.loadscan.interval.
-Assignment of guest VM to console proxy is determined by first determining if the guest VM has a previous session associated with a console proxy. If it does, the Management Server will assign the guest VM to the target Console Proxy VM regardless of the load on the proxy VM. Failing that, the first available running Console Proxy VM that has the capacity to handle new sessions is used.
+Assignment of guest VM to console proxy is determined by first determining if
+the guest VM has a previous session associated with a console proxy. If it
+does, the Management Server will assign the guest VM to the target Console
+Proxy VM regardless of the load on the proxy VM. Failing that, the first
+available running Console Proxy VM that has the capacity to handle new
+sessions is used.
+
+Console proxies can be restarted by administrators but this will interrupt
+existing console sessions for users.
-Console proxies can be restarted by administrators but this will interrupt existing console sessions for users.
Using a SSL Certificate for the Console Proxy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The console viewing functionality uses a dynamic DNS service under the domain name realhostip.com to assist in providing SSL security to console sessions. The console proxy is assigned a public IP address. In order to avoid browser warnings for mismatched SSL certificates, the URL for the new console window is set to the form of https://aaa-bbb-ccc-ddd.realhostip.com. You will see this URL during console session creation. CloudStack includes the realhostip.com SSL certificate in the console proxy VM. Of course, CloudStack cannot know about the DNS A records for our customers' public IPs prior to shipping the software. CloudStack therefore runs a dynamic DNS server that is authoritative for the realhostip.com domain. It maps the aaa-bbb-ccc-ddd part of the DNS name to the IP address aaa.bbb.ccc.ddd on lookups. This allows the browser to correctly connect to the console proxy's public IP, where it then expects and receives a SSL certificate for realhostip.com, and SSL is set up withou
t browser warnings.
+The console viewing functionality uses a dynamic DNS service under the domain
+name realhostip.com to assist in providing SSL security to console sessions.
+The console proxy is assigned a public IP address. In order to avoid browser
+warnings for mismatched SSL certificates, the URL for the new console window
+is set to the form of https://aaa-bbb-ccc-ddd.realhostip.com. You will see
+this URL during console session creation. CloudStack includes the
+realhostip.com SSL certificate in the console proxy VM. Of course, CloudStack
+cannot know about the DNS A records for our customers' public IPs prior to
+shipping the software. CloudStack therefore runs a dynamic DNS server that is
+authoritative for the realhostip.com domain. It maps the aaa-bbb-ccc-ddd part
+of the DNS name to the IP address aaa.bbb.ccc.ddd on lookups. This allows the
+browser to correctly connect to the console proxy's public IP, where it then
+expects and receives a SSL certificate for realhostip.com, and SSL is set up
+without browser warnings.
+
Changing the Console Proxy SSL Certificate and Domain
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If the administrator prefers, it is possible for the URL of the customer's console session to show a domain other than realhostip.com. The administrator can customize the displayed domain by selecting a different domain and uploading a new SSL certificate and private key. The domain must run a DNS service that is capable of resolving queries for addresses of the form aaa-bbb-ccc-ddd.your.domain to an IPv4 IP address in the form aaa.bbb.ccc.ddd, for example, 202.8.44.1. To change the console proxy domain, SSL certificate, and private key:
+If the administrator prefers, it is possible for the URL of the customer's
+console session to show a domain other than realhostip.com. The administrator
+can customize the displayed domain by selecting a different domain and
+uploading a new SSL certificate and private key. The domain must run a DNS
+service that is capable of resolving queries for addresses of the form
+aaa-bbb-ccc-ddd.your.domain to an IPv4 IP address in the form aaa.bbb.ccc.ddd,
+for example, 202.8.44.1. To change the console proxy domain, SSL certificate,
+and private key:
+
+#. Set up dynamic name resolution or populate all possible DNS names in your
+ public IP range into your existing DNS server with the format
+ aaa-bbb-ccc-ddd.company.com -> aaa.bbb.ccc.ddd.
+
+#. Generate the private key and certificate signing request (CSR). When you
+ are using openssl to generate private/public key pairs and CSRs, for the
+ private key that you are going to paste into the CloudStack UI, be sure to
+ convert it into PKCS#8 format.
+
+ #. Generate a new 2048-bit private key
+
+ ::
+
+ openssl genrsa -des3 -out yourprivate.key 2048
+
+ #. Generate a new certificate CSR
-#. Set up dynamic name resolution or populate all possible DNS names in your public IP range into your existing DNS server with the format aaa-bbb-ccc-ddd.company.com -> aaa.bbb.ccc.ddd.
-#. Generate the private key and certificate signing request (CSR). When you are using openssl to generate private/public key pairs and CSRs, for the private key that you are going to paste into the CloudStack UI, be sure to convert it into PKCS#8 format.
+ ::
+
+ openssl req -new -key yourprivate.key -out yourcertificate.csr
+
+ #. Head to the website of your favorite trusted Certificate Authority,
+ purchase an SSL certificate, and submit the CSR. You should receive a
+ valid certificate in return
- 1. Generate a new 2048-bit private key::
+ #. Convert your private key format into PKCS#8 encrypted format.
- openssl genrsa -des3 -out yourprivate.key 2048
+ ::
- 2. Generate a new certificate CSR::
+ openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key
- openssl req -new -key yourprivate.key -out yourcertificate.csr
+ #. Convert your PKCS#8 encrypted private key into the PKCS#8 format that is
+ compliant with CloudStack
- 3. Head to the website of your favorite trusted Certificate Authority, purchase an SSL certificate, and submit the CSR. You should receive a valid certificate in return
- 4. Convert your private key format into PKCS#8 encrypted format.::
+ ::
- openssl pkcs8 -topk8 -in yourprivate.key -out yourprivate.pkcs8.encrypted.key
+ openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key
- 5. Convert your PKCS#8 encrypted private key into the PKCS#8 format that is compliant with CloudStack::
+#. In the Update SSL Certificate screen of the CloudStack UI, paste the following:
- openssl pkcs8 -in yourprivate.pkcs8.encrypted.key -out yourprivate.pkcs8.key
+ - The certificate you've just generated.
+
+ - The private key you've just generated.
+
+ - The desired new domain name; for example, company.com
-3. In the Update SSL Certificate screen of the CloudStack UI, paste the following:
- *. The certificate you've just generated.
- *. The private key you've just generated.
- *. The desired new domain name; for example, company.com
+#. The desired new domain name; for example, company.com
+ This stops all currently running console proxy VMs, then restarts them with
+ the new certificate and key. Users might notice a brief interruption in
+ console availability.
-4. The desired new domain name; for example, company.com
-This stops all currently running console proxy VMs, then restarts them with the new certificate and key. Users might notice a brief interruption in console availability.
+The Management Server generates URLs of the form "aaa-bbb-ccc-ddd.company.com"
+after this change is made. The new console requests will be served with the
+new DNS domain name, certificate, and key.
-The Management Server generates URLs of the form "aaa-bbb-ccc-ddd.company.com" after this change is made. The new console requests will be served with the new DNS domain name, certificate, and key.
Virtual Router
-_______________
+--------------
-The virtual router is a type of System Virtual Machine. The virtual router is one of the most frequently used service providers in CloudStack. The end user has no direct access to the virtual router. Users can ping the virtual router and take actions that affect it (such as setting up port forwarding), but users do not have SSH access into the virtual router.
+The virtual router is a type of System Virtual Machine. The virtual router is
+one of the most frequently used service providers in CloudStack. The end user
+has no direct access to the virtual router. Users can ping the virtual router
+and take actions that affect it (such as setting up port forwarding), but
+users do not have SSH access into the virtual router.
+
+Virtual routers can be restarted by administrators, but this will interrupt
+public network access and other services for end users. A basic test in
+debugging networking issues is to attempt to ping the virtual router from a
+guest VM. Some of the characteristics of the virtual router are determined by
+its associated system service offering..
-Virtual routers can be restarted by administrators, but this will interrupt public network access and other services for end users. A basic test in debugging networking issues is to attempt to ping the virtual router from a guest VM. Some of the characteristics of the virtual router are determined by its associated system service offering..
Configuring the Virtual Router
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can set the following:
-*. IP range
-*. Supported network services
-*. Default domain name for the network serviced by the virtual router
-*. Gateway IP address
-*. How often CloudStack fetches network usage statistics from CloudStack virtual routers. If you want to collect traffic metering data from the virtual router, set the global configuration parameter router.stats.interval. If you are not using the virtual router to gather network usage statistics, set it to 0.
+
+- IP range
+
+- Supported network services
+
+- Default domain name for the network serviced by the virtual router
+
+- Gateway IP address
+
+- How often CloudStack fetches network usage statistics from CloudStack
+ virtual routers. If you want to collect traffic metering data from the
+ virtual router, set the global configuration parameter
+ router.stats.interval. If you are not using the virtual router to gather
+ network usage statistics, set it to 0.
+
Upgrading a Virtual Router with System Service Offerings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-When CloudStack creates a virtual router, it uses default settings which are defined in a default system service offering. See Section 8.2, “System Service Offerings”. All the virtual routers in a single guest network use the same system service offering. You can upgrade the capabilities of the virtual router by creating and applying a custom system service offering.
-Define your custom system service offering.
+When CloudStack creates a virtual router, it uses default settings which are
+defined in a default system service offering. See Section 8.2, “System Service
+Offerings”. All the virtual routers in a single guest network use the same
+system service offering. You can upgrade the capabilities of the virtual
+router by creating and applying a custom system service offering.
+Define your custom system service offering.
+
Associate the system service offering with a network offering.
-Apply the network offering to the network where you want the virtual routers to use the new system service offering.
+Apply the network offering to the network where you want the virtual routers
+to use the new system service offering.
+
Best Practices for Virtual Routers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* Restarting a virtual router from a hypervisor console deletes all the iptables rules. To work around this issue, stop the virtual router and start it from the CloudStack UI.
-* Do not use the destroyRouter API when only one router is available in the network, because restartNetwork API with the cleanup=false parameter can't recreate it later. If you want to destroy and recreate the single router available in the network, use the restartNetwork API with the cleanup=true parameter.
+- Restarting a virtual router from a hypervisor console deletes all the
+ iptables rules. To work around this issue, stop the virtual router and
+ start it from the CloudStack UI.
+
+- Do not use the destroyRouter API when only one router is available in the
+ network, because restartNetwork API with the cleanup=false parameter can't
+ recreate it later. If you want to destroy and recreate the single router
+ available in the network, use the restartNetwork API with the cleanup=true
+ parameter.
+
Secondary Storage VM
-_____________________
+--------------------
-In addition to the hosts, CloudStack’s Secondary Storage VM mounts and writes to secondary storage.
-Submissions to secondary storage go through the Secondary Storage VM. The Secondary Storage VM can retrieve templates and ISO images from URLs using a variety of protocols.
-The secondary storage VM provides a background task that takes care of a variety of secondary storage activities: downloading a new template to a Zone, copying templates between Zones, and snapshot backups.
-The administrator can log in to the secondary storage VM if needed.
+In addition to the hosts, CloudStack’s Secondary Storage VM mounts and writes
+to secondary storage. Submissions to secondary storage go through the
+Secondary Storage VM. The Secondary Storage VM can retrieve templates and ISO
+images from URLs using a variety of protocols. The secondary storage VM
+provides a background task that takes care of a variety of secondary storage
+activities: downloading a new template to a Zone, copying templates between
+Zones, and snapshot backups. The administrator can log in to the secondary
+storage VM if needed.
Storage Administration
----------------------
+
Hypervisor Host Management
--------------------------
+
Maintenance mode
-________________
+----------------
+
+Maintenance mode makes a host unavailable to have new virtual machines
+allocated to it. It also starts a process by which running virtual machines
+are live migrated to other available hosts within the same cluster. It should
+be noted that the live migration is not universally perfect, and you may end
+up with recalcitrant virtual machines which are unable to be live migrated.
+This can be due to lack of hypervisor-specific tooling or other problems.
-Maintenance mode makes a host unavailable to have new virtual machines allocated to it. It also starts a process by which running virtual machines are live migrated to other available hosts within the same cluster. It should be noted that the live migration is not universally perfect, and you may end up with recalcitrant virtual machines which are unable to be live migrated. This can be due to lack of hypervisor-specific tooling or other problems.
vCenter and Maintenance mode
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-To enter maintenance mode on a vCenter host, both vCenter and CloudStack must be used in concert. CloudStack and vCenter have separate maintenance modes that work closely together.
+To enter maintenance mode on a vCenter host, both vCenter and CloudStack must
+be used in concert. CloudStack and vCenter have separate maintenance modes
+that work closely together.
+
+#. Place the host into CloudStack's "scheduled maintenance" mode. This does
+ not invoke the vCenter maintenance mode, but only causes VMs to be migrated
+ off the host When the CloudStack maintenance mode is requested, the host
+ first moves into the Prepare for Maintenance state. In this state it cannot
+ be the target of new guest VM starts. Then all VMs will be migrated off the
+ server. Live migration will be used to move VMs off the host. This allows
+ the guests to be migrated to other hosts with no disruption to the guests.
+ After this migration is completed, the host will enter the Ready for
+ Maintenance mode.
-#. Place the host into CloudStack's "scheduled maintenance" mode. This does not invoke the vCenter maintenance mode, but only causes VMs to be migrated off the host When the CloudStack maintenance mode is requested, the host first moves into the Prepare for Maintenance state. In this state it cannot be the target of new guest VM starts. Then all VMs will be migrated off the server. Live migration will be used to move VMs off the host. This allows the guests to be migrated to other hosts with no disruption to the guests. After this migration is completed, the host will enter the Ready for Maintenance mode.
#. Wait for the "Ready for Maintenance" indicator to appear in the UI.
-#. Now use vCenter to perform whatever actions are necessary to maintain the host. During this time, the host cannot be the target of new VM allocations.
-#. When the maintenance tasks are complete, take the host out of maintenance mode as follows:
- a. First use vCenter to exit the vCenter maintenance mode. This makes the host ready for CloudStack to reactivate it.
- b. Then use CloudStack's administrator UI to cancel the CloudStack maintenance mode When the host comes back online, the VMs that were migrated off of it may be migrated back to it manually and new VMs can be added.
+
+#. Now use vCenter to perform whatever actions are necessary to maintain the
+ host. During this time, the host cannot be the target of new VM allocations.
+
+#. When the maintenance tasks are complete, take the host out of maintenance
+ mode as follows:
+
+ #. First use vCenter to exit the vCenter maintenance mode. This makes the
+ host ready for CloudStack to reactivate it.
+
+ #. Then use CloudStack's administrator UI to cancel the CloudStack
+ maintenance mode When the host comes back online, the VMs that were
+ migrated off of it may be migrated back to it manually and new VMs can
+ be added.
+
XenServer Maintenance Mode
~~~~~~~~~~~~~~~~~~~~~~~~~~
-XenServer, you can take a server offline temporarily by using the Maintenance Mode feature in XenCenter. When you place a server into Maintenance Mode, all running VMs are automatically migrated from it to another host in the same pool. If the server is the pool master, a new master will also be selected for the pool. While a server is Maintenance Mode, you cannot create or start any VMs on it.
+XenServer, you can take a server offline temporarily by using the Maintenance
+Mode feature in XenCenter. When you place a server into Maintenance Mode, all
+running VMs are automatically migrated from it to another host in the same
+pool. If the server is the pool master, a new master will also be selected for
+the pool. While a server is Maintenance Mode, you cannot create or start any
+VMs on it.
+
To place a XenServer host in Maintenace Mode
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. In the Resources pane, select the server, then do one of the following:
- *. Right-click, then click Enter Maintenance Mode on the shortcut menu.
- *. On the Server menu, click Enter Maintenance Mode.
+
+ - Right-click, then click Enter Maintenance Mode on the shortcut menu.
+
+ - On the Server menu, click Enter Maintenance Mode.
+
#. Click Enter Maintenance Mode.
-The server's status in the Resources pane shows when all running VMs have been successfully migrated off the server.
+The server's status in the Resources pane shows when all running VMs have been
+successfully migrated off the server.
+
To take a Xenserver host out of Maintenance mode
-@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
#. In the Resources pane, select the server, then do one of the following:
- *Right-click, then click Exit Maintenance Mode on the shortcut menu.
- *On the Server menu, click Exit Maintenance Mode.
+
+ - Right-click, then click Exit Maintenance Mode on the shortcut menu.
+
+ - On the Server menu, click Exit Maintenance Mode.
+
#. Click Exit Maintenance Mode.
+
Disabling and enabling Zones, Pods, and Clusters
-________________________________________________
+------------------------------------------------
+
+You can enable or disable a zone, pod, or cluster without permanently removing
+it from the cloud. This is useful for maintenance or when there are problems
+that make a portion of the cloud infrastructure unreliable. No new allocations
+will be made to a disabled zone, pod, or cluster until its state is returned
+to Enabled. When a zone, pod, or cluster is first added to the cloud, it is
+Disabled by default.
-You can enable or disable a zone, pod, or cluster without permanently removing it from the cloud. This is useful for maintenance or when there are problems that make a portion of the cloud infrastructure unreliable. No new allocations will be made to a disabled zone, pod, or cluster until its state is returned to Enabled. When a zone, pod, or cluster is first added to the cloud, it is Disabled by default.
To disable and enable a zone, pod, or cluster:
#. Log in to the CloudStack UI as administrator
+
#. In the left navigation bar, click Infrastructure.
+
#. In Zones, click View More.
-#. If you are disabling or enabling a zone, find the name of the zone in the list, and click the Enable/Disable button.
-#. If you are disabling or enabling a pod or cluster, click the name of the zone that contains the pod or cluster.
+
+#. If you are disabling or enabling a zone, find the name of the zone in the
+ list, and click the Enable/Disable button.
+
+#. If you are disabling or enabling a pod or cluster, click the name of the
+ zone that contains the pod or cluster.
+
#. Click the Compute tab.
+
#. In the Pods or Clusters node of the diagram, click View All.
+
#. Click the pod or cluster name in the list.
+
#. Click the Enable/Disable button.
+
Removing hypervisor hosts
-_________________________
+-------------------------
+
+Hosts can be removed from the cloud as needed. The procedure to remove a host
+depends on the hypervisor type.
-Hosts can be removed from the cloud as needed. The procedure to remove a host depends on the hypervisor type.
Removing XenServer and KVM Hosts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-A node cannot be removed from a cluster until it has been placed in maintenance mode. This will ensure that all of the VMs on it have been migrated to other Hosts. To remove a Host from CloudStack:
+A node cannot be removed from a cluster until it has been placed in
+maintenance mode. This will ensure that all of the VMs on it have been
+migrated to other Hosts. To remove a Host from CloudStack:
#. Place the node in maintenance mode.
+
#. For KVM, stop the cloud-agent service.
+
#. Use the UI option to remove the node.
+
#. Then you may power down the Host, re-use its IP address, re-install it, etc
+
Removing vSphere Hosts
~~~~~~~~~~~~~~~~~~~~~~
-To remove this type of host, first place it in maintenance mode, as described above. Then use CloudStack to remove the host. CloudStack will not direct commands to a host that has been removed using CloudStack. However, the host may still exist in the vCenter cluster.
+To remove this type of host, first place it in maintenance mode, as described
+above. Then use CloudStack to remove the host. CloudStack will not direct
+commands to a host that has been removed using CloudStack. However, the host
+may still exist in the vCenter cluster.
+
Changing hypervisor host password
-_________________________________
-The password for a XenServer Node, KVM Node, or vSphere Node may be changed in the database. Note that all Nodes in a Cluster must have the same password.
+---------------------------------
+The password for a XenServer Node, KVM Node, or vSphere Node may be changed in
+the database. Note that all Nodes in a Cluster must have the same password.
+
To change a hosts password:
#. Identify all hosts in the cluster.
-#. Change the password on all hosts in the cluster. Now the password for the host and the password known to CloudStack will not match. Operations on the cluster will fail until the two passwords match.
-#. Get the list of host IDs for the host in the cluster where you are changing the password. You will need to access the database to determine these host IDs. For each hostname "h" (or vSphere cluster) that you are changing the password for, execute: ::
+
+#. Change the password on all hosts in the cluster. Now the password for the
+ host and the password known to CloudStack will not match. Operations on the
+ cluster will fail until the two passwords match.
+
+#. Get the list of host IDs for the host in the cluster where you are changing
+ the password. You will need to access the database to determine these host
+ IDs. For each hostname "h" (or vSphere cluster) that you are changing the
+ password for, execute:
+
+ ::
- mysql> select id from cloud.host where name like '%h%';
+ mysql> select id from cloud.host where name like '%h%';
+
+#. Update the passwords for the host in the database. In this example, we
+ change the passwords for hosts with IDs 5, 10, and 12 to "password".
+
+ ::
-4. Update the passwords for the host in the database. In this example, we change the passwords for hosts with IDs 5, 10, and 12 to "password".::
+ mysql> update cloud.host set password='password' where id=5 or id=10 or id=12;
- mysql> update cloud.host set password='password' where id=5 or id=10 or id=12;
Overprovisioning and Service Offering Limits
-____________________________________________
+--------------------------------------------
-CPU and memory (RAM) over-provisioning factors can be set for each cluster to change the number of VMs that can run on each host in the cluster. This helps optimize the use of resources. By increasing the over-provisioning ratio, more resource capacity will be used. If the ratio is set to 1, no over-provisioning is done.
+CPU and memory (RAM) over-provisioning factors can be set for each cluster to
+change the number of VMs that can run on each host in the cluster. This helps
+optimize the use of resources. By increasing the over-provisioning ratio, more
+resource capacity will be used. If the ratio is set to 1, no over-provisioning
+is done.
-The administrator can also set global default over-provisioning ratios in the cpu.overprovisioning.factor and mem.overprovisioning.factor global configuration variables. The default value of these variables is 1: over-provisioning is turned off by default.
-Over-provisioning ratios are dynamically substituted in CloudStack's capacity calculations. For example:::
+The administrator can also set global default over-provisioning ratios in the
+cpu.overprovisioning.factor and mem.overprovisioning.factor global
+configuration variables. The default value of these variables is 1:
+over-provisioning is turned off by default.
+Over-provisioning ratios are dynamically substituted in CloudStack's capacity
+calculations. For example:
+
+::
Capacity = 2 GB
Over-provisioning factor = 2
@@ -364,80 +723,147 @@ Over-provisioning ratios are dynamically substituted in CloudStack's capacity ca
Used = 3 GB
Free = 1 GB
-The administrator can specify a memory over-provisioning ratio, and can specify both CPU and memory over-provisioning ratios on a per-cluster basis.
-In any given cloud, the optimum number of VMs for each host is affected by such things as the hypervisor, storage, and hardware configuration. These may be different for each cluster in the same cloud. A single global over-provisioning setting can not provide the best utilization for all the different clusters in the cloud. It has to be set for the lowest common denominator. The per-cluster setting provides a finer granularity for better utilization of resources, no matter where the CloudStack placement algorithm decides to place a VM.
+The administrator can specify a memory over-provisioning ratio, and can
+specify both CPU and memory over-provisioning ratios on a per-cluster basis.
+
+In any given cloud, the optimum number of VMs for each host is affected by
+such things as the hypervisor, storage, and hardware configuration. These may
+be different for each cluster in the same cloud. A single global
+over-provisioning setting can not provide the best utilization for all the
+different clusters in the cloud. It has to be set for the lowest common
+denominator. The per-cluster setting provides a finer granularity for better
+utilization of resources, no matter where the CloudStack placement algorithm
+decides to place a VM.
-The overprovisioning settings can be used along with dedicated resources (assigning a specific cluster to an account) to effectively offer different levels of service to different accounts. For example, an account paying for a more expensive level of service could be assigned to a dedicated cluster with an over-provisioning ratio of 1, and a lower-paying account to a cluster with a ratio of 2.
+The overprovisioning settings can be used along with dedicated resources
+(assigning a specific cluster to an account) to effectively offer different
+levels of service to different accounts. For example, an account paying for a
+more expensive level of service could be assigned to a dedicated cluster with
+an over-provisioning ratio of 1, and a lower-paying account to a cluster with
+a ratio of 2.
+
+When a new host is added to a cluster, CloudStack will assume the host has the
+capability to perform the CPU and RAM over-provisioning which is configured
+for that cluster. It is up to the administrator to be sure the host is
+actually suitable for the level of over-provisioning which has been set.
-When a new host is added to a cluster, CloudStack will assume the host has the capability to perform the CPU and RAM over-provisioning which is configured for that cluster. It is up to the administrator to be sure the host is actually suitable for the level of over-provisioning which has been set.
Limitations on over-provisioning in KVM and XenServer
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-In XenServer, due to a constraint of this hypervisor, you can not use an over-provisioning factor greater than 4.
+In XenServer, due to a constraint of this hypervisor, you can not use an
+over-provisioning factor greater than 4.
+
+KVM can not manage memory allocation to VMs dynamically. CloudStack sets the
+minimum and maximum amount of memory that a VM can use. The hypervisor adjusts
+the memory within the set limits based on the memory contention.
-KVM can not manage memory allocation to VMs dynamically. CloudStack sets the minimum and maximum amount of memory that a VM can use. The hypervisor adjusts the memory within the set limits based on the memory contention.
Requirements for Over-Provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several prerequisites are required in order for over-provisioning to function properly. The feature is dependent on the OS type, hypervisor capabilities, and certain scripts. It is the administrator's responsibility to ensure that these requirements are met.
+Several prerequisites are required in order for over-provisioning to function
+properly. The feature is dependent on the OS type, hypervisor capabilities,
+and certain scripts. It is the administrator's responsibility to ensure that
+these requirements are met.
+
Balloon Driver
-@@@@@@@@@@@@@@
+^^^^^^^^^^^^^^
+
+All VMs should have a balloon driver installed in them. The hypervisor
+communicates with the balloon driver to free up and make the memory available
+to a VM.
-All VMs should have a balloon driver installed in them. The hypervisor communicates with the balloon driver to free up and make the memory available to a VM.
XenServer
-#########
+'''''''''
+
+The balloon driver can be found as a part of xen pv or PVHVM drivers. The xen
+pvhvm drivers are included in upstream linux kernels 2.6.36+.
-The balloon driver can be found as a part of xen pv or PVHVM drivers. The xen pvhvm drivers are included in upstream linux kernels 2.6.36+.
VMware
-######
+''''''
+
+The balloon driver can be found as a part of the VMware tools. All the VMs
+that are deployed in a over-provisioned cluster should have the VMware tools
+installed.
-The balloon driver can be found as a part of the VMware tools. All the VMs that are deployed in a over-provisioned cluster should have the VMware tools installed.
KVM
-####
+'''
+
+All VMs are required to support the virtio drivers. These drivers are
+installed in all Linux kernel versions 2.6.25 and greater. The administrator
+must set CONFIG_VIRTIO_BALLOON=y in the virtio configuration.
-All VMs are required to support the virtio drivers. These drivers are installed in all Linux kernel versions 2.6.25 and greater. The administrator must set CONFIG_VIRTIO_BALLOON=y in the virtio configuration.
Hypervisor capabilities
-@@@@@@@@@@@@@@@@@@@@@@@
+^^^^^^^^^^^^^^^^^^^^^^^
The hypervisor must be capable of using the memory ballooning.
+
XenServer
-#########
+'''''''''
+
+The DMC (Dynamic Memory Control) capability of the hypervisor should be
+enabled. Only XenServer Advanced and above versions have this feature.
-The DMC (Dynamic Memory Control) capability of the hypervisor should be enabled. Only XenServer Advanced and above versions have this feature.
VMware, KVM
-###########
+'''''''''''
Memory ballooning is supported by default.
+
Setting Over-Provisioning Rations
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-There are two ways the root admin can set CPU and RAM over-provisioning ratios. First, the global configuration settings cpu.overprovisioning.factor and mem.overprovisioning.factor will be applied when a new cluster is created. Later, the ratios can be modified for an existing cluster.
+There are two ways the root admin can set CPU and RAM over-provisioning ratios.
+First, the global configuration settings cpu.overprovisioning.factor and
+mem.overprovisioning.factor will be applied when a new cluster is created.
+Later, the ratios can be modified for an existing cluster.
-Only VMs deployed after the change are affected by the new setting. If you want VMs deployed before the change to adopt the new over-provisioning ratio, you must stop and restart the VMs. When this is done, CloudStack recalculates or scales the used and reserved capacities based on the new over-provisioning ratios, to ensure that CloudStack is correctly tracking the amount of free capacity.
+Only VMs deployed after the change are affected by the new setting. If you
+want VMs deployed before the change to adopt the new over-provisioning ratio,
+you must stop and restart the VMs. When this is done, CloudStack recalculates
+or scales the used and reserved capacities based on the new over-provisioning
+ratios, to ensure that CloudStack is correctly tracking the amount of free
+capacity.
To change the over-provisioning ratios for an existing cluster:
#. Log in as administrator to the CloudStack UI.
+
#. In the left navigation bar, click Infrastructure.
+
#. Under Clusters, click View All.
-#. Select the cluster you want to work with, and click the Edit button.
-#. Fill in your desired over-provisioning multipliers in the fields CPU overcommit ratio and RAM overcommit ratio. The value which is intially shown in these fields is the default value inherited from the global configuration settings.
-Service Offering Limits and Over-Provisioning
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Select the cluster you want to work with, and click the Edit button.
-Service offering limits (e.g. 1 GHz, 1 core) are strictly enforced for core count. For example, a guest with a service offering of one core will have only one core available to it regardless of other activity on the Host.
+#. Fill in your desired over-provisioning multipliers in the fields CPU
+ overcommit ratio and RAM overcommit ratio. The value which is intially
+ shown in these fields is the default value inherited from the global
+ configuration settings.
-Service offering limits for gigahertz are enforced only in the presence of contention for CPU resources. For example, suppose that a guest was created with a service offering of 1 GHz on a Host that has 2 GHz cores, and that guest is the only guest running on the Host. The guest will have the full 2 GHz available to it. When multiple guests are attempting to use the CPU a weighting factor is used to schedule CPU resources. The weight is based on the clock speed in the service offering. Guests receive a CPU allocation that is proportionate to the GHz in the service offering. For example, a guest created from a 2 GHz service offering will receive twice the CPU allocation as a guest created from a 1 GHz service offering. CloudStack does not perform memory over-provisioning.
+Service Offering Limits and Over-Provisioning
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Service offering limits (e.g. 1 GHz, 1 core) are strictly enforced for core
+count. For example, a guest with a service offering of one core will have only
+one core available to it regardless of other activity on the Host.
+
+Service offering limits for gigahertz are enforced only in the presence of
+contention for CPU resources. For example, suppose that a guest was created
+with a service offering of 1 GHz on a Host that has 2 GHz cores, and that
+guest is the only guest running on the Host. The guest will have the full
+2 GHz available to it. When multiple guests are attempting to use the CPU a
+weighting factor is used to schedule CPU resources. The weight is based on the
+clock speed in the service offering. Guests receive a CPU allocation that is
+proportionate to the GHz in the service offering. For example, a guest created
+from a 2 GHz service offering will receive twice the CPU allocation as a guest
+created from a 1 GHz service offering. CloudStack does not perform memory
+over-provisioning.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/alloc.rst
----------------------------------------------------------------------
diff --git a/rtd/source/alloc.rst b/rtd/source/alloc.rst
index f5fd1bf..00ce8c9 100644
--- a/rtd/source/alloc.rst
+++ b/rtd/source/alloc.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
Allocators
==========
@@ -14,12 +30,14 @@ These are following categories of allocators currently supported:
determine which storage pool to allocate the guest virtual machines
on.
+
Implementing a custom HostAllocator
-----------------------------------
HostAllocators are written by extending
com.cloud.agent.manager.allocator.HostAllocator interface.
+
HostAllocator Interface
~~~~~~~~~~~~~~~~~~~~~~~
@@ -27,32 +45,32 @@ The interface defines the following two methods.
::
- /**
- * Checks if the VM can be upgraded to the specified ServiceOffering
- * @param UserVm vm
- * @param ServiceOffering offering
- * @return boolean true if the VM can be upgraded
- **/
-
- publicboolean isVirtualMachineUpgradable(final UserVm vm, final ServiceOffering offering);
-
- /**
- * Determines which physical hosts are suitable to allocate the guest virtual machines on
- *
- * @paramVirtualMachineProfile vmProfile
- * @paramDeploymentPlan plan
- * @paramType type
- * @paramExcludeList avoid
- * @paramint returnUpTo
- * @returnList<Host>List of hosts that are suitable for VM allocation
- **/
-
- publicList<Host> allocateTo( VirtualMachineProfile<?extendsVirtualMachine> vmProfile, DeploymentPlan plan, Type type, ExcludeList avoid, intreturnUpTo);
-
+ /**
+ * Checks if the VM can be upgraded to the specified ServiceOffering
+ * @param UserVm vm
+ * @param ServiceOffering offering
+ * @return boolean true if the VM can be upgraded
+ **/
+
+ publicboolean isVirtualMachineUpgradable(final UserVm vm, final ServiceOffering offering);
+
+ /**
+ * Determines which physical hosts are suitable to allocate the guest virtual machines on
+ *
+ * @paramVirtualMachineProfile vmProfile
+ * @paramDeploymentPlan plan
+ * @paramType type
+ * @paramExcludeList avoid
+ * @paramint returnUpTo
+ * @returnList<Host>List of hosts that are suitable for VM allocation
+ **/
+
+ publicList<Host> allocateTo( VirtualMachineProfile<?extendsVirtualMachine> vmProfile, DeploymentPlan plan, Type type, ExcludeList avoid, intreturnUpTo);
A custom HostAllocator can be written by implementing the ‘allocateTo’
method
+
Input Parameters for the method ‘HostAllocator :: allocateTo’
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -124,6 +142,7 @@ This specifies return up to that many available hosts for this guest VM.
To get all possible hosts, set this value to -1.
+
Reference HostAllocator implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -135,31 +154,33 @@ given ServiceOffering requirements.
If returnUpTo = 1, this allocator would return the first Host that fits
the requirements of the guest VM.
+
Loading a custom HostAllocator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-1. Write a custom HostAllocator class, implementing the interface
+#. Write a custom HostAllocator class, implementing the interface
described above.
-2. Package the code into a JAR file and make the JAR available in the
+#. Package the code into a JAR file and make the JAR available in the
classpath of the Management Server/tomcat.
-3. Modify the components.xml and components-premium.xml files found in
+#. Modify the components.xml and components-premium.xml files found in
/client/ tomcatconf as follows.
-4. Search for ‘HostAllocator’ in these files.
+#. Search for ‘HostAllocator’ in these files.
::
- <adapters key="com.cloud.agent.manager.allocator.HostAllocator">
- <adapter name="FirstFit" class="com.cloud.agent.manager.allocator.impl.FirstFitAllocator"/>
- </adapters>
+ <adapters key="com.cloud.agent.manager.allocator.HostAllocator">
+ <adapter name="FirstFit" class="com.cloud.agent.manager.allocator.impl.FirstFitAllocator"/>
+ </adapters>
-5. Replace the FirstFitAllocator with your class name. Optionally, you
+#. Replace the FirstFitAllocator with your class name. Optionally, you
can change the name of the adapter as well.
-6. Restart the Management Server.
+#. Restart the Management Server.
+
Implementing a custom StoragePoolAllocator
------------------------------------------
@@ -167,6 +188,7 @@ Implementing a custom StoragePoolAllocator
StoragePoolAllocators are written by extending
com.cloud.storage.allocator. StoragePoolAllocator interface.
+
StoragePoolAllocator Interface
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -175,17 +197,17 @@ A custom StoragePoolAllocator can be written by implementing the
::
- /**
- * Determines which storage pools are suitable for the guest virtual machine
- * @param DiskProfile dskCh
- * @param VirtualMachineProfile vmProfile
- * @param DeploymentPlan plan
- * @param ExcludeList avoid
- * @param int returnUpTo
- * @return List<StoragePool> List of storage pools that are suitable for the VM
- **/
-
- public List<StoragePool> allocateToPool(DiskProfile dskCh, VirtualMachineProfile<? extends VirtualMachine> vm, DeploymentPlan plan, ExcludeList avoid, int returnUpTo);
+ /**
+ * Determines which storage pools are suitable for the guest virtual machine
+ * @param DiskProfile dskCh
+ * @param VirtualMachineProfile vmProfile
+ * @param DeploymentPlan plan
+ * @param ExcludeList avoid
+ * @param int returnUpTo
+ * @return List<StoragePool> List of storage pools that are suitable for the VM
+ **/
+
+ public List<StoragePool> allocateToPool(DiskProfile dskCh, VirtualMachineProfile<? extends VirtualMachine> vm, DeploymentPlan plan, ExcludeList avoid, int returnUpTo);
This interface also contains some other methods to support some legacy
@@ -193,6 +215,7 @@ code. However your custom allocator can extend the existing
com.cloud.storage.allocator. AbstractStoragePoolAllocator. This class
provides default implementation for all the other interface methods.
+
Input Parameters for the method ‘StoragePoolAllocator :: allocateTo’
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -253,6 +276,7 @@ This specifies return up to that many available pools for this guest VM
To get all possible pools, set this value to -1
+
Reference StoragePoolAllocator implementation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -264,19 +288,20 @@ considering the given DiskProfile characteristics.
If returnUpTo = 1, this allocator would return the first Storage Pool
that fits the requirements of the guest VM.
+
Loading a custom StoragePoolAllocator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-1. Write a custom StoragePoolAllocator class, implementing the interface
+#. Write a custom StoragePoolAllocator class, implementing the interface
described above.
-2. Package the code into a JAR file and make the JAR available in the
+#. Package the code into a JAR file and make the JAR available in the
classpath of the Management Server/tomcat.
-3. Modify the components.xml and components-premium.xml files found in
+#. Modify the components.xml and components-premium.xml files found in
/client/ tomcatconf as follows.
-4. Search for ‘StoragePoolAllocator’ in these files.
+#. Search for ‘StoragePoolAllocator’ in these files.
::
@@ -284,9 +309,7 @@ Loading a custom StoragePoolAllocator
<adapter name="Storage" class="com.cloud.storage.allocator.FirstFitStoragePoolAllocator"/>
</adapters>
-5. Replace the FirstFitStoragePoolAllocator with your class name.
+#. Replace the FirstFitStoragePoolAllocator with your class name.
Optionally, you can change the name of the adapter as well.
-6. Restart the Management Server.
-
-
+#. Restart the Management Server.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/ansible.rst
----------------------------------------------------------------------
diff --git a/rtd/source/ansible.rst b/rtd/source/ansible.rst
index 7f0f9bd..18b19fb 100644
--- a/rtd/source/ansible.rst
+++ b/rtd/source/ansible.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
Deploying CloudStack with Ansible
=================================
@@ -5,6 +21,7 @@ In this article, `Paul Angus <https://twitter.com/CloudyAngus>`__ Cloud
Architect at ShapeBlue takes a look at using Ansible to Deploy an
Apache CloudStack cloud.
+
What is Ansible
---------------
@@ -17,6 +34,7 @@ Like Chef and Puppet, Ansible is designed to be idempotent, these means
that you determine the state you want a host to be in and Ansible will
decide if it needs to act in order to achieve that state.
+
There’s already Chef and Puppet, so what’s the fuss about Ansible?
------------------------------------------------------------------
@@ -44,6 +62,7 @@ found it a bit tricky to get the syntax correct for variables in some
circumstances, but otherwise I’ve found it one of the easier tools to
get my head around.
+
So let’s see something
----------------------
@@ -51,6 +70,7 @@ For this example we’re going to create an Ansible server which will then
deploy a CloudStack server. Both of these servers will be CentOS 6.4
virtual machines.
+
Installing Ansible
------------------
@@ -60,8 +80,8 @@ server.
::
- # rpm -ivh http://www.mirrorservice.org/sites/dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
- # yum install -y ansible
+ # rpm -ivh http://www.mirrorservice.org/sites/dl.fedoraproject.org/pub/epel/6/i386/epel-release-6-8.noarch.rpm
+ # yum install -y ansible
And that’s it.
@@ -82,6 +102,7 @@ Ansible uses playbooks to specify the state in which you wish the target
host to be in to be able to accomplish its role. Ansible playbooks are
written in YAML format.
+
Modules
-------
@@ -100,11 +121,15 @@ to do exactly that.
The pre-requisites to this CloudStack build are:
- A CentOS 6.4 host to install CloudStack on
+
- An IP address already assigned on the ACS management host
+
- The ACS management host should have a resolvable FQDN (either through
DNS or the host file on the ACS management host)
+
- Internet connectivity on the ACS management host
+
Planning
--------
@@ -113,11 +138,16 @@ group them or split them into logical blocks. So for this deployment of
CloudStack I’d start with:
- Configure selinux
+
- (libselinux-python required for Ansible to work with selinux enabled
hosts)
+
- Install and configure MySQL
+
- (Python MySQL-DB required for Ansible MySQL module)
+
- Install cloud-client
+
- Seed secondary storage
Ansible is built around the idea of hosts having roles, so generally you
@@ -127,6 +157,7 @@ roles for these tasks
I’ve created:
- cloudstack-manager
+
- mysql
First up we need to tell Ansible where to find our CloudStack management
@@ -135,11 +166,12 @@ host. In the root Ansible directory there is a file called ‘hosts’
::
- [acs-manager]
- xxx.xxx.xxx.xxx
+ [acs-manager]
+ xxx.xxx.xxx.xxx
where xxx.xxx.xxx.xxx is the ip address of your ACS management host.
+
MySQL
-----
@@ -150,59 +182,59 @@ the file will look like this:
::
- -name: Ensure mysql server is installed
+ -name: Ensure mysql server is installed
- yum: name=mysql-server state=present
+ yum: name=mysql-server state=present
- - name: Ensure mysql python is installed
+ - name: Ensure mysql python is installed
- yum: name=MySQL-python state=present
+ yum: name=MySQL-python state=present
- - name: Ensure selinux python bindings are installed
+ - name: Ensure selinux python bindings are installed
- yum: name=libselinux-python state=present
+ yum: name=libselinux-python state=present
- - name: Ensure cloudstack specfic my.cnf lines are present
+ - name: Ensure cloudstack specfic my.cnf lines are present
- lineinfile: dest=/etc/my.cnf regexp=’$item’ insertafter=”symbolic-links=0″ line=’$item’
+ lineinfile: dest=/etc/my.cnf regexp=’$item’ insertafter=”symbolic-links=0″ line=’$item’
- with\_items:
+ with\_items:
- – skip-name-resolve
+ – skip-name-resolve
- – default-time-zone=’+00:00′
+ – default-time-zone=’+00:00′
- – innodb\_rollback\_on\_timeout=1
+ – innodb\_rollback\_on\_timeout=1
- – innodb\_lock\_wait\_timeout=600
+ – innodb\_lock\_wait\_timeout=600
- – max\_connections=350
+ – max\_connections=350
- – log-bin=mysql-bin
+ – log-bin=mysql-bin
- – binlog-format = ‘ROW’
+ – binlog-format = ‘ROW’
- - name: Ensure MySQL service is started
+ - name: Ensure MySQL service is started
- service: name=mysqld state=started
+ service: name=mysqld state=started
- - name: Ensure MySQL service is enabled at boot
+ - name: Ensure MySQL service is enabled at boot
- service: name=mysqld enabled=yes
+ service: name=mysqld enabled=yes
-
+
- - name: Ensure root password is set
+ - name: Ensure root password is set
- mysql\_user: user=root password=$mysql\_root\_password host=localhost
+ mysql\_user: user=root password=$mysql\_root\_password host=localhost
- ignore\_errors: true
+ ignore\_errors: true
- - name: Ensure root has sufficient privileges
+ - name: Ensure root has sufficient privileges
- mysql\_user: login\_user=root login\_password=$mysql\_root\_password user=root host=% password=$mysql\_root\_password priv=\*.\*:GRANT,ALL state=present
+ mysql\_user: login\_user=root login\_password=$mysql\_root\_password user=root host=% password=$mysql\_root\_password priv=\*.\*:GRANT,ALL state=present
This needs to be saved as `/etc/ansible/roles/mysql/tasks/main.yml`
@@ -235,34 +267,34 @@ For the management server role we create a main.yml task like this:
::
- - name: Ensure selinux python bindings are installed
+ - name: Ensure selinux python bindings are installed
- yum: name=libselinux-python state=present
+ yum: name=libselinux-python state=present
- - name: Ensure the Apache Cloudstack Repo file exists as per template
+ - name: Ensure the Apache Cloudstack Repo file exists as per template
- template: src=cloudstack.repo.j2 dest=/etc/yum.repos.d/cloudstack.repo
+ template: src=cloudstack.repo.j2 dest=/etc/yum.repos.d/cloudstack.repo
- - name: Ensure selinux is in permissive mode
+ - name: Ensure selinux is in permissive mode
- command: setenforce permissive
+ command: setenforce permissive
- - name: Ensure selinux is set permanently
+ - name: Ensure selinux is set permanently
- selinux: policy=targeted state=permissive
+ selinux: policy=targeted state=permissive
- -name: Ensure CloudStack packages are installed
+ -name: Ensure CloudStack packages are installed
- yum: name=cloud-client state=present
+ yum: name=cloud-client state=present
- - name: Ensure vhdutil is in correct location
+ - name: Ensure vhdutil is in correct location
- get\_url: url=http://download.cloud.com.s3.amazonaws.com/tools/vhd-util dest=/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/vhd-util mode=0755
+ get\_url: url=http://download.cloud.com.s3.amazonaws.com/tools/vhd-util dest=/usr/share/cloudstack-common/scripts/vm/hypervisor/xenserver/vhd-util mode=0755
Save this as `/etc/ansible/roles/cloudstack-management/tasks/main.yml`
@@ -274,24 +306,25 @@ it, so it would simply look like this:
::
- [cloudstack]
- name=cloudstack
- baseurl=http://cloudstack.apt-get.eu/rhel/4.2/
- enabled=1
- gpgcheck=0
+ [cloudstack]
+ name=cloudstack
+ baseurl=http://cloudstack.apt-get.eu/rhel/4.2/
+ enabled=1
+ gpgcheck=0
-This is saved in `/etc/ansible/roles/cloudstack-manager/templates/cloudstack.repo.j2`
+This is saved in
+`/etc/ansible/roles/cloudstack-manager/templates/cloudstack.repo.j2`
That gives us the packages installed, we need to set up the database. To
do this I’ve created a separate task called setupdb.yml
::
- - name: cloudstack-setup-databases
- command: /usr/bin/cloudstack-setup-databases cloud:{{mysql\_cloud\_password }}@localhost –deploy-as=root:{{mysql\_root\_password }}
+ - name: cloudstack-setup-databases
+ command: /usr/bin/cloudstack-setup-databases cloud:{{mysql\_cloud\_password }}@localhost –deploy-as=root:{{mysql\_root\_password }}
- - name: Setup CloudStack manager
- command: /usr/bin/cloudstack-setup-management
+ - name: Setup CloudStack manager
+ command: /usr/bin/cloudstack-setup-management
Save this as: `/etc/ansible/roles/cloudstack-management/tasks/setupdb.yml`
@@ -307,34 +340,33 @@ There are some more variables here for us to declare later.
System VM Templates:
--------------------
-
Finally we would want to seed the system VM templates into the secondary
storage. The playbook for this would look as follows:
::
- - name: Ensure secondary storage mount exists
- file: path={{ tmp\_nfs\_path }} state=directory
+ - name: Ensure secondary storage mount exists
+ file: path={{ tmp\_nfs\_path }} state=directory
- - name: Ensure NFS storage is mounted
- mount: name={{ tmp\_nfs\_path }} src={{ sec\_nfs\_ip }}:{{sec\_nfs\_path }} fstype=nfs state=mounted opts=nolock
+ - name: Ensure NFS storage is mounted
+ mount: name={{ tmp\_nfs\_path }} src={{ sec\_nfs\_ip }}:{{sec\_nfs\_path }} fstype=nfs state=mounted opts=nolock
- - name: Seed secondary storage
- command:
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2 -h kvm -F
+ - name: Seed secondary storage
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-06-12-master-kvm.qcow2.bz2 -h kvm -F
- command:
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 -h xenserver -F
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-2013-07-12-master-xen.vhd.bz2 -h xenserver -F
- command:
- /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-4.2-vh7.ov -h vmware -F
+ command:
+ /usr/share/cloudstack-common/scripts/storage/secondary/cloud-install-sys-tmplt -m {{ tmp\_nfs\_path }} -u http://download.cloud.com/templates/4.2/systemvmtemplate-4.2-vh7.ov -h vmware -F
Save this as `/etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml`
- Again, there isn’t a CloudStack module so Ansible will always run this
+Again, there isn’t a CloudStack module so Ansible will always run this
even if the secondary storage already has the templates in it.
@@ -348,46 +380,43 @@ called deploy-cloudstack.yml, which would look like this:
::
- -hosts: acs-manager
+ -hosts: acs-manager
- vars:
+ vars:
- mysql\_root\_password: Cl0ud5tack
- mysql\_cloud\_password: Cl0ud5tack
- tmp\_nfs\_path: /mnt/secondary
- sec\_nfs\_ip: IP\_OF\_YOUR\_SECONDARY\_STORAGE
- sec\_nfs\_path: PATH\_TO\_YOUR\_SECONDARY\_STORAGE\_MOUNT
+ mysql\_root\_password: Cl0ud5tack
+ mysql\_cloud\_password: Cl0ud5tack
+ tmp\_nfs\_path: /mnt/secondary
+ sec\_nfs\_ip: IP\_OF\_YOUR\_SECONDARY\_STORAGE
+ sec\_nfs\_path: PATH\_TO\_YOUR\_SECONDARY\_STORAGE\_MOUNT
- roles:
+ roles:
- – mysql
- – cloudstack-manager
+ – mysql
+ – cloudstack-manager
- tasks:
+ tasks:
- – include: /etc/ansible/roles/cloudstack-manager/tasks/setupdb.yml
- – include: /etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml
+ – include: /etc/ansible/roles/cloudstack-manager/tasks/setupdb.yml
+ – include: /etc/ansible/roles/cloudstack-manager/tasks/seedstorage.yml
Save this as `/etc/ansible/deploy-cloudstack.yml` inserting the IP
address and path for your secondary storage and changing the passwords
if you wish to.
-
-
To run this go to the Ansible directory (cd /etc/ansible ) and run:
::
- # ansible-playbook deploy-cloudstack.yml -k
+ # ansible-playbook deploy-cloudstack.yml -k
- ‘-k’ tells Ansible to ask you for the root password to connect to the
+‘-k’ tells Ansible to ask you for the root password to connect to the
remote host.
- Now log in to the CloudStack UI on the new management server.
+Now log in to the CloudStack UI on the new management server.
-
How is this example different from a production deployment?
-----------------------------------------------------------
[3/4] fixed the formatting in all the files and added the license to
each file: This closes #4
Posted by se...@apache.org.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/concepts.rst
----------------------------------------------------------------------
diff --git a/rtd/source/concepts.rst b/rtd/source/concepts.rst
index 5860aa4..93a1fe7 100644
--- a/rtd/source/concepts.rst
+++ b/rtd/source/concepts.rst
@@ -13,6 +13,7 @@
specific language governing permissions and limitations
under the License.
+
Concepts and Terminology
========================
@@ -25,8 +26,10 @@ build a public or private IaaS compute cloud.
With CloudStack you can:
-* Set up an on-demand elastic cloud computing service.
-* Allow end-users to provision resources
+- Set up an on-demand elastic cloud computing service.
+
+- Allow end-users to provision resources
+
What can Apache CloudStack do?
------------------------------
@@ -34,117 +37,171 @@ What can Apache CloudStack do?
Multiple Hypervisor Support
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-CloudStack works with a variety of hypervisors and hypervisor-like technologies. A single
-cloud can contain multiple hypervisor implementations. As of the current release CloudStack
-supports:
+CloudStack works with a variety of hypervisors and hypervisor-like
+technologies. A single cloud can contain multiple hypervisor implementations.
+As of the current release CloudStack supports:
+
+- BareMetal (via IPMI)
+
+- Hyper-V
+
+- KVM
+
+- LXC
+
+- vSphere (via vCenter)
+
+- Xenserver
+
+- Xen Project
-* BareMetal (via IPMI)
-* Hyper-V
-* KVM
-* LXC
-* vSphere (via vCenter)
-* Xenserver
-* Xen Project
Massively Scalable Infrastructure Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-CloudStack can manage tens of thousands of physical servers installed in geographically
-distributed datacenters. The management server scales near-linearly eliminating the need
-for cluster-level management servers. Maintenance or other outages of the management server
-can occur without affecting the virtual machines running in the cloud.
+CloudStack can manage tens of thousands of physical servers installed in
+geographically distributed datacenters. The management server scales
+near-linearly eliminating the need for cluster-level management servers.
+Maintenance or other outages of the management server can occur without
+affecting the virtual machines running in the cloud.
+
Automatic Cloud Configuration Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-CloudStack automatically configures the network and storage settings for each virtual machine deployment.
-Internally, a pool of virtual appliances support the operation of configuration of the cloud itself. These
-appliances offer services such as firewalling, routing, DHCP, VPN, console proxy, storage acces, and
-storage replication. The extensive use of horizontally scalable virtual machines simplifies the installation
-and ongoing operation of a cloud.
+CloudStack automatically configures the network and storage settings for each
+virtual machine deployment. Internally, a pool of virtual appliances support
+the operation of configuration of the cloud itself. These appliances offer
+services such as firewalling, routing, DHCP, VPN, console proxy, storage
+acces, and storage replication. The extensive use of horizontally scalable
+virtual machines simplifies the installation and ongoing operation of a cloud.
+
Graphical User Interface
~~~~~~~~~~~~~~~~~~~~~~~~
-CloudStack offers an administrators web interface used for provisioning and managing the cloud, as well as
-an end-user's Web interface, used for running VMs and managing VM templates. The UI can be customized to
-reflect the desired service provider or enterprise look and feel.
+CloudStack offers an administrators web interface used for provisioning and
+managing the cloud, as well as an end-user's Web interface, used for running
+VMs and managing VM templates. The UI can be customized to reflect the desired
+service provider or enterprise look and feel.
+
API
~~~
-CloudStack provides a REST-like API for the operation, management and use of the cloud.
+CloudStack provides a REST-like API for the operation, management and use of
+the cloud.
+
AWS EC2 API Support
~~~~~~~~~~~~~~~~~~~
-CloudStack provides an EC2 API translation layer to permit the common EC2 tools to be used in the use of
-a CloudStack cloud.
+CloudStack provides an EC2 API translation layer to permit the common EC2
+tools to be used in the use of a CloudStack cloud.
+
High Availability
~~~~~~~~~~~~~~~~~
-CloudStack has a number of features to increase the availability of the system. The Management Server
-itself may be deployed in a multi-node installation where the servers are load balanced. MySQL may be
-configured to use replication to provide for failover in the event of database loss. For the
-hosts, CloudStack supports NIC bonding and the use of separate networks for storage as well as iSCSI Multipath.
+CloudStack has a number of features to increase the availability of the
+system. The Management Server itself may be deployed in a multi-node
+installation where the servers are load balanced. MySQL may be configured to
+use replication to provide for failover in the event of database loss. For the
+hosts, CloudStack supports NIC bonding and the use of separate networks for
+storage as well as iSCSI Multipath.
+
Deployment Architecture Overview
--------------------------------
-Generally speaking, most CloudStack deployments consist of the management server and the resources to be managed.
-During deployment you inform the management server of the resources to be managed, such as IP address blocks, storage devices,
-hypervisors, and VLANs.
+Generally speaking, most CloudStack deployments consist of the management
+server and the resources to be managed. During deployment you inform the
+management server of the resources to be managed, such as IP address blocks,
+storage devices, hypervisors, and VLANs.
-The minimum installation consists of one machine running the CloudStack Management Server and another machine
-to act as the cloud infrastructure (in this case, a very simple infrastructure consisting of one host running
-hypervisor software). In its smallest deployment, a single machine can act as both the Management Server and
-the hypervisor host (using the KVM hypervisor).
+The minimum installation consists of one machine running the CloudStack
+Management Server and another machine to act as the cloud infrastructure (in
+this case, a very simple infrastructure consisting of one host running
+hypervisor software). In its smallest deployment, a single machine can act as
+both the Management Server and the hypervisor host (using the KVM hypervisor).
.. image:: _static/images/basic-deployment.png
-A more full-featured installation consists of a highly-available multi-node Management Server installation and
-up to tens of thousands of hosts using any of severa networking technologies.
+A more full-featured installation consists of a highly-available multi-node
+Management Server installation and up to tens of thousands of hosts using any
+of severa networking technologies.
+
Management Server Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~
-The management server orchestrates and allocates the resources in your cloud deployment.
+The management server orchestrates and allocates the resources in your cloud
+deployment.
-The management server typically runs on a dedicated machine or as a virtual machine. It controls allocation of
-virtual machines to hosts and assigns storage and IP addresses to the virtual machine instances. The Management
-Server runs in an Apache Tomcat container and requires a MySQL database for persistence.
+The management server typically runs on a dedicated machine or as a virtual
+machine. It controls allocation of virtual machines to hosts and assigns
+storage and IP addresses to the virtual machine instances. The Management
+Server runs in an Apache Tomcat container and requires a MySQL database for
+persistence.
The management server:
-* Provides the web interface for both the adminstrator and end user.
-* Provides the API interfaces for both the CloudStack API as well as the EC2 interface.
-* Manages the assignment of guest VMs to a specific compute resource
-* Manages the assignment of public and private IP addresses.
-* Allocates storage during the VM instantiation process.
-* Manages snapshots, disk images (templates), and ISO images.
-* Provides a single point of configuration for your cloud.
+- Provides the web interface for both the adminstrator and end user.
+
+- Provides the API interfaces for both the CloudStack API as well as the EC2
+ interface.
+
+- Manages the assignment of guest VMs to a specific compute resource
+
+- Manages the assignment of public and private IP addresses.
+
+- Allocates storage during the VM instantiation process.
+
+- Manages snapshots, disk images (templates), and ISO images.
+
+- Provides a single point of configuration for your cloud.
+
Cloud Infrastructure Overview
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Resources within the cloud are managed as follows:
-* Regions: A collection of one or more geographically proximate zones managed by one or more management servers.
-* Zones: Typically, a zone is equivalent to a single datacenter. A zone consists of one or more pods and secondary storage.
-* Pods: A pod is usually a rack, or row of racks that includes a layer-2 switch and one or more clusters.
-* Clusters: A cluster consists of one or more homogenous hosts and primary storage.
-* Host: A single compute node within a cluster; often a hypervisor.
-* Primary Storage: A storage resource typically provided to a single cluster for the actual running of instance disk images. (Zone-wide primary storage is an option, though not typically used.)
-* Secondary Storage: A zone-wide resource which stores disk templates, ISO images, and snapshots.
+- Regions: A collection of one or more geographically proximate zones managed
+ by one or more management servers.
+
+- Zones: Typically, a zone is equivalent to a single datacenter. A zone
+ consists of one or more pods and secondary storage.
+
+- Pods: A pod is usually a rack, or row of racks that includes a layer-2
+ switch and one or more clusters.
+
+- Clusters: A cluster consists of one or more homogenous hosts and primary
+ storage.
+
+- Host: A single compute node within a cluster; often a hypervisor.
+
+- Primary Storage: A storage resource typically provided to a single cluster
+ for the actual running of instance disk images. (Zone-wide primary storage
+ is an option, though not typically used.)
+
+- Secondary Storage: A zone-wide resource which stores disk templates, ISO
+ images, and snapshots.
+
Networking Overview
~~~~~~~~~~~~~~~~~~~
-CloudStack offers many types of networking, but they typically fall into one of two scenarios:
+CloudStack offers many types of networking, but they typically fall into one
+of two scenarios:
+
+- Basic: Most analogous to AWS-classic style networking. Provides a single
+ flat layer-2 network where guest isolation is provided at layer-3 by the
+ hypervisors bridge device.
+
+- Advanced: This typically uses layer-2 isolation such as VLANs, though this
+ category also includes SDN technologies such as Nicira NVP.
-* Basic: Most analogous to AWS-classic style networking. Provides a single flat layer-2 network where guest isolation is provided at layer-3 by the hypervisors bridge device.
-* Advanced: This typically uses layer-2 isolation such as VLANs, though this category also includes SDN technologies such as Nicira NVP.
CloudStack Terminology
----------------------
@@ -181,6 +238,7 @@ selecting that 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.
+
About Zones
~~~~~~~~~~~
@@ -194,19 +252,13 @@ geographically (though this is not required).
A zone consists of:
--
-
- One or more pods. Each pod contains one or more clusters of hosts and
+- One or more pods. Each pod contains one or more clusters of hosts and
one or more primary storage servers.
--
-
- A zone may contain one or more primary storage servers, which are
+- A zone may contain one or more primary storage servers, which are
shared by all the pods in the zone.
--
-
- Secondary storage, which is shared by all the pods in the zone.
+- Secondary storage, which is shared by all the pods in the zone.
|zone-overview.png: Nested structure of a simple zone.|
@@ -226,31 +278,19 @@ each other through statically configured VPN tunnels.
For each zone, the administrator must decide the following.
--
-
- How many pods to place in each zone.
-
--
-
- How many clusters to place in each pod.
-
--
+- How many pods to place in each zone.
- How many hosts to place in each cluster.
+- How many clusters to place in each pod.
--
+- How many hosts to place in each cluster.
- (Optional) How many primary storage servers to place in each zone and
+- (Optional) How many primary storage servers to place in each zone and
total capacity for these storage servers.
--
-
- How many primary storage servers to place in each cluster and total
+- How many primary storage servers to place in each cluster and total
capacity for these storage servers.
--
-
- How much secondary storage to deploy in a zone.
+- How much secondary storage to deploy in a zone.
When you add a new zone using the CloudStack UI, you will be prompted to
configure the zone’s physical network and add the first pod, cluster,
@@ -266,8 +306,13 @@ the zone. If you are provisioning multiple VMware Datacenters, each one
will be set up as a single zone in CloudStack.
.. note::
+ If you are upgrading from a previous CloudStack version, and your existing
+ deployment contains a zone with clusters from multiple VMware Datacenters,
+ that zone will not be forcibly migrated to the new model. It will continue
+ to function as before. However, any new zone-wide operations, such as
+ zone-wide primary storage and live storage migration, will not be available
+ in that zone.
- If you are upgrading from a previous CloudStack version, and your existing deployment contains a zone with clusters from multiple VMware Datacenters, that zone will not be forcibly migrated to the new model. It will continue to function as before. However, any new zone-wide operations, such as zone-wide primary storage and live storage migration, will not be available in that zone.
About Pods
~~~~~~~~~~
@@ -281,6 +326,7 @@ the end user.
|pod-overview.png: Nested structure of a simple pod|
+
About Clusters
~~~~~~~~~~~~~~
@@ -313,6 +359,7 @@ server. An Administrator must register the vCenter server with
CloudStack. There may be multiple vCenter servers per zone. Each vCenter
server may manage multiple VMware clusters.
+
About Hosts
~~~~~~~~~~~
@@ -329,24 +376,16 @@ within regions.
Hosts in a CloudStack deployment:
--
-
- Provide the CPU, memory, storage, and networking resources needed to
+- Provide the CPU, memory, storage, and networking resources needed to
host the virtual machines
--
-
- Interconnect using a high bandwidth TCP/IP network and connect to the
+- Interconnect using a high bandwidth TCP/IP network and connect to the
Internet
--
-
- May reside in multiple data centers across different geographic
+- May reside in multiple data centers across different geographic
locations
--
-
- May have different capacities (different CPU speeds, different
+- May have different capacities (different CPU speeds, different
amounts of RAM, etc.), although the hosts within a cluster must all
be homogeneous
@@ -361,17 +400,12 @@ which host their guest has been assigned to.
For a host to function in CloudStack, you must do the following:
--
-
- Install hypervisor software on the host
+- Install hypervisor software on the host
--
+- Assign an IP address to the host
- Assign an IP address to the host
+- Ensure the host is connected to the CloudStack Management Server.
--
-
- Ensure the host is connected to the CloudStack Management Server.
About Primary Storage
~~~~~~~~~~~~~~~~~~~~~
@@ -399,43 +433,30 @@ CloudStack is designed to work with all standards-compliant iSCSI and
NFS servers that are supported by the underlying hypervisor, including,
for example:
--
-
- SolidFire for iSCSI
+- SolidFire for iSCSI
--
+- Dell EqualLogic™ for iSCSI
- Dell EqualLogic™ for iSCSI
+- Network Appliances filers for NFS and iSCSI
--
-
- Network Appliances filers for NFS and iSCSI
-
--
-
- Scale Computing for NFS
+- Scale Computing for NFS
If you intend to use only local disk for your installation, you can skip
adding separate primary storage.
+
About Secondary Storage
~~~~~~~~~~~~~~~~~~~~~~~
Secondary storage stores the following:
--
-
- Templates — OS images that can be used to boot VMs and can include
+- Templates — OS images that can be used to boot VMs and can include
additional configuration information, such as installed applications
--
-
- ISO images — disc images containing data or bootable media for
+- ISO images — disc images containing data or bootable media for
operating systems
--
-
- Disk volume snapshots — saved copies of VM data which can be used for
+- Disk volume snapshots — saved copies of VM data which can be used for
data recovery or to create new templates
The items in secondary storage are available to all hosts in the scope
@@ -462,8 +483,10 @@ resource, making templates and other data available to any zone in the
cloud.
.. warning::
+ Heterogeneous Secondary Storage is not supported in Regions. For example,
+ you cannot set up multiple zones, one using NFS secondary and the other
+ using S3 or Swift secondary.
- Heterogeneous Secondary Storage is not supported in Regions. For example, you cannot set up multiple zones, one using NFS secondary and the other using S3 or Swift secondary.
About Physical Networks
~~~~~~~~~~~~~~~~~~~~~~~
@@ -478,49 +501,34 @@ a zone with basic networking or advanced networking.
A physical network is the actual network hardware and wiring in a zone.
A zone can have multiple physical networks. An administrator can:
--
-
- Add/Remove/Update physical networks in a zone
-
--
-
- Configure VLANs on the physical network
+- Add/Remove/Update physical networks in a zone
--
+- Configure VLANs on the physical network
- Configure a name so the network can be recognized by hypervisors
+- Configure a name so the network can be recognized by hypervisors
--
-
- Configure the service providers (firewalls, load balancers, etc.)
+- Configure the service providers (firewalls, load balancers, etc.)
available on a physical network
--
-
- Configure the IP addresses trunked to a physical network
-
--
+- Configure the IP addresses trunked to a physical network
- Specify what type of traffic is carried on the physical network, as
+- Specify what type of traffic is carried on the physical network, as
well as other properties like network speed
+
Basic Zone Network Traffic Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When basic networking is used, there can be only one physical network in
the zone. That physical network carries the following traffic types:
--
-
- Guest. When end users run VMs, they generate guest traffic. The guest
+- Guest. When end users run VMs, they generate guest traffic. The guest
VMs communicate with each other over a network that can be referred
to as the guest network. Each pod in a basic zone is a broadcast
domain, and therefore each pod has a different IP range for the guest
network. The administrator must configure the IP range for each pod.
--
-
- Management. When CloudStack's internal resources communicate with
+- Management. When CloudStack's internal resources communicate with
each other, they generate management traffic. This includes
communication between hosts, system VMs (VMs used by CloudStack to
perform various tasks in the cloud), and any other component that
@@ -528,21 +536,16 @@ the zone. That physical network carries the following traffic types:
configure the IP range for the system VMs to use.
.. note::
-
We strongly recommend the use of separate NICs for management traffic
and guest traffic.
--
-
- Public. Public traffic is generated when VMs in the cloud access the
+- Public. Public traffic is generated when VMs in the cloud access the
Internet. Publicly accessible IPs must be allocated for this purpose.
End users can use the CloudStack UI to acquire these IPs to implement
NAT between their guest network and the public network, as described
in Acquiring a New IP Address.
--
-
- Storage. While labeled "storage" this is specifically about secondary
+- Storage. While labeled "storage" this is specifically about secondary
storage, and doesn't affect traffic for primary storage. This
includes traffic such as VM templates and snapshots, which is sent
between the secondary storage VM and secondary storage servers.
@@ -560,6 +563,7 @@ balancing (EIP and ELB) features, you must also configure a network to
carry public traffic. CloudStack takes care of presenting the necessary
network configuration steps to you in the UI when you add a new zone.
+
Basic Zone Guest IP Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -568,6 +572,7 @@ the CIDR of the pod to the guests in that pod. The administrator must
add a Direct IP range on the pod for this purpose. These IPs are in the
same VLAN as the hosts.
+
Advanced Zone Network Traffic Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -577,9 +582,7 @@ traffic types, and you need to let CloudStack know which type of network
traffic you want each network to carry. The traffic types in an advanced
zone are:
--
-
- Guest. When end users run VMs, they generate guest traffic. The guest
+- Guest. When end users run VMs, they generate guest traffic. The guest
VMs communicate with each other over a network that can be referred
to as the guest network. This network can be isolated or shared. In
an isolated guest network, the administrator needs to reserve VLAN
@@ -587,26 +590,20 @@ zone are:
(potentially a large number of VLANs). In a shared guest network, all
guest VMs share a single network.
--
-
- Management. When CloudStack’s internal resources communicate with
+- Management. When CloudStack’s internal resources communicate with
each other, they generate management traffic. This includes
communication between hosts, system VMs (VMs used by CloudStack to
perform various tasks in the cloud), and any other component that
communicates directly with the CloudStack Management Server. You must
configure the IP range for the system VMs to use.
--
-
- Public. Public traffic is generated when VMs in the cloud access the
+- Public. Public traffic is generated when VMs in the cloud access the
Internet. Publicly accessible IPs must be allocated for this purpose.
End users can use the CloudStack UI to acquire these IPs to implement
NAT between their guest network and the public network, as described
in “Acquiring a New IP Address” in the Administration Guide.
--
-
- Storage. While labeled "storage" this is specifically about secondary
+- Storage. While labeled "storage" this is specifically about secondary
storage, and doesn't affect traffic for primary storage. This
includes traffic such as VM templates and snapshots, which is sent
between the secondary storage VM and secondary storage servers.
@@ -621,6 +618,7 @@ can be combined with certain restrictions. When you use the Add Zone
wizard in the UI to create a new zone, you are guided into making only
valid choices.
+
Advanced Zone Guest IP Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -633,6 +631,7 @@ range, and gateway. The administrator may provision thousands of these
networks if desired. Additionally, the administrator can reserve a part
of the IP address space for non-CloudStack VMs and servers.
+
Advanced Zone Public IP Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -644,6 +643,7 @@ attach to these networks. The networks are defined by a VLAN ID, IP
range, and gateway. The administrator may provision thousands of these
networks if desired.
+
System Reserved IP Addresses
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -702,14 +702,10 @@ To ensure adequate headroom to scale private IP space in an ESXi pod
that uses advanced networking, use one or both of the following
techniques:
--
-
- Specify a larger CIDR block for the subnet. A subnet mask with a /20
+- Specify a larger CIDR block for the subnet. A subnet mask with a /20
suffix will provide more than 4,000 IP addresses.
--
-
- Create multiple pods, each with its own subnet. For example, if you
+- Create multiple pods, each with its own subnet. For example, if you
create 10 pods and each pod has 255 IPs, this will provide 2,550 IP
addresses.
@@ -720,4 +716,4 @@ techniques:
.. |region-overview.png: Nested structure of a region.| image:: ./_static/images/region-overview.png
.. |zone-overview.png: Nested structure of a simple zone.| image:: ./_static/images/zone-overview.png
.. |pod-overview.png: Nested structure of a simple pod| image:: ./_static/images/pod-overview.png
-.. |cluster-overview.png: Structure of a simple cluster| image:: ./_static/images/cluster-overview.png
\ No newline at end of file
+.. |cluster-overview.png: Structure of a simple cluster| image:: ./_static/images/cluster-overview.png
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/conf.py
----------------------------------------------------------------------
diff --git a/rtd/source/conf.py b/rtd/source/conf.py
index 751553f..2076d96 100644
--- a/rtd/source/conf.py
+++ b/rtd/source/conf.py
@@ -31,6 +31,8 @@
import sys
import os
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -115,6 +117,13 @@ pygments_style = 'sphinx'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
+if not on_rtd:
+ try:
+ import sphinx_rtd_theme
+ html_theme = 'sphinx_rtd_theme'
+ html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+ except ImportError:
+ pass
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/dev.rst
----------------------------------------------------------------------
diff --git a/rtd/source/dev.rst b/rtd/source/dev.rst
index 5fca19e..850caf2 100644
--- a/rtd/source/dev.rst
+++ b/rtd/source/dev.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
Programmer Guide
================
@@ -5,6 +21,7 @@ This guide shows how to develop CloudStack, use the API for operation
and integration, access the usage data and use CloudStack specific tools
to ease development, testing and integration.
+
The CloudStack API
------------------
@@ -13,55 +30,42 @@ Getting Started
To get started using the CloudStack API, you should have the following:
--
-
- URL of the CloudStack server you wish to integrate with.
+- URL of the CloudStack server you wish to integrate with.
--
-
- Both the API Key and Secret Key for an account. This should have been
+- Both the API Key and Secret Key for an account. This should have been
generated by the administrator of the cloud instance and given to
you.
--
-
- Familiarity with HTTP GET/POST and query strings.
-
--
+- Familiarity with HTTP GET/POST and query strings.
- Knowledge of either XML or JSON.
+- Knowledge of either XML or JSON.
--
-
- Knowledge of a programming language that can generate HTTP requests;
+- Knowledge of a programming language that can generate HTTP requests;
for example, Java or PHP.
+
Roles
~~~~~
The CloudStack API supports three access roles:
-#.
-
- Root Admin. Access to all features of the cloud, including both
+#. Root Admin. Access to all features of the cloud, including both
virtual and physical resource management.
-#.
-
- Domain Admin. Access to only the virtual resources of the clouds that
+#. Domain Admin. Access to only the virtual resources of the clouds that
belong to the administrator’s domain.
-#.
-
- User. Access to only the features that allow management of the user’s
+#. User. Access to only the features that allow management of the user’s
virtual instances, storage, and network.
+
API Reference Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can find all the API reference documentation at the below site:
-`http://cloudstack.apache.org/docs/api/ <http://cloudstack.apache.org/docs/api/>`__
+`http://cloudstack.apache.org/docs/api/
+<http://cloudstack.apache.org/docs/api/>`__
Making API Requests
@@ -71,39 +75,33 @@ All CloudStack API requests are submitted in the form of a HTTP GET/POST
with an associated command and any parameters. A request is composed of
the following whether in HTTP or HTTPS:
--
-
- CloudStack API URL: This is the web services API entry point(for
+- CloudStack API URL: This is the web services API entry point(for
example, http://www.example.com:8080/client/api)
--
-
- Command: The web services command you wish to execute, such as start
+- Command: The web services command you wish to execute, such as start
a virtual machine or create a disk volume
--
-
- Parameters: Any additional required or optional parameters for the
+- Parameters: Any additional required or optional parameters for the
command
A sample API GET request looks like the following:
.. sourcecode:: bash
- http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Or in a more readable format:
.. sourcecode:: bash
- 1. http://localhost:8080/client/api
- 2. ?command=deployVirtualMachine
- 3. &serviceOfferingId=1
- 4. &diskOfferingId=1
- 5. &templateId=2
- 6. &zoneId=4
- 7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
- 8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ 1. http://localhost:8080/client/api
+ 2. ?command=deployVirtualMachine
+ 3. &serviceOfferingId=1
+ 4. &diskOfferingId=1
+ 5. &templateId=2
+ 6. &zoneId=4
+ 7. &apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXqjB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
+ 8. &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
The first line is the CloudStack API URL. This is the Cloud instance you
wish to interact with.
@@ -123,6 +121,7 @@ Signing API Requests on page 7.
Line 8 is the signature hash created to authenticate the user account
executing the API command.
+
Signing API Requests
~~~~~~~~~~~~~~~~~~~~
@@ -137,74 +136,63 @@ To show how to sign a request, we will re-use the previous example.
.. sourcecode:: bash
- http://http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ http://http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Breaking this down, we have several distinct parts to this URL.
--
-
- Base URL: This is the base URL to the CloudStack Management Server.
+- Base URL: This is the base URL to the CloudStack Management Server.
.. sourcecode:: bash
- http://localhost:8080
+ http://localhost:8080
--
-
- API Path: This is the path to the API Servlet that processes the
+- API Path: This is the path to the API Servlet that processes the
incoming requests.
.. sourcecode:: bash
- /client/api?
-
--
+ /client/api?
- Command String: This part of the query string comprises of the
+- Command String: This part of the query string comprises of the
command, its parameters, and the API Key that identifies the account.
- .. note:: As with all query string parameters of field-value pairs, the "field" component is case insensitive while all "value" values are case sensitive.
+ .. note::
+ As with all query string parameters of field-value pairs, the "field"
+ component is case insensitive while all "value" values are case
+ sensitive.
.. sourcecode: bash
- command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
-
--
+ command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ
- Signature: This is the signature of the command string that is
+- Signature: This is the signature of the command string that is
generated using a combination of the user’s Secret Key and the HMAC
SHA-1 hashing algorithm.
.. sourcecode:: bash
- &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ &signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Every API request has the format Base URL+API Path+Command
String+Signature.
To generate the signature.
-#.
-
- For each field-value pair (as separated by a '&') in the Command
+#. For each field-value pair (as separated by a '&') in the Command
String, URL encode each value so that it can be safely sent via HTTP
GET.
.. note:: Make sure all spaces are encoded as "%20" rather than "+".
-#.
-
- Lower case the entire Command String and sort it alphabetically via
+#. Lower case the entire Command String and sort it alphabetically via
the field for each field-value pair. The result of this step would
look like the following.
.. sourcecode:: bash
- apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
-
-#.
+ apikey=mivr6x7u6bn_sdahobpjnejpgest35exq-jb8cg20yi3yaxxcgpyuairmfi_ejtvwz0nukkjbpmy3y2bcikwfq&command=deployvirtualmachine&diskofferingid=1&serviceofferingid=1&templateid=2&zoneid=4
- Take the sorted Command String and run it through the HMAC SHA-1
+#. Take the sorted Command String and run it through the HMAC SHA-1
hashing algorithm (most programming languages offer a utility method
to do this) with the user’s Secret Key. Base64 encode the resulting
byte array in UTF-8 so that it can be safely transmitted via HTTP.
@@ -216,7 +204,8 @@ To generate the signature.
.. sourcecode:: bash
- http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ http://localhost:8080/client/api?command=deployVirtualMachine&serviceOfferingId=1&diskOfferingId=1&templateId=2&zoneId=4&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+
How to sign an API call with Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -228,15 +217,15 @@ First import the required modules:
.. sourcecode:: bash
- $python
- Python 2.7.3 (default, Nov 17 2012, 19:54:34)
- [GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
- Type "help", "copyright", "credits" or "license" for more information.
- >>> import urllib2
- >>> import urllib
- >>> import hashlib
- >>> import hmac
- >>> import base64
+ $python
+ Python 2.7.3 (default, Nov 17 2012, 19:54:34)
+ [GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>> import urllib2
+ >>> import urllib
+ >>> import hashlib
+ >>> import hmac
+ >>> import base64
Define the endpoint of the Cloud, the command that you want to execute
@@ -244,21 +233,21 @@ and the keys of the user.
.. sourcecode:: bash
- >>> baseurl='http://localhost:8080/client/api?'
- >>> request={}
- >>> request['command']='listUsers'
- >>> request['response']='json'
- >>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
- >>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
+ >>> baseurl='http://localhost:8080/client/api?'
+ >>> request={}
+ >>> request['command']='listUsers'
+ >>> request['response']='json'
+ >>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
+ >>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
Build the request string:
.. sourcecode:: bash
- >>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
- >>> request_str
- 'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
+ >>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
+ >>> request_str
+ 'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
Compute the signature with hmac, do a 64 bit encoding and a url
@@ -266,33 +255,33 @@ encoding:
.. sourcecode:: bash
- >>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
- >>> sig_str 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
- >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1)
- >>> sig
- <hmac.HMAC instance at 0x10d91d680>
- >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
- >>> sig
- 'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
- >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
- >>> sig
- 'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
- >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
- >>> sig
- 'TTpdDq/7j/J58XCRHomKoQXEQds='
- >>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
+ >>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
+ >>> sig_str 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
+ >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1)
+ >>> sig
+ <hmac.HMAC instance at 0x10d91d680>
+ >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
+ >>> sig
+ 'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
+ >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
+ >>> sig
+ 'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
+ >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
+ >>> sig
+ 'TTpdDq/7j/J58XCRHomKoQXEQds='
+ >>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
Finally, build the entire string and do an http GET:
.. sourcecode:: bash
- >>> req=baseurl+request_str+'&signature='+sig
- >>> req
- 'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
- >>> res=urllib2.urlopen(req)
- >>> res.read()
- '{ "listusersresponse" : { "count":3 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg","secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"1fea6418-5576-4989-a21e-4790787bbee3","username":"runseb","firstname":"foobar","lastname":"goa","email":"joe@smith.com","created":"2013-04-10T16:52:06-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"Xhsb3MewjJQaXXMszRcLvQI9_NPy_UcbDj1QXikkVbDC9MDSPwWdtZ1bUY1H7JBEYTtDDLY3yuchCeW778GkBA","secretkey":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLc
eY5bgnfzKjL4aM6ctJX-i1ddQIHJLbLJDK9MRzsKk6xZ_w","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"52f65396-183c-4473-883f-a37e7bb93967","username":"toto","firstname":"john","lastname":"smith","email":"john@smith.com","created":"2013-04-23T04:27:22-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"THaA6fFWS_OmvU8od201omxFC8yKNL_Hc5ZCS77LFCJsRzSx48JyZucbUul6XYbEg-ZyXMl_wuEpECzK-wKnow","secretkey":"O5ywpqJorAsEBKR_5jEvrtGHfWL1Y_j1E4Z_iCr8OKCYcsPIOdVcfzjJQ8YqK0a5EzSpoRrjOFiLsG0hQrYnDA","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"} ] } }'
+ >>> req=baseurl+request_str+'&signature='+sig
+ >>> req
+ 'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
+ >>> res=urllib2.urlopen(req)
+ >>> res.read()
+ '{ "listusersresponse" : { "count":3 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin","lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg","secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"1fea6418-5576-4989-a21e-4790787bbee3","username":"runseb","firstname":"foobar","lastname":"goa","email":"joe@smith.com","created":"2013-04-10T16:52:06-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"Xhsb3MewjJQaXXMszRcLvQI9_NPy_UcbDj1QXikkVbDC9MDSPwWdtZ1bUY1H7JBEYTtDDLY3yuchCeW778GkBA","secretkey":"gIsgmi8C5YwxMHjX5o51pSe0kqs6JnKriw0jJBLce
Y5bgnfzKjL4aM6ctJX-i1ddQIHJLbLJDK9MRzsKk6xZ_w","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}, {"id":"52f65396-183c-4473-883f-a37e7bb93967","username":"toto","firstname":"john","lastname":"smith","email":"john@smith.com","created":"2013-04-23T04:27:22-0700","state":"enabled","account":"admin","accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT","apikey":"THaA6fFWS_OmvU8od201omxFC8yKNL_Hc5ZCS77LFCJsRzSx48JyZucbUul6XYbEg-ZyXMl_wuEpECzK-wKnow","secretkey":"O5ywpqJorAsEBKR_5jEvrtGHfWL1Y_j1E4Z_iCr8OKCYcsPIOdVcfzjJQ8YqK0a5EzSpoRrjOFiLsG0hQrYnDA","accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"} ] } }'
Enabling API Call Expiration
@@ -305,15 +294,11 @@ that come in after this validity period.
To enable this feature, add the following parameters to the API request:
--
-
- signatureVersion=3: If the signatureVersion parameter is missing or
+- signatureVersion=3: If the signatureVersion parameter is missing or
is not equal to 3, the expires parameter is ignored in the API
request.
--
-
- expires=YYYY-MM-DDThh:mm:ssZ: Specifies the date and time at which
+- expires=YYYY-MM-DDThh:mm:ssZ: Specifies the date and time at which
the signature included in the request is expired. The timestamp is
expressed in the YYYY-MM-DDThh:mm:ssZ format, as specified in the ISO
8601 standard.
@@ -322,13 +307,13 @@ For example:
.. sourcecode:: bash
- expires=2011-10-10T12:00:00+0530
+ expires=2011-10-10T12:00:00+0530
A sample API request with expiration is given below:
.. sourcecode:: bash
- http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
+ http://<IPAddress>:8080/client/api?command=listZones&signatureVersion=3&expires=2011-10-10T12:00:00+0530&apiKey=miVr6X7u6bN_sdahOBpjNejPgEsT35eXq-jB8CG20YI3yaxXcgpyuaIRmFI_EJTVwZ0nUkkJbPmY3y2bciKwFQ&signature=Lxx1DM40AjcXU%2FcaiK8RAP0O1hU%3D
Limiting the Rate of API Requests
@@ -343,58 +328,49 @@ If the number of API calls exceeds the threshold, an error message is
returned for any additional API calls. The caller will have to retry
these API calls at another time.
+
Configuring the API Request Rate
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To control the API request rate, use the following global configuration
settings:
--
-
- `api.throttling.enabled` - Enable/Disable API throttling. By default,
+- `api.throttling.enabled` - Enable/Disable API throttling. By default,
this setting is false, so API throttling is not enabled.
--
-
- `api.throttling.interval` (in seconds) - Time interval during which the
+- `api.throttling.interval` (in seconds) - Time interval during which the
number of API requests is to be counted. When the interval has
passed, the API count is reset to 0.
--
-
- `api.throttling.max` - Maximum number of APIs that can be placed within
+- `api.throttling.max` - Maximum number of APIs that can be placed within
the `api.throttling.interval` period.
--
-
- `api.throttling.cachesize` - Cache size for storing API counters. Use a
+- `api.throttling.cachesize` - Cache size for storing API counters. Use a
value higher than the total number of accounts managed by the cloud.
One cache entry is needed for each account, to store the running API
total for that account.
+
Limitations on API Throttling
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following limitations exist in the current implementation of this
feature.
-.. note:: Even with these limitations, CloudStack is still able to effectively use
-API throttling to avoid malicious attacks causing denial of service.
-
+.. note::
+ Even with these limitations, CloudStack is still able to effectively use
+ API throttling to avoid malicious attacks causing denial of service.
--
-
- In a deployment with multiple Management Servers, the cache is not
+- In a deployment with multiple Management Servers, the cache is not
synchronized across them. In this case, CloudStack might not be able
to ensure that only the exact desired number of API requests are
allowed. In the worst case, the number of API calls that might be
allowed is (number of Management Servers) \* (api.throttling.max).
--
-
- The API commands resetApiLimit and getApiLimit are limited to the
+- The API commands resetApiLimit and getApiLimit are limited to the
Management Server where the API is invoked.
+
API Responses
~~~~~~~~~~~~~
@@ -415,33 +391,34 @@ Sample XML Response:
.. sourcecode:: bash
- <listipaddressesresponse>
- <allocatedipaddress>
- <ipaddress>192.168.10.141</ipaddress>
- <allocated>2009-09-18T13:16:10-0700</allocated>
- <zoneid>4</zoneid>
- <zonename>WC</zonename>
- <issourcenat>true</issourcenat>
- </allocatedipaddress>
- </listipaddressesresponse>
+ <listipaddressesresponse>
+ <allocatedipaddress>
+ <ipaddress>192.168.10.141</ipaddress>
+ <allocated>2009-09-18T13:16:10-0700</allocated>
+ <zoneid>4</zoneid>
+ <zonename>WC</zonename>
+ <issourcenat>true</issourcenat>
+ </allocatedipaddress>
+ </listipaddressesresponse>
Sample JSON Response:
.. sourcecode:: bash
- { "listipaddressesresponse" :
- { "allocatedipaddress" :
- [
- {
- "ipaddress" : "192.168.10.141",
- "allocated" : "2009-09-18T13:16:10-0700",
- "zoneid" : "4",
- "zonename" : "WC",
- "issourcenat" : "true"
- }
- ]
- }
- }
+ { "listipaddressesresponse" :
+ { "allocatedipaddress" :
+ [
+ {
+ "ipaddress" : "192.168.10.141",
+ "allocated" : "2009-09-18T13:16:10-0700",
+ "zoneid" : "4",
+ "zonename" : "WC",
+ "issourcenat" : "true"
+ }
+ ]
+ }
+ }
+
Maximum Result Pages Returned
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -465,18 +442,15 @@ the global setting with the page and pagesize parameters, which are
available in any list\* command (listCapabilities, listDiskOfferings,
etc.).
--
+- Both parameters must be specified together.
- Both parameters must be specified together.
-
--
-
- The value of the pagesize parameter must be smaller than the value of
+- The value of the pagesize parameter must be smaller than the value of
default.page.size. That is, you can not increase the number of
possible items in a result page, only decrease it.
For syntax information on the list\* commands, see the API Reference.
+
Error Handling
~~~~~~~~~~~~~~
@@ -611,6 +585,7 @@ An HTTP error code of 401 is always returned if API request was rejected
due to bad signatures, missing API Keys, or the user simply did not have
the permissions to execute the command.
+
Asynchronous Commands
~~~~~~~~~~~~~~~~~~~~~
@@ -619,24 +594,19 @@ designated as asynchronous when they can potentially take a long period
of time to complete such as creating a snapshot or disk volume. They
differ from synchronous commands by the following:
--
-
- They are identified in the API Reference by an (A).
+- They are identified in the API Reference by an (A).
--
-
- They will immediately return a job ID to refer to the job that will
+- They will immediately return a job ID to refer to the job that will
be responsible in processing the command.
--
-
- If executed as a "create" resource command, it will return the
+- If executed as a "create" resource command, it will return the
resource ID as well as the job ID.
You can periodically check the status of the job by making a simple
API call to the command, `queryAsyncJobResult` and passing in the job
ID.
+
Job Status
~~~~~~~~~~
@@ -646,22 +616,17 @@ periodically check the job status by making calls to queryAsyncJobResult
command. The command will return three possible job status integer
values:
--
-
- 0 - Job is still in progress. Continue to periodically poll for any
+- 0 - Job is still in progress. Continue to periodically poll for any
status changes.
--
-
- 1 - Job has successfully completed. The job will return any
+- 1 - Job has successfully completed. The job will return any
successful response values associated with command that was
originally executed.
--
-
- 2 - Job has failed to complete. Please check the "jobresultcode" tag
+- 2 - Job has failed to complete. Please check the "jobresultcode" tag
for failure reason code and "jobresult" for the failure reason.
+
Example
~~~~~~~
@@ -670,24 +635,24 @@ the API command:
.. sourcecode:: bash
- command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1
+ command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1
CloudStack will immediately return a job ID and any other additional
data.
.. sourcecode:: bash
- <deployvirtualmachineresponse>
- <jobid>1</jobid>
- <id>100</id>
- </deployvirtualmachineresponse>
+ <deployvirtualmachineresponse>
+ <jobid>1</jobid>
+ <id>100</id>
+ </deployvirtualmachineresponse>
Using the job ID, you can periodically poll for the results by using the
queryAsyncJobResult command.
.. sourcecode:: bash
- command=queryAsyncJobResult&jobId=1
+ command=queryAsyncJobResult&jobId=1
Three possible results could come from this query.
@@ -695,78 +660,78 @@ Job is still pending:
.. sourcecode:: bash
- <queryasyncjobresult>
- <jobid>1</jobid>
- <jobstatus>0</jobstatus>
- <jobprocstatus>1</jobprocstatus>
- </queryasyncjobresult>
+ <queryasyncjobresult>
+ <jobid>1</jobid>
+ <jobstatus>0</jobstatus>
+ <jobprocstatus>1</jobprocstatus>
+ </queryasyncjobresult>
Job has succeeded:
.. sourcecode:: bash
- <queryasyncjobresultresponse cloud-stack-version="3.0.1.6">
- <jobid>1</jobid>
- <jobstatus>1</jobstatus>
- <jobprocstatus>0</jobprocstatus>
- <jobresultcode>0</jobresultcode>
- <jobresulttype>object</jobresulttype>
- <jobresult>
- <virtualmachine>
- <id>450</id>
- <name>i-2-450-VM</name>
- <displayname>i-2-450-VM</displayname>
- <account>admin</account>
- <domainid>1</domainid>
- <domain>ROOT</domain>
- <created>2011-03-10T18:20:25-0800</created>
- <state>Running</state>
- <haenable>false</haenable>
- <zoneid>1</zoneid>
- <zonename>San Jose 1</zonename>
- <hostid>2</hostid>
- <hostname>905-13.sjc.lab.vmops.com</hostname>
- <templateid>1</templateid>
- <templatename>CentOS 5.3 64bit LAMP</templatename>
- <templatedisplaytext>CentOS 5.3 64bit LAMP</templatedisplaytext>
- <passwordenabled>false</passwordenabled>
- <serviceofferingid>1</serviceofferingid>
- <serviceofferingname>Small Instance</serviceofferingname>
- <cpunumber>1</cpunumber>
- <cpuspeed>500</cpuspeed>
- <memory>512</memory>
- <guestosid>12</guestosid>
- <rootdeviceid>0</rootdeviceid>
- <rootdevicetype>NetworkFilesystem</rootdevicetype>
- <nic>
- <id>561</id>
- <networkid>205</networkid>
- <netmask>255.255.255.0</netmask>
- <gateway>10.1.1.1</gateway>
- <ipaddress>10.1.1.225</ipaddress>
- <isolationuri>vlan://295</isolationuri>
- <broadcasturi>vlan://295</broadcasturi>
- <traffictype>Guest</traffictype>
- <type>Virtual</type>
- <isdefault>true</isdefault>
- </nic>
- <hypervisor>XenServer</hypervisor>
- </virtualmachine>
- </jobresult>
- </queryasyncjobresultresponse>
+ <queryasyncjobresultresponse cloud-stack-version="3.0.1.6">
+ <jobid>1</jobid>
+ <jobstatus>1</jobstatus>
+ <jobprocstatus>0</jobprocstatus>
+ <jobresultcode>0</jobresultcode>
+ <jobresulttype>object</jobresulttype>
+ <jobresult>
+ <virtualmachine>
+ <id>450</id>
+ <name>i-2-450-VM</name>
+ <displayname>i-2-450-VM</displayname>
+ <account>admin</account>
+ <domainid>1</domainid>
+ <domain>ROOT</domain>
+ <created>2011-03-10T18:20:25-0800</created>
+ <state>Running</state>
+ <haenable>false</haenable>
+ <zoneid>1</zoneid>
+ <zonename>San Jose 1</zonename>
+ <hostid>2</hostid>
+ <hostname>905-13.sjc.lab.vmops.com</hostname>
+ <templateid>1</templateid>
+ <templatename>CentOS 5.3 64bit LAMP</templatename>
+ <templatedisplaytext>CentOS 5.3 64bit LAMP</templatedisplaytext>
+ <passwordenabled>false</passwordenabled>
+ <serviceofferingid>1</serviceofferingid>
+ <serviceofferingname>Small Instance</serviceofferingname>
+ <cpunumber>1</cpunumber>
+ <cpuspeed>500</cpuspeed>
+ <memory>512</memory>
+ <guestosid>12</guestosid>
+ <rootdeviceid>0</rootdeviceid>
+ <rootdevicetype>NetworkFilesystem</rootdevicetype>
+ <nic>
+ <id>561</id>
+ <networkid>205</networkid>
+ <netmask>255.255.255.0</netmask>
+ <gateway>10.1.1.1</gateway>
+ <ipaddress>10.1.1.225</ipaddress>
+ <isolationuri>vlan://295</isolationuri>
+ <broadcasturi>vlan://295</broadcasturi>
+ <traffictype>Guest</traffictype>
+ <type>Virtual</type>
+ <isdefault>true</isdefault>
+ </nic>
+ <hypervisor>XenServer</hypervisor>
+ </virtualmachine>
+ </jobresult>
+ </queryasyncjobresultresponse>
Job has failed:
.. sourcecode:: bash
- <queryasyncjobresult>
- <jobid>1</jobid>
- <jobstatus>2</jobstatus>
- <jobprocstatus>0</jobprocstatus>
- <jobresultcode>551</jobresultcode>
- <jobresulttype>text</jobresulttype>
- <jobresult>Unable to deploy virtual machine id = 100 due to not enough capacity</jobresult>
- </queryasyncjobresult>
+ <queryasyncjobresult>
+ <jobid>1</jobid>
+ <jobstatus>2</jobstatus>
+ <jobprocstatus>0</jobprocstatus>
+ <jobresultcode>551</jobresultcode>
+ <jobresulttype>text</jobresulttype>
+ <jobresult>Unable to deploy virtual machine id = 100 due to not enough capacity</jobresult>
+ </queryasyncjobresult>
Event Types
@@ -1318,6 +1283,7 @@ Event Types
| | UCS.DISASSOCIATEPROFILE |
+-------------------+--------------------------------------------------------+
+
Time Zones
----------
@@ -1367,6 +1333,3 @@ user, and specifying the usage time zone in the Configuration table.
+-----------------------------------+-----------------------+------------------------+
| Pacific/Guam | Pacific/Auckland | |
+-----------------------------------+-----------------------+------------------------+
-
-
-
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/developer_guide.rst
----------------------------------------------------------------------
diff --git a/rtd/source/developer_guide.rst b/rtd/source/developer_guide.rst
index e859a59..0e49688 100644
--- a/rtd/source/developer_guide.rst
+++ b/rtd/source/developer_guide.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
CloudStack Installation from Source for Developers
==================================================
@@ -7,13 +23,19 @@ and were tested with the 4.2 release of Apache CloudStack, please adapt
them if you are on a different operating system or using a newer/older
version of CloudStack. This book is composed of the following sections:
-1. Installation of the prerequisites
-2. Compiling and installation from source
-3. Using the CloudStack simulator
-4. Installation with DevCloud the CloudStack sandbox
-5. Building your own packages
-6. The CloudStack API
-7. Testing the AWS API interface
+#. Installation of the prerequisites
+
+#. Compiling and installation from source
+
+#. Using the CloudStack simulator
+
+#. Installation with DevCloud the CloudStack sandbox
+
+#. Building your own packages
+
+#. The CloudStack API
+
+#. Testing the AWS API interface
Prerequisites
@@ -22,6 +44,7 @@ Prerequisites
In this section we'll look at installing the dependencies you'll need
for Apache CloudStack development.
+
On Ubuntu 12.04
~~~~~~~~~~~~~~~
@@ -29,21 +52,21 @@ First update and upgrade your system:
::
- apt-get update
- apt-get upgrade
+ apt-get update
+ apt-get upgrade
NTP might already be installed, check it with ``service ntp status``. If
it's not then install NTP to synchronize the clocks:
::
- apt-get install openntpd
+ apt-get install openntpd
Install ``openjdk``. As we're using Linux, OpenJDK is our first choice.
::
- apt-get install openjdk-6-jdk
+ apt-get install openjdk-6-jdk
Install ``tomcat6``, note that the new version of tomcat on
`Ubuntu <http://packages.ubuntu.com/precise/all/tomcat6>`__ is the
@@ -51,13 +74,13 @@ Install ``tomcat6``, note that the new version of tomcat on
::
- apt-get install tomcat6
+ apt-get install tomcat6
Next, we'll install MySQL if it's not already present on the system.
::
- apt-get install mysql-server
+ apt-get install mysql-server
Remember to set the correct ``mysql`` password in the CloudStack
properties file. Mysql should be running but you can check it's status
@@ -65,7 +88,7 @@ with:
::
- service mysql status
+ service mysql status
Developers wanting to build CloudStack from source will want to install
the following additional packages. If you dont' want to build from
@@ -75,13 +98,13 @@ Install ``git`` to later clone the CloudStack source code:
::
- apt-get install git
+ apt-get install git
Install ``Maven`` to later build CloudStack
::
- apt-get install maven
+ apt-get install maven
This should have installed Maven 3.0, check the version number with
``mvn --version``
@@ -91,35 +114,36 @@ package management tools:
::
- apt-get install python-pip python-setuptools
+ apt-get install python-pip python-setuptools
Finally install ``mkisofs`` with:
::
- apt-get install genisoimage
+ apt-get install genisoimage
-On centOS 6.4
+
+On CentOS 6.4
~~~~~~~~~~~~~
First update and upgrade your system:
::
- yum -y update
- yum -y upgrade
+ yum -y update
+ yum -y upgrade
If not already installed, install NTP for clock synchornization
::
- yum -y install ntp
+ yum -y install ntp
Install ``openjdk``. As we're using Linux, OpenJDK is our first choice.
::
- yum -y install java-1.6.0-openjdk
+ yum -y install java-1.6.0-openjdk
Install ``tomcat6``, note that the version of tomcat6 in the default
CentOS 6.4 repo is 6.0.24, so we will grab the 6.0.35 version. The
@@ -127,22 +151,22 @@ CentOS 6.4 repo is 6.0.24, so we will grab the 6.0.35 version. The
::
- wget https://archive.apache.org/dist/tomcat/tomcat-6/v6.0.35/bin/apache-tomcat-6.0.35.tar.gz
- tar xzvf apache-tomcat-6.0.35.tar.gz -C /usr/local
+ wget https://archive.apache.org/dist/tomcat/tomcat-6/v6.0.35/bin/apache-tomcat-6.0.35.tar.gz
+ tar xzvf apache-tomcat-6.0.35.tar.gz -C /usr/local
Setup tomcat6 system wide by creating a file
``/etc/profile.d/tomcat.sh`` with the following content:
::
- export CATALINA_BASE=/usr/local/apache-tomcat-6.0.35
- export CATALINA_HOME=/usr/local/apache-tomcat-6.0.35
+ export CATALINA_BASE=/usr/local/apache-tomcat-6.0.35
+ export CATALINA_HOME=/usr/local/apache-tomcat-6.0.35
Next, we'll install MySQL if it's not already present on the system.
::
- yum -y install mysql mysql-server
+ yum -y install mysql mysql-server
Remember to set the correct ``mysql`` password in the CloudStack
properties file. Mysql should be running but you can check it's status
@@ -150,37 +174,37 @@ with:
::
- service mysqld status
+ service mysqld status
Install ``git`` to later clone the CloudStack source code:
::
- yum -y install git
+ yum -y install git
Install ``Maven`` to later build CloudStack. Grab the 3.0.5 release from
the Maven `website <http://maven.apache.org/download.cgi>`__
::
- wget http://mirror.cc.columbia.edu/pub/software/apache/maven/maven-3/3.0.5/binaries/apache-maven-3.0.5-bin.tar.gz
- tar xzf apache-maven-3.0.5-bin.tar.gz -C /usr/local
- cd /usr/local
- ln -s apache-maven-3.0.5 maven
+ wget http://mirror.cc.columbia.edu/pub/software/apache/maven/maven-3/3.0.5/binaries/apache-maven-3.0.5-bin.tar.gz
+ tar xzf apache-maven-3.0.5-bin.tar.gz -C /usr/local
+ cd /usr/local
+ ln -s apache-maven-3.0.5 maven
Setup Maven system wide by creating a ``/etc/profile.d/maven.sh`` file
with the following content:
::
- export M2_HOME=/usr/local/maven
- export PATH=${M2_HOME}/bin:${PATH}
+ export M2_HOME=/usr/local/maven
+ export PATH=${M2_HOME}/bin:${PATH}
Log out and log in again and you will have maven in your PATH:
::
- mvn --version
+ mvn --version
This should have installed Maven 3.0, check the version number with
``mvn --version``
@@ -190,16 +214,16 @@ package management tools:
::
- yum -y install python-setuptools
+ yum -y install python-setuptools
To install python-pip you might want to setup the Extra Packages for
Enterprise Linux (EPEL) repo
::
- cd /tmp
- wget http://mirror-fpt-telecom.fpt.net/fedora/epel/6/i386/epel-release-6-8.noarch.rpm
- rpm -ivh epel-release-6-8.noarch.rpm
+ cd /tmp
+ wget http://mirror-fpt-telecom.fpt.net/fedora/epel/6/i386/epel-release-6-8.noarch.rpm
+ rpm -ivh epel-release-6-8.noarch.rpm
Then update you repository cache ``yum update`` and install pip
``yum -y install python-pip``
@@ -208,7 +232,7 @@ Finally install ``mkisofs`` with:
::
- yum -y install genisoimage
+ yum -y install genisoimage
Installing from Source
@@ -220,20 +244,20 @@ setup on your machine, pull the source with:
::
- git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git
+ git clone https://git-wip-us.apache.org/repos/asf/cloudstack.git
To build the latest stable release:
::
- git checkout 4.2
+ git checkout 4.2
To compile Apache CloudStack, go to the cloudstack source folder and
run:
::
- mvn -Pdeveloper,systemvm clean install
+ mvn -Pdeveloper,systemvm clean install
If you want to skip the tests add ``-DskipTests`` to the command above.
Do NOT use ``-Dmaven.test.skip=true`` because that will break the build.
@@ -245,14 +269,14 @@ Deploy the database next:
::
- mvn -P developer -pl developer -Ddeploydb
+ mvn -P developer -pl developer -Ddeploydb
Run Apache CloudStack with jetty for testing. Note that ``tomcat`` maybe
be running on port 8080, stop it before you use ``jetty``
::
- mvn -pl :cloud-client-ui jetty:run
+ mvn -pl :cloud-client-ui jetty:run
Log Into Apache CloudStack:
@@ -260,11 +284,13 @@ Open your Web browser and use this URL to connect to CloudStack:
::
- http://localhost:8080/client/
+ http://localhost:8080/client/
Replace ``localhost`` with the IP of your management server if need be.
-.. note:: If you have iptables enabled, you may have to open the ports used by CloudStack. Specifically, ports 8080, 8250, and 9090.
+.. note::
+ If you have iptables enabled, you may have to open the ports used by
+ CloudStack. Specifically, ports 8080, 8250, and 9090.
You can now start configuring a Zone, playing with the API. Of course we
did not setup any infrastructure, there is no storage, no
@@ -272,6 +298,7 @@ hypervisors...etc. However you can run tests using the simulator. The
following section shows you how to use the simulator so that you don't
have to setup a physical infrastructure.
+
Using the Simulator
-------------------
@@ -287,39 +314,39 @@ Do a clean build:
::
- mvn -Pdeveloper -Dsimulator -DskipTests clean install
+ mvn -Pdeveloper -Dsimulator -DskipTests clean install
Deploy the database:
::
- mvn -Pdeveloper -pl developer -Ddeploydb
- mvn -Pdeveloper -pl developer -Ddeploydb-simulator
+ mvn -Pdeveloper -pl developer -Ddeploydb
+ mvn -Pdeveloper -pl developer -Ddeploydb-simulator
Install marvin. Note that you will need to have installed ``pip``
properly in the prerequisites step.
::
- pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
+ pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
Stop jetty (from any previous runs)
::
- mvn -pl :cloud-client-ui jetty:stop
+ mvn -pl :cloud-client-ui jetty:stop
Start jetty
::
- mvn -pl client jetty:run
+ mvn -pl client jetty:run
Setup a basic zone with Marvin. In a separate shell://
::
- mvn -Pdeveloper,marvin.setup -Dmarvin.config=setup/dev/basic.cfg -pl :cloud-marvin integration-test
+ mvn -Pdeveloper,marvin.setup -Dmarvin.config=setup/dev/basic.cfg -pl :cloud-marvin integration-test
At this stage log in the CloudStack management server at
http://localhost:8080/client with the credentials admin/password, you
@@ -328,6 +355,7 @@ advanced zone replace ``basic.cfg`` with ``advanced.cfg``.
You can now run integration tests, use the API etc...
+
Using DevCloud
--------------
@@ -345,25 +373,26 @@ with the VirtualBox image. For KVM see the
\*\* DevCloud Pre-requisites
-1. Install `VirtualBox <http://www.virtualbox.org>`__ on your machine
+#. Install `VirtualBox <http://www.virtualbox.org>`__ on your machine
-2. Run VirtualBox and under >Preferences create a *host-only interface*
+#. Run VirtualBox and under >Preferences create a *host-only interface*
on which you disable the DHCP server
-3. Download the DevCloud
- `image <http://people.apache.org/~bhaisaab/cloudstack/devcloud/devcloud2.ova>`__
+#. Download the DevCloud `image
+ <http://people.apache.org/~bhaisaab/cloudstack/devcloud/devcloud2.ova>`__
-4. In VirtualBox, under File > Import Appliance import the DevCloud
+#. In VirtualBox, under File > Import Appliance import the DevCloud
image.
-5. Verify the settings under > Settings and check the ``enable PAE``
+#. Verify the settings under > Settings and check the ``enable PAE``
option in the processor menu
-6. Once the VM has booted try to ``ssh`` to it with credentials:
+#. Once the VM has booted try to ``ssh`` to it with credentials:
``root/password``
ssh root@192.168.56.10
+
Adding DevCloud as an Hypervisor
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -371,28 +400,28 @@ Picking up from a clean build:
::
- mvn -Pdeveloper,systemvm clean install
- mvn -P developer -pl developer,tools/devcloud -Ddeploydb
+ mvn -Pdeveloper,systemvm clean install
+ mvn -P developer -pl developer,tools/devcloud -Ddeploydb
At this stage install marvin similarly than with the simulator:
::
- pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
+ pip install tools/marvin/dist/Marvin-0.1.0.tar.gz
Start the management server
::
- mvn -pl client jetty:run
+ mvn -pl client jetty:run
Then you are going to configure CloudStack to use the running DevCloud
instance:
::
- cd tools/devcloud
- python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg
+ cd tools/devcloud
+ python ../marvin/marvin/deployDataCenter.py -i devcloud.cfg
If you are curious, check the ``devcloud.cfg`` file and see how the data
center is defined: 1 Zone, 1 Pod, 1 Cluster, 1 Host, 1 primary Storage,
@@ -407,6 +436,7 @@ that DevCloud is used only as a n Hypervisor. You could potentially run
the management server within DevCloud as well, or memory granted, run
multiple DevClouds.
+
Building Packages
-----------------
@@ -425,35 +455,36 @@ not need to install for source compilation:
::
- apt-get install python-mysqldb
- apt-get install debhelper
+ apt-get install python-mysqldb
+ apt-get install debhelper
Then build the packages with:
::
- dpkg-buildpackage -uc -us
+ dpkg-buildpackage -uc -us
One directory up from the CloudStack root dir you will find:
::
- cloudstack_4.2.0_amd64.changes
- cloudstack_4.2.0.dsc
- cloudstack_4.2.0.tar.gz
- cloudstack-agent_4.2.0_all.deb
- cloudstack-awsapi_4.2.0_all.deb
- cloudstack-cli_4.2.0_all.deb
- cloudstack-common_4.2.0_all.deb
- cloudstack-docs_4.2.0_all.deb
- cloudstack-management_4.2.0_all.deb
- cloudstack-usage_4.2.0_all.deb
+ cloudstack_4.2.0_amd64.changes
+ cloudstack_4.2.0.dsc
+ cloudstack_4.2.0.tar.gz
+ cloudstack-agent_4.2.0_all.deb
+ cloudstack-awsapi_4.2.0_all.deb
+ cloudstack-cli_4.2.0_all.deb
+ cloudstack-common_4.2.0_all.deb
+ cloudstack-docs_4.2.0_all.deb
+ cloudstack-management_4.2.0_all.deb
+ cloudstack-usage_4.2.0_all.deb
Of course the community provides a repository for these packages and you
can use it instead of building your own packages and putting them in
your own repo. Instructions on how to use this community repository are
available in the installation book.
+
The CloudStack API
------------------
@@ -498,8 +529,8 @@ using the ``Generate Keys`` icon. You will see an ``API Key`` and
::
- API Key : XzAz0uC0t888gOzPs3HchY72qwDc7pUPIO8LxC-VkIHo4C3fvbEBY_Ccj8fo3mBapN5qRDg_0_EbGdbxi8oy1A
- Secret Key: zmBOXAXPlfb-LIygOxUVblAbz7E47eukDS_0JYUxP3JAmknOYo56T0R-AcM7rK7SMyo11Y6XW22gyuXzOdiybQ
+ API Key : XzAz0uC0t888gOzPs3HchY72qwDc7pUPIO8LxC-VkIHo4C3fvbEBY_Ccj8fo3mBapN5qRDg_0_EbGdbxi8oy1A
+ Secret Key: zmBOXAXPlfb-LIygOxUVblAbz7E47eukDS_0JYUxP3JAmknOYo56T0R-AcM7rK7SMyo11Y6XW22gyuXzOdiybQ
Open a Python shell and import the basic modules necessary to make the
request. Do note that this request could be made many different ways,
@@ -511,15 +542,15 @@ encoded using the ``base64`` module.
::
- $python
- Python 2.7.3 (default, Nov 17 2012, 19:54:34)
- [GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
- Type "help", "copyright", "credits" or "license" for more information.
- >>> import urllib2
- >>> import urllib
- >>> import hashlib
- >>> import hmac
- >>> import base64
+ $python
+ Python 2.7.3 (default, Nov 17 2012, 19:54:34)
+ [GCC 4.2.1 Compatible Apple Clang 4.1 ((tags/Apple/clang-421.11.66))] on darwin
+ Type "help", "copyright", "credits" or "license" for more information.
+ >>> import urllib2
+ >>> import urllib
+ >>> import hashlib
+ >>> import hmac
+ >>> import base64
Define the endpoint of the Cloud, the command that you want to execute,
the type of the response (i.e XML or JSON) and the keys of the user.
@@ -528,21 +559,21 @@ it is only used to compute the hmac.
::
- >>> baseurl='http://localhost:8080/client/api?'
- >>> request={}
- >>> request['command']='listUsers'
- >>> request['response']='json'
- >>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
- >>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
+ >>> baseurl='http://localhost:8080/client/api?'
+ >>> request={}
+ >>> request['command']='listUsers'
+ >>> request['response']='json'
+ >>> request['apikey']='plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg'
+ >>> secretkey='VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ'
Build the base request string, the combination of all the key/pairs of
the request, url encoded and joined with ampersand.
::
- >>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
- >>> request_str
- 'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
+ >>> request_str='&'.join(['='.join([k,urllib.quote_plus(request[k])]) for k in request.keys()])
+ >>> request_str
+ 'apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json'
Compute the signature with hmac, do a 64 bit encoding and a url
encoding, the string used for the signature is similar to the base
@@ -551,37 +582,53 @@ joined in a sorted order
::
- >>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
- >>> sig_str
- 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
- >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
- >>> sig
- 'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
- >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
- >>> sig
- 'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
- >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
- >>> sig
- 'TTpdDq/7j/J58XCRHomKoQXEQds='
- >>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
+ >>> sig_str='&'.join(['='.join([k.lower(),urllib.quote_plus(request[k].lower().replace('+','%20'))])for k in sorted(request.iterkeys())])
+ >>> sig_str
+ 'apikey=plgwjfzk4gys3momtvmjuvg-x-jlwlnfauj9gabbbf9edm-kaymmailqzzq1elzlyq_u38zcm0bewzgudp66mg&command=listusers&response=json'
+ >>> sig=hmac.new(secretkey,sig_str,hashlib.sha1).digest()
+ >>> sig
+ 'M:]\x0e\xaf\xfb\x8f\xf2y\xf1p\x91\x1e\x89\x8a\xa1\x05\xc4A\xdb'
+ >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest())
+ >>> sig
+ 'TTpdDq/7j/J58XCRHomKoQXEQds=\n'
+ >>> sig=base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip()
+ >>> sig
+ 'TTpdDq/7j/J58XCRHomKoQXEQds='
+ >>> sig=urllib.quote_plus(base64.encodestring(hmac.new(secretkey,sig_str,hashlib.sha1).digest()).strip())
Finally, build the entire string by joining the baseurl, the request str
and the signature. Then do an http GET:
::
- >>> req=baseurl+request_str+'&signature='+sig
- >>> req
- 'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
- >>> res=urllib2.urlopen(req)
- >>> res.read()
- '{ "listusersresponse" : { "count":1 ,"user" : [ {"id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a","username":"admin","firstname":"admin",
- "lastname":"cloud","created":"2012-07-05T12:18:27-0700","state":"enabled","account":"admin",
- "accounttype":1,"domainid":"8a111e58-e155-4482-93ce-84efff3c7c77","domain":"ROOT",
- "apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg",
- "secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ",
- "accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"}]}}
-
+ >>> req=baseurl+request_str+'&signature='+sig
+ >>> req
+ 'http://localhost:8080/client/api?apikey=plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg&command=listUsers&response=json&signature=TTpdDq%2F7j%2FJ58XCRHomKoQXEQds%3D'
+ >>> res=urllib2.urlopen(req)
+ >>> res.read()
+ {
+ "listusersresponse" : {
+ "count":1 ,
+ "user" : [
+ {
+ "id":"7ed6d5da-93b2-4545-a502-23d20b48ef2a",
+ "username":"admin",
+ "firstname":"admin",
+ "lastname":"cloud",
+ "created":"2012-07-05T12:18:27-0700",
+ "state":"enabled",
+ "account":"admin",
+ "accounttype":1,
+ "domainid":"8a111e58-e155-4482-93ce-84efff3c7c77",
+ "domain":"ROOT",
+ "apikey":"plgWJfZK4gyS3mOMTVmjUVg-X-jlWlnfaUJ9GAbBbf9EdM-kAYMmAiLqzzq1ElZLYq_u38zCm0bewzGUdP66mg",
+ "secretkey":"VDaACYb0LV9eNjTetIOElcVQkvJck_J_QljX_FcHRj87ZKiy0z0ty0ZsYBkoXkY9b7eq1EhwJaw7FF3akA3KBQ",
+ "accountid":"7548ac03-af1d-4c1c-9064-2f3e2c0eda0d"
+ }
+ ]
+ }
+ }
+
All the clients that you will find on github will implement this
signature technique, you should not have to do it by hand. Now that you
@@ -592,6 +639,7 @@ is a sub-project of Apache CloudStack and gives operators/developers the
ability to use any of the API methods. It has nice auto-completion and
help feature as well as an API discovery mechanism since 4.2.
+
Testing the AWS API interface
-----------------------------
@@ -608,7 +656,7 @@ start the AWS API interface in a separate shell with:
::
- mvn -Pawsapi -pl :cloud-awsapi jetty:run
+ mvn -Pawsapi -pl :cloud-awsapi jetty:run
Log into the CloudStack UI ``http://localhost:8080/client``, go to
*Service Offerings* and edit one of the compute offerings to have the
@@ -619,24 +667,25 @@ to use Python `Boto <http://docs.pythonboto.org/en/latest/>`__ module:
::
- import boto
- import boto.ec2
+ import boto
+ import boto.ec2
- accesskey="2IUSA5xylbsPSnBQFoWXKg3RvjHgsufcKhC1SeiCbeEc0obKwUlwJamB_gFmMJkFHYHTIafpUx0pHcfLvt-dzw"
- secretkey="oxV5Dhhk5ufNowey7OVHgWxCBVS4deTl9qL0EqMthfPBuy3ScHPo2fifDxw1aXeL5cyH10hnLOKjyKphcXGeDA"
+ accesskey="2IUSA5xylbsPSnBQFoWXKg3RvjHgsufcKhC1SeiCbeEc0obKwUlwJamB_gFmMJkFHYHTIafpUx0pHcfLvt-dzw"
+ secretkey="oxV5Dhhk5ufNowey7OVHgWxCBVS4deTl9qL0EqMthfPBuy3ScHPo2fifDxw1aXeL5cyH10hnLOKjyKphcXGeDA"
- region = boto.ec2.regioninfo.RegionInfo(name="ROOT", endpoint="localhost")
- conn = boto.connect_ec2(aws_access_key_id=accesskey, aws_secret_access_key=secretkey, is_secure=False, region=region, port=7080, path="/awsapi", api_version="2012-08-15")
+ region = boto.ec2.regioninfo.RegionInfo(name="ROOT", endpoint="localhost")
+ conn = boto.connect_ec2(aws_access_key_id=accesskey, aws_secret_access_key=secretkey, is_secure=False, region=region, port=7080, path="/awsapi", api_version="2012-08-15")
- images=conn.get_all_images()
- print images
+ images=conn.get_all_images()
+ print images
- res = images[0].run(instance_type='m1.small',security_groups=['default'])
+ res = images[0].run(instance_type='m1.small',security_groups=['default'])
Note the new ``api_version`` number in the connection object and also
note that there was no user registration to make like in previous
CloudStack releases.
+
Conclusions
-----------
[2/4] fixed the formatting in all the files and added the license to
each file: This closes #4
Posted by se...@apache.org.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/index.rst
----------------------------------------------------------------------
diff --git a/rtd/source/index.rst b/rtd/source/index.rst
index 3972486..398a1f6 100644
--- a/rtd/source/index.rst
+++ b/rtd/source/index.rst
@@ -1,69 +1,97 @@
+.. 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.
+
.. CloudStack Documentation documentation master file, created by
sphinx-quickstart on Sat Nov 2 11:17:30 2013.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
+
Welcome to CloudStack Documentation !
=====================================
.. figure:: /_static/images/acslogo.png
- :align: center
+ :align: center
-.. warning:: We are in the process of changing documentation format as well as hosting mechanism.
- Please be patient with us as we migrate our entire documentation to this new setup.
+.. warning::
+ We are in the process of changing documentation format as well as hosting
+ mechanism. Please be patient with us as we migrate our entire documentation
+ to this new setup.
.. toctree::
+
Introduction
------------
-If you are new to CloudStack you should go through this short introduction on concepts and terminology before proceeding to the installation or administration guides.
+If you are new to CloudStack you should go through this short introduction on
+concepts and terminology before proceeding to the installation or
+administration guides.
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
+
+ concepts
- concepts
Navigating the docs
-------------------
-Now that you have gone over the basic concepts of CloudStack you are ready to dive into installation and operation documentation.
+Now that you have gone over the basic concepts of CloudStack you are ready to
+dive into installation and operation documentation.
-- `Installation Guide <http://docs.cloudstack.apache.org/projects/cloudstack-installation>`_
+- `Installation Guide
+ <http://docs.cloudstack.apache.org/projects/cloudstack-installation>`_
-- `Administration Guide <http://docs.cloudstack.apache.org/projects/cloudstack-administration>`_
+- `Administration Guide
+ <http://docs.cloudstack.apache.org/projects/cloudstack-administration>`_
-- `Release Notes <http://docs.cloudstack.apache.org/projects/cloudstack-release-notes>`_
+- `Release Notes
+ <http://docs.cloudstack.apache.org/projects/cloudstack-release-notes>`_
-Below you will find very specific documentation on advanced networking_ which you can skip if you are just getting started.
-Developers will also find below a short developers_ guide.
+Below you will find very specific documentation on advanced networking_ which
+you can skip if you are just getting started. Developers will also find below
+a short developers_ guide.
.. _networking:
+
Advanced Networking Guides
--------------------------
.. toctree::
- :maxdepth: 2
+ :maxdepth: 2
- networking/nicira-plugin
- networking/midonet
- networking/vxlan.rst
- networking/ovs-plugin
- networking/ipv6
- networking/autoscale_without_netscaler.rst
+ networking/nicira-plugin
+ networking/midonet
+ networking/vxlan.rst
+ networking/ovs-plugin
+ networking/ipv6
+ networking/autoscale_without_netscaler.rst
.. _developers:
+
Developers Guide
----------------
.. toctree::
- :maxdepth: 2
-
- developer_guide
- dev
- plugins
- alloc.rst
- ansible
+ :maxdepth: 2
+ developer_guide
+ dev
+ plugins
+ alloc.rst
+ ansible
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/autoscale_without_netscaler.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/autoscale_without_netscaler.rst b/rtd/source/networking/autoscale_without_netscaler.rst
index 9dbac42..b35eaaf 100644
--- a/rtd/source/networking/autoscale_without_netscaler.rst
+++ b/rtd/source/networking/autoscale_without_netscaler.rst
@@ -1,87 +1,177 @@
+.. 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.
+
+
Configuring AutoScale without using NetScaler
=============================================
-.. warning:: This feature is currently only available on the master branch and will be released in the 4.4 release.
+.. warning::
+ This feature is currently only available on the master branch and will be
+ released in the 4.4 release.
+
What is AutoScaling?
-~~~~~~~~~~~~~~~~~~~~
+--------------------
+
+AutoScaling allows you to scale your back-end services or application VMs up
+or down seamlessly and automatically according to the conditions you define.
+With AutoScaling enabled, you can ensure that the number of VMs you are using
+seamlessly scale up when demand increases, and automatically decreases when
+demand subsides. Thus it helps you save compute costs by terminating underused
+VMs automatically and launching new VMs when you need them, without the need
+for manual intervention.
-AutoScaling allows you to scale your back-end services or application VMs up or down seamlessly and automatically according to the conditions you define. With AutoScaling enabled, you can ensure that the number of VMs you are using seamlessly scale up when demand increases, and automatically decreases when demand subsides. Thus it helps you save compute costs by terminating underused VMs automatically and launching new VMs when you need them, without the need for manual intervention.
Hypervisor support
-~~~~~~~~~~~~~~~~~~
+------------------
+
+At that time, AutoScaling without NetScaler only supports for Xenserver. We
+are working to support KVM also.
-At that time, AutoScaling without NetScaler only supports for Xenserver. We are working to support KVM also.
Prerequisites
-~~~~~~~~~~~~~
+-------------
Before you configure an AutoScale rule, consider the following:
-* Ensure that the necessary template is prepared before configuring AutoScale. Firstly you must install the PV-driver, which helps Xenserver collect performance parameters (CPU and memory) into VMs. Beside, When a VM is deployed by using a template and when it comes up, the application should be up and running.
+- Ensure that the necessary template is prepared before configuring AutoScale.
+ Firstly you must install the PV-driver, which helps Xenserver collect
+ performance parameters (CPU and memory) into VMs. Beside, When a VM is
+ deployed by using a template and when it comes up, the application should be
+ up and running.
+
Configuration
-~~~~~~~~~~~~~
+-------------
Specify the following:
.. image:: ../_static/images/autoscale-config.png
-* Template: A template consists of a base OS image and application. A template is used to provision the new instance of an application on a scaleup action. When a VM is deployed from a template, the VM can start taking the traffic from the load balancer without any admin intervention. For example, if the VM is deployed for a Web service, it should have the Web server running, the database connected, and so on.
+- Template: A template consists of a base OS image and application. A
+ template is used to provision the new instance of an application on a
+ scaleup action. When a VM is deployed from a template, the VM can start
+ taking the traffic from the load balancer without any admin intervention.
+ For example, if the VM is deployed for a Web service, it should have the
+ Web server running, the database connected, and so on.
+
+- Compute offering: A predefined set of virtual hardware attributes,
+ including CPU speed, number of CPUs, and RAM size, that the user can select
+ when creating a new virtual machine instance. Choose one of the compute
+ offerings to be used while provisioning a VM instance as part of scaleup
+ action.
+
+- Min Instance: The minimum number of active VM instances that is assigned to
+ a load balancing rule. The active VM instances are the application
+ instances that are up and serving the traffic, and are being load balanced.
+ This parameter ensures that a load balancing rule has at least the
+ configured number of active VM instances are available to serve the traffic.
+
+- Max Instance: Maximum number of active VM instances that should be assigned
+ to a load balancing rule. This parameter defines the upper limit of active
+ VM instances that can be assigned to a load balancing rule.
+
+ Specifying a large value for the maximum instance parameter might result in
+ provisioning large number of VM instances, which in turn leads to a single
+ load balancing rule exhausting the VM instances limit specified at the
+ account or domain level.
-* Compute offering: A predefined set of virtual hardware attributes, including CPU speed, number of CPUs, and RAM size, that the user can select when creating a new virtual machine instance. Choose one of the compute offerings to be used while provisioning a VM instance as part of scaleup action.
+Specify the following scale-up and scale-down policies:
-* Min Instance: The minimum number of active VM instances that is assigned to a load balancing rule. The active VM instances are the application instances that are up and serving the traffic, and are being load balanced. This parameter ensures that a load balancing rule has at least the configured number of active VM instances are available to serve the traffic.
+- Duration: The duration, in seconds, for which the conditions you specify
+ must be true to trigger a scaleup action. The conditions defined should
+ hold true for the entire duration you specify for an AutoScale action to be
+ invoked.
-* Max Instance: Maximum number of active VM instances that should be assigned to a load balancing rule. This parameter defines the upper limit of active VM instances that can be assigned to a load balancing rule.
+- Counter: The performance counters expose the state of the monitored
+ instances. We added two new counter to work with that feature:
-Specifying a large value for the maximum instance parameter might result in provisioning large number of VM instances, which in turn leads to a single load balancing rule exhausting the VM instances limit specified at the account or domain level.
+ - Linux User CPU [native] - percentage
+ - Linux User RAM [native] - percentage
-Specify the following scale-up and scale-down policies:
+ Remember to choose one of them. If you choose anything else, the
+ autoscaling will not work.
-* Duration: The duration, in seconds, for which the conditions you specify must be true to trigger a scaleup action. The conditions defined should hold true for the entire duration you specify for an AutoScale action to be invoked.
+- Operator: The following five relational operators are supported in
+ AutoScale feature: Greater than, Less than, Less than or equal to, Greater
+ than or equal to, and Equal to.
-* Counter: The performance counters expose the state of the monitored instances. We added two new counter to work with that feature:
+- Threshold: Threshold value to be used for the counter. Once the counter
+ defined above breaches the threshold value, the AutoScale feature initiates
+ a scaleup or scaledown action.
-- Linux User CPU [native] - percentage
-- Linux User RAM [native] - percentage
+- Add: Click Add to add the condition.
-Remember to choose one of them. If you choose anything else, the autoscaling will not work.
+ Additionally, if you want to configure the advanced settings, click Show
+ advanced settings, and specify the following:
-* Operator: The following five relational operators are supported in AutoScale feature: Greater than, Less than, Less than or equal to, Greater than or equal to, and Equal to.
+- Polling interval: Frequency in which the conditions, combination of counter,
+ operator and threshold, are to be evaluated before taking a scale up or
+ down action. The default polling interval is 30 seconds.
-* Threshold: Threshold value to be used for the counter. Once the counter defined above breaches the threshold value, the AutoScale feature initiates a scaleup or scaledown action.
+- Quiet Time: This is the cool down period after an AutoScale action is
+ initiated. The time includes the time taken to complete provisioning a VM
+ instance from its template and the time taken by an application to be ready
+ to serve traffic. This quiet time allows the fleet to come up to a stable
+ state before any action can take place. The default is 300 seconds.
-* Add: Click Add to add the condition.
+- Destroy VM Grace Period: The duration in seconds, after a scaledown action
+ is initiated, to wait before the VM is destroyed as part of scaledown
+ action. This is to ensure graceful close of any pending sessions or
+ transactions being served by the VM marked for destroy. The default is 120
+ seconds.
-Additionally, if you want to configure the advanced settings, click Show advanced settings, and specify the following:
+- Apply: Click Apply to create the AutoScale configuration.
-* Polling interval: Frequency in which the conditions, combination of counter, operator and threshold, are to be evaluated before taking a scale up or down action. The default polling interval is 30 seconds.
-* Quiet Time: This is the cool down period after an AutoScale action is initiated. The time includes the time taken to complete provisioning a VM instance from its template and the time taken by an application to be ready to serve traffic. This quiet time allows the fleet to come up to a stable state before any action can take place. The default is 300 seconds.
+Disabling and Enabling an AutoScale Configuration
+-------------------------------------------------
-* Destroy VM Grace Period: The duration in seconds, after a scaledown action is initiated, to wait before the VM is destroyed as part of scaledown action. This is to ensure graceful close of any pending sessions or transactions being served by the VM marked for destroy. The default is 120 seconds.
+If you want to perform any maintenance operation on the AutoScale VM instances,
+disable the AutoScale configuration. When the AutoScale configuration is
+disabled, no scaleup or scaledown action is performed. You can use this
+downtime for the maintenance activities. To disable the AutoScale
+configuration, click the Disable AutoScale button.
-* Apply: Click Apply to create the AutoScale configuration.
+The button toggles between enable and disable, depending on whether AutoScale
+is currently enabled or not. After the maintenance operations are done, you
+can enable the AutoScale configuration back. To enable, open the AutoScale
+configuration page again, then click the Enable AutoScale button.
-Disabling and Enabling an AutoScale Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-If you want to perform any maintenance operation on the AutoScale VM instances, disable the AutoScale configuration. When the AutoScale configuration is disabled, no scaleup or scaledown action is performed. You can use this downtime for the maintenance activities. To disable the AutoScale configuration, click the Disable AutoScale button.
+Updating an AutoScale Configuration
+-----------------------------------
-The button toggles between enable and disable, depending on whether AutoScale is currently enabled or not. After the maintenance operations are done, you can enable the AutoScale configuration back. To enable, open the AutoScale configuration page again, then click the Enable AutoScale button.
+You can update the various parameters and add or delete the conditions in a
+scaleup or scaledown rule. Before you update an AutoScale configuration,
+ensure that you disable the AutoScale load balancer rule by clicking the
+Disable AutoScale button.
-Updating an AutoScale Configuration
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+After you modify the required AutoScale parameters, click Apply. To apply the
+new AutoScale policies, open the AutoScale configuration page again, then
+click the Enable AutoScale button.
-You can update the various parameters and add or delete the conditions in a scaleup or scaledown rule. Before you update an AutoScale configuration, ensure that you disable the AutoScale load balancer rule by clicking the Disable AutoScale button.
-After you modify the required AutoScale parameters, click Apply. To apply the new AutoScale policies, open the AutoScale configuration page again, then click the Enable AutoScale button.
Runtime Considerations
-~~~~~~~~~~~~~~~~~~~~~~
-
-An administrator should not assign a VM to a load balancing rule which is configured for AutoScale.
+----------------------
-Making API calls outside the context of AutoScale, such as destroyVM, on an autoscaled VM leaves the load balancing configuration in an inconsistent state. Though VM is destroyed from the load balancer rule, it continues be showed as a service assigned to a rule inside the context of AutoScale.
+An administrator should not assign a VM to a load balancing rule which is
+configured for AutoScale.
+Making API calls outside the context of AutoScale, such as destroyVM, on an
+autoscaled VM leaves the load balancing configuration in an inconsistent state.
+Though VM is destroyed from the load balancer rule, it continues be showed as
+a service assigned to a rule inside the context of AutoScale.
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/ipv6.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/ipv6.rst b/rtd/source/networking/ipv6.rst
index 2e5a1b6..117fdc2 100644
--- a/rtd/source/networking/ipv6.rst
+++ b/rtd/source/networking/ipv6.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
IPv6 Support in CloudStack
===========================
@@ -19,17 +35,11 @@ support is only an experimental feature.
Here's the sequence of events when IPv6 is used:
-#.
-
- The administrator creates an IPv6 shared network in an advanced zone.
-
-#.
+#. The administrator creates an IPv6 shared network in an advanced zone.
- The user deploys a VM in an IPv6 shared network.
+#. The user deploys a VM in an IPv6 shared network.
-#.
-
- The user VM generates an IPv6 link local address by itself, and gets
+#. The user VM generates an IPv6 link local address by itself, and gets
an IPv6 global or site local address through DHCPv6.
@@ -38,48 +48,38 @@ Prerequisites and Guidelines
Consider the following:
--
-
- CIDR size must be 64 for IPv6 networks.
-
--
+- CIDR size must be 64 for IPv6 networks.
- The DHCP client of the guest VMs should support generating DUID based
+- The DHCP client of the guest VMs should support generating DUID based
on Link-layer Address (DUID- LL). DUID-LL derives from the MAC
address of guest VMs, and therefore the user VM can be identified by
using DUID. See `Dynamic Host Configuration Protocol for
IPv6 <http://tools.ietf.org/html/rfc3315>`__\ for more information.
--
-
- The gateway of the guest network generates Router Advisement and
+- The gateway of the guest network generates Router Advisement and
Response messages to Router Solicitation. The M (Managed Address
Configuration) flag of Router Advisement should enable stateful IP
address configuration. Set the M flag to where the end nodes receive
their IPv6 addresses from the DHCPv6 server as opposed to the router
or switch.
- .. note:: The M flag is the 1-bit Managed Address Configuration flag for Router
- Advisement. When set, Dynamic Host Configuration Protocol (DHCPv6) is
- available for address configuration in addition to any IPs set by
- using stateless address auto-configuration.
-
--
+ .. note::
+ The M flag is the 1-bit Managed Address Configuration flag for Router
+ Advisement. When set, Dynamic Host Configuration Protocol (DHCPv6) is
+ available for address configuration in addition to any IPs set by
+ using stateless address auto-configuration.
- Use the System VM template exclusively designed to support IPv6.
+- Use the System VM template exclusively designed to support IPv6.
Download the System VM template from
- `http://cloudstack.apt-get.eu/systemvm/ <http://cloudstack.apt-get.eu/systemvm/>`__.
-
--
+ `http://cloudstack.apt-get.eu/systemvm/
+ <http://cloudstack.apt-get.eu/systemvm/>`__.
- The concept of Default Network applies to IPv6 networks. However,
+- The concept of Default Network applies to IPv6 networks. However,
unlike IPv4 CloudStack does not control the routing information of
IPv6 in shared network; the choice of Default Network will not affect
the routing in the user VM.
--
-
- In a multiple shared network, the default route is set by the rack
+- In a multiple shared network, the default route is set by the rack
router, rather than the DHCP server, which is out of CloudStack
control. Therefore, in order for the user VM to get only the default
route from the default NIC, modify the configuration of the user VM,
@@ -88,22 +88,18 @@ Consider the following:
auto-configure ``/proc/sys/net/ipv6/conf/interface`` with received
data.
+
Limitations of IPv6 in CloudStack
---------------------------------
The following are not yet supported:
-#.
-
- Security groups
+#. Security groups
-#.
+#. Userdata and metadata
- Userdata and metadata
+#. Passwords
-#.
-
- Passwords
Guest VM Configuration for DHCPv6
---------------------------------
@@ -111,114 +107,93 @@ Guest VM Configuration for DHCPv6
For the guest VMs to get IPv6 address, run dhclient command manually on
each of the VMs. Use DUID-LL to set up dhclient.
-.. note:: The IPv6 address is lost when a VM is stopped and started. Therefore,
-use the same procedure to get an IPv6 address when a VM is stopped and
-started.
-
-#.
+.. note::
+ The IPv6 address is lost when a VM is stopped and started. Therefore,
+ use the same procedure to get an IPv6 address when a VM is stopped and
+ started.
- Set up dhclient by using DUID-LL.
+#. Set up dhclient by using DUID-LL.
Perform the following for DHCP Client 4.2 and above:
- #.
-
- Run the following command on the selected VM to get the dhcpv6
+ #. Run the following command on the selected VM to get the dhcpv6
offer from VR:
.. sourcecode:: bash
- dhclient -6 -D LL <dev>
+ dhclient -6 -D LL <dev>
Perform the following for DHCP Client 4.1:
- #.
-
- Open the following to the dhclient configuration file:
+ #. Open the following to the dhclient configuration file:
.. sourcecode:: bash
- vi /etc/dhcp/dhclient.conf
-
- #.
+ vi /etc/dhcp/dhclient.conf
- Add the following to the dhclient configuration file:
+ #. Add the following to the dhclient configuration file:
.. sourcecode:: bash
- send dhcp6.client-id = concat(00:03:00, hardware);
-
-#.
+ send dhcp6.client-id = concat(00:03:00, hardware);
- Get IPv6 address from DHCP server as part of the system or network
+#. Get IPv6 address from DHCP server as part of the system or network
restart.
Based on the operating systems, perform the following:
On CentOS 6.2:
- #.
-
- Open the Ethernet interface configuration file:
+ #. Open the Ethernet interface configuration file:
.. sourcecode:: bash
- vi /etc/sysconfig/network-scripts/ifcfg-eth0
+ vi /etc/sysconfig/network-scripts/ifcfg-eth0
The ``ifcfg-eth0`` file controls the first NIC in a system.
- #.
-
- Make the necessary configuration changes, as given below:
+ #. Make the necessary configuration changes, as given below:
.. sourcecode:: bash
- DEVICE=eth0
- HWADDR=06:A0:F0:00:00:38
- NM_CONTROLLED=no
- ONBOOT=yes
- BOOTPROTO=dhcp6
- TYPE=Ethernet
- USERCTL=no
- PEERDNS=yes
- IPV6INIT=yes
- DHCPV6C=yes
-
- #.
+ DEVICE=eth0
+ HWADDR=06:A0:F0:00:00:38
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ BOOTPROTO=dhcp6
+ TYPE=Ethernet
+ USERCTL=no
+ PEERDNS=yes
+ IPV6INIT=yes
+ DHCPV6C=yes
- Open the following:
+ #. Open the following:
.. sourcecode:: bash
- vi /etc/sysconfig/network
+ vi /etc/sysconfig/network
- #.
-
- Make the necessary configuration changes, as given below:
+ #. Make the necessary configuration changes, as given below:
.. sourcecode:: bash
- NETWORKING=yes
- HOSTNAME=centos62mgmt.lab.vmops.com
- NETWORKING_IPV6=yes
- IPV6_AUTOCONF=no
+ NETWORKING=yes
+ HOSTNAME=centos62mgmt.lab.vmops.com
+ NETWORKING_IPV6=yes
+ IPV6_AUTOCONF=no
On Ubuntu 12.10
- #.
-
- Open the following:
+ #. Open the following:
.. sourcecode:: bash
- etc/network/interfaces:
-
- #.
+ etc/network/interfaces:
- Make the necessary configuration changes, as given below:
+ #. Make the necessary configuration changes, as given below:
.. sourcecode:: bash
- iface eth0 inet6 dhcp
- autoconf 0
- accept_ra 1
+ iface eth0 inet6 dhcp
+ autoconf 0
+ accept_ra 1
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/midonet.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/midonet.rst b/rtd/source/networking/midonet.rst
index 73d7ab2..a82fa44 100644
--- a/rtd/source/networking/midonet.rst
+++ b/rtd/source/networking/midonet.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
The MidoNet Plugin
==================
@@ -9,11 +25,13 @@ networking solution as a provider for CloudStack networks and services. For
more information on MidoNet and how it works, see
http://www.midokura.com/midonet/.
+
Features of the MidoNet Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-.. note:: In CloudStack 4.2.0 only the KVM hypervisor is supported for use in
- combination with MidoNet.
+.. note::
+ In CloudStack 4.2.0 only the KVM hypervisor is supported for use in
+ combination with MidoNet.
In CloudStack release 4.2.0 this plugin supports several services in the
Advanced Isolated network mode.
@@ -39,6 +57,7 @@ supported in the 4.2.0 release:
The plugin has been tested with MidoNet version 12.12. (Caddo).
+
Using the MidoNet Plugin
------------------------
@@ -50,11 +69,11 @@ the MidoNet Agent, and the MidoNet API server must be available. Please
consult the MidoNet User Guide for more information. The following
section describes the CloudStack side setup.
-1. CloudStack needs to have at least one physical network with the
+#. CloudStack needs to have at least one physical network with the
isolation method set to "MIDO". This network should be enabled for
the Guest and Public traffic types.
-2. Next, we need to set the following CloudStack settings under "Global
+#. Next, we need to set the following CloudStack settings under "Global
Settings" in the UI:
+-----------------------------+------------------------------------------------------------------------+--------------------------------------------+
@@ -67,33 +86,35 @@ section describes the CloudStack side setup.
Table: CloudStack settings
-3. We also want MidoNet to take care of public traffic, so in
+#. We also want MidoNet to take care of public traffic, so in
*componentContext.xml* we need to replace this line:
::
- <bean id="PublicNetworkGuru" class="com.cloud.network.guru.PublicNetworkGuru">
+ <bean id="PublicNetworkGuru" class="com.cloud.network.guru.PublicNetworkGuru">
With this:
::
- <bean id="PublicNetworkGuru" class="com.cloud.network.guru.MidoNetPublicNetworkGuru">
+ <bean id="PublicNetworkGuru" class="com.cloud.network.guru.MidoNetPublicNetworkGuru">
-.. note:: On the compute host, MidoNet takes advantage of per-traffic type VIF
- driver support in CloudStack KVM.
+.. note::
+ On the compute host, MidoNet takes advantage of per-traffic type VIF
+ driver support in CloudStack KVM.
- In agent.properties, we set the following to make MidoNet take care
- of Guest and Public traffic:
+ In agent.properties, we set the following to make MidoNet take care
+ of Guest and Public traffic:
- ::
+ ::
+
+ libvirt.vif.driver.Guest=com.cloud.network.resource.MidoNetVifDriver
+ libvirt.vif.driver.Public=com.cloud.network.resource.MidoNetVifDriver
- libvirt.vif.driver.Guest=com.cloud.network.resource.MidoNetVifDriver
- libvirt.vif.driver.Public=com.cloud.network.resource.MidoNetVifDriver
+ This is explained further in MidoNet User Guide.
- This is explained further in MidoNet User Guide.
Enabling the MidoNet service provider via the UI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -103,21 +124,22 @@ needs to be enabled on the physical network.
The steps to enable via the UI are as follows:
-1. In the left navbar, click Infrastructure
+#. In the left navbar, click Infrastructure
-2. In Zones, click View All
+#. In Zones, click View All
-3. Click the name of the Zone on which you are setting up MidoNet
+#. Click the name of the Zone on which you are setting up MidoNet
-4. Click the Physical Network tab
+#. Click the Physical Network tab
-5. Click the Name of the Network on which you are setting up MidoNet
+#. Click the Name of the Network on which you are setting up MidoNet
-6. Click Configure on the Network Service Providers box
+#. Click Configure on the Network Service Providers box
-7. Click on the name MidoNet
+#. Click on the name MidoNet
+
+#. Click the Enable Provider button in the Network tab
-8. Click the Enable Provider button in the Network tab
Enabling the MidoNet service provider via the API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -136,6 +158,7 @@ To enable via the API, use the following API calls:
- state = "Enabled"
+
Revision History
----------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/nicira-plugin.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/nicira-plugin.rst b/rtd/source/networking/nicira-plugin.rst
index b644f16..cbff59c 100644
--- a/rtd/source/networking/nicira-plugin.rst
+++ b/rtd/source/networking/nicira-plugin.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
The Nicira NVP Plugin
=====================
@@ -9,6 +25,7 @@ implementations in CloudStack. With the plugin an exisiting Nicira NVP
setup can be used by CloudStack to implement isolated guest networks and
to provide additional services like routing and NAT.
+
Features of the Nicira NVP Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -29,8 +46,9 @@ the Nicira NVP Plugin.
Table: Supported Services
-.. note:: The Virtual Networking service was originally called 'Connectivity'
- in CloudStack 4.0
+.. note::
+ The Virtual Networking service was originally called 'Connectivity'
+ in CloudStack 4.0
The following hypervisors are supported by the Nicira NVP Plugin.
@@ -44,8 +62,10 @@ The following hypervisors are supported by the Nicira NVP Plugin.
Table: Supported Hypervisors
-.. note:: Please refer to the Nicira NVP configuration guide on how to prepare
- the hypervisors for Nicira NVP integration.
+.. note::
+ Please refer to the Nicira NVP configuration guide on how to prepare
+ the hypervisors for Nicira NVP integration.
+
Configuring the Nicira NVP Plugin
---------------------------------
@@ -71,8 +91,10 @@ Make sure you have the following information ready:
services.
-.. note:: The gateway service uuid is optional and is used for Layer 3
- services only (SourceNat, StaticNat and PortForwarding)
+.. note::
+ The gateway service uuid is optional and is used for Layer 3
+ services only (SourceNat, StaticNat and PortForwarding)
+
Zone Configuration
~~~~~~~~~~~~~~~~~~
@@ -81,14 +103,16 @@ CloudStack needs to have at least one physical network with the isolation
method set to "STT". This network should be enabled for the Guest
traffic type.
-.. note:: The Guest traffic type should be configured with the traffic label
- that matches the name of the Integration Bridge on the hypervisor.
- See the Nicira NVP User Guide for more details on how to set this up
- in XenServer or KVM.
+.. note::
+ The Guest traffic type should be configured with the traffic label
+ that matches the name of the Integration Bridge on the hypervisor.
+ See the Nicira NVP User Guide for more details on how to set this up
+ in XenServer or KVM.
.. figure:: /_static/images/nvp-physical-network-stt.png
- :align: center
- :alt: a screenshot of a physical network with the STT isolation type
+ :align: center
+ :alt: a screenshot of a physical network with the STT isolation type
+
Enabling the service provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -98,13 +122,15 @@ Service Providers" configuration of the physical network with the STT
isolation type. Navigate to the Nicira NVP provider and press the
"Enable Provider" button.
-.. note:: CloudStack 4.0 does not have the UI interface to configure the
- Nicira NVP plugin. Configuration needs to be done using the API
- directly.
+.. note::
+ CloudStack 4.0 does not have the UI interface to configure the
+ Nicira NVP plugin. Configuration needs to be done using the API
+ directly.
.. figure:: /_static/images/nvp-physical-network-stt.png
- :align: center
- :alt: a screenshot of an enabled Nicira NVP provider
+ :align: center
+ :alt: a screenshot of an enabled Nicira NVP provider
+
Device Management
~~~~~~~~~~~~~~~~~
@@ -116,8 +142,9 @@ network. Press the "Add NVP Controller" button on the provider panel and
enter the configuration details.
.. figure:: /_static/images/nvp-physical-network-stt.png
- :align: center
- :alt: a screenshot of the device configuration popup.
+ :align: center
+ :alt: a screenshot of the device configuration popup.
+
Network Offerings
~~~~~~~~~~~~~~~~~
@@ -155,12 +182,13 @@ Table: Isolated network offering with regular services from the Virtual
Router.
.. figure:: /_static/images/nvp-physical-network-stt.png
- :align: center
- :alt: a screenshot of a network offering.
+ :align: center
+ :alt: a screenshot of a network offering.
-.. note:: The tag in the network offering should be set to the name of the
- physical network with the NVP provider.
+.. note::
+ The tag in the network offering should be set to the name of the
+ physical network with the NVP provider.
Isolated network with network services. The virtual router is still
required to provide network services like dns and dhcp.
@@ -185,6 +213,7 @@ required to provide network services like dns and dhcp.
Table: Isolated network offering with network services
+
Using the Nicira NVP plugin with VPC
------------------------------------
@@ -201,6 +230,7 @@ Router
It is not possible to connect a private gateway using a Nicira NVP
Logical Switch
+
VPC Offering with Nicira NVP
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -221,13 +251,15 @@ to the 'vpc\_offering\_service\_map' with service 'Connectivity' and
provider 'NiciraNvp'
.. figure:: /_static/images/nvp-physical-network-stt.png
- :align: center
- :alt: a screenshot of the mysql table.
+ :align: center
+ :alt: a screenshot of the mysql table.
-.. note:: When creating a new VPC offering please note that the UI does not
- allow you to select a VPC offering yet. The VPC needs to be created
- using the API with the offering UUID.
+.. note::
+ When creating a new VPC offering please note that the UI does not
+ allow you to select a VPC offering yet. The VPC needs to be created
+ using the API with the offering UUID.
+
VPC Network Offerings
~~~~~~~~~~~~~~~~~~~~~
@@ -267,6 +299,7 @@ with the loadbalancing service enabled and one without loadbalancing.
Table: VPC Network Offering with Loadbalancing
+
Troubleshooting the Nicira NVP Plugin
-------------------------------------
@@ -284,9 +317,11 @@ network on the NVP Controller.
The Nics that are connected to one of the Logical Switches will have
their Logical Switch Port UUID listed in the nicira\_nvp\_nic\_map table
-.. note:: All devices created on the NVP Controller will have a tag set to
- domain-account of the owner of the network, this string can be used
- to search for items in the NVP Controller.
+.. note::
+ All devices created on the NVP Controller will have a tag set to
+ domain-account of the owner of the network, this string can be used
+ to search for items in the NVP Controller.
+
Database tables
~~~~~~~~~~~~~~~
@@ -332,7 +367,9 @@ Table: external\_nicira\_nvp\_devices
Table: nicira\_nvp\_router\_map
-.. note:: nicira\_nvp\_router\_map is only available in CloudStack 4.1 and above
+.. note::
+ nicira\_nvp\_router\_map is only available in CloudStack 4.1 and above
+
Revision History
----------------
@@ -341,6 +378,7 @@ Revision History
for 4.0.0-incubating version of the NVP Plugin 1-0 Wed May 22 2013 Hugo
Trippaers hugo@apache.org Documentation updated for CloudStack 4.1.0
+
.. | nvp-physical-network-stt.png: a screenshot of a physical network with the STT isolation type | image:: ./images/nvp-physical-network-stt.png
.. | nvp-physical-network-stt.png: a screenshot of an enabled Nicira NVP provider | image:: ./images/nvp-enable-provider.png
.. | nvp-physical-network-stt.png: a screenshot of the device configuration popup. | image:: ./images/nvp-add-controller.png
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/ovs-plugin.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/ovs-plugin.rst b/rtd/source/networking/ovs-plugin.rst
index 495b304..90892b5 100644
--- a/rtd/source/networking/ovs-plugin.rst
+++ b/rtd/source/networking/ovs-plugin.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
The OVS Plugin
==============
@@ -5,8 +21,10 @@ Introduction to the OVS Plugin
------------------------------
The OVS plugin is the native SDN
-implementations in CloudStack, using GRE isolation method. The plugin can be used by CloudStack to implement isolated guest networks and
-to provide additional services like NAT, port forwarding and load balancing.
+implementations in CloudStack, using GRE isolation method. The plugin can be
+used by CloudStack to implement isolated guest networks and to provide
+additional services like NAT, port forwarding and load balancing.
+
Features of the OVS Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -28,8 +46,9 @@ the OVS Plugin.
Table: Supported Services
-.. note:: The Virtual Networking service was originally called 'Connectivity'
- in CloudStack 4.0
+.. note::
+ The Virtual Networking service was originally called 'Connectivity'
+ in CloudStack 4.0
The following hypervisors are supported by the OVS Plugin.
@@ -50,12 +69,20 @@ Configuring the OVS Plugin
Prerequisites
~~~~~~~~~~~~~
-Before enabling the OVS plugin the hypervisor needs to be install OpenvSwitch. Default, XenServer has already installed OpenvSwitch. However, you must install OpenvSwitch manually on KVM. CentOS 6.4 and OpenvSwitch 1.10 are recommended.
+Before enabling the OVS plugin the hypervisor needs to be install OpenvSwitch.
+Default, XenServer has already installed OpenvSwitch. However, you must
+install OpenvSwitch manually on KVM. CentOS 6.4 and OpenvSwitch 1.10 are
+recommended.
KVM hypervisor:
-- CentOS 6.4 is recommended.
-- To make sure that the native bridge module will not interfere with openvSwitch the bridge module should be added to the blacklist. See the modprobe documentation for your distribution on where to find the blacklist. Make sure the module is not loaded either by rebooting or executing rmmod bridge before executing next steps.
+- CentOS 6.4 is recommended.
+
+- To make sure that the native bridge module will not interfere with
+ openvSwitch the bridge module should be added to the blacklist. See the
+ modprobe documentation for your distribution on where to find the blacklist.
+ Make sure the module is not loaded either by rebooting or executing rmmod
+ bridge before executing next steps.
Zone Configuration
@@ -66,76 +93,82 @@ method set to “GRE”. This network should be enabled for the Guest
traffic type.
.. note::
- With KVM, the traffic type should be configured with the traffic label
- that matches the name of the Integration Bridge on the hypervisor. For example, you should set the traffic label as following:
- - Management & Storage traffic: cloudbr0
- - Guest & Public traffic: cloudbr1
- See KVM networking configuration guide for more detail.
+ With KVM, the traffic type should be configured with the traffic label
+ that matches the name of the Integration Bridge on the hypervisor. For
+ example, you should set the traffic label as following:
+
+ - Management & Storage traffic: cloudbr0
+
+ - Guest & Public traffic: cloudbr1
+ See KVM networking configuration guide for more detail.
.. figure:: /_static/images/ovs-physical-network-gre.png
- :align: center
- :alt: a screenshot of a physical network with the GRE isolation type
+ :align: center
+ :alt: a screenshot of a physical network with the GRE isolation type
+
Agent Configuration
~~~~~~~~~~~~~~~~~~~
-.. note:: Only for KVM hypervisor
-
-* Configure network interfaces:
-
-::
-
- /etc/sysconfig/network-scripts/ifcfg-eth0
- DEVICE=eth0
- BOOTPROTO=none
- IPV6INIT=no
- NM_CONTROLLED=no
- ONBOOT=yes
- TYPE=OVSPort
- DEVICETYPE=ovs
- OVS_BRIDGE=cloudbr0
-
- /etc/sysconfig/network-scripts/ifcfg-eth1
- DEVICE=eth1
- BOOTPROTO=none
- IPV6INIT=no
- NM_CONTROLLED=no
- ONBOOT=yes
- TYPE=OVSPort
- DEVICETYPE=ovs
- OVS_BRIDGE=cloudbr1
-
- /etc/sysconfig/network-scripts/ifcfg-cloudbr0
- DEVICE=cloudbr0
- ONBOOT=yes
- DEVICETYPE=ovs
- TYPE=OVSBridge
- BOOTPROTO=static
- IPADDR=172.16.10.10
- GATEWAY=172.16.10.1
- NETMASK=255.255.255.0
- HOTPLUG=no
-
- /etc/sysconfig/network-scripts/ifcfg-cloudbr1
- DEVICE=cloudbr1
- ONBOOT=yes
- DEVICETYPE=ovs
- TYPE=OVSBridge
- BOOTPROTO=none
- HOTPLUG=no
-
- /etc/sysconfig/network
- NETWORKING=yes
- HOSTNAME=testkvm1
- GATEWAY=172.10.10.1
-
-* Edit /etc/cloudstack/agent/agent.properties
-
-::
-
- network.bridge.type=openvswitch
- libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.OvsVifDriver
+.. note::
+ Only for KVM hypervisor
+
+- Configure network interfaces:
+
+ ::
+
+ /etc/sysconfig/network-scripts/ifcfg-eth0
+ DEVICE=eth0
+ BOOTPROTO=none
+ IPV6INIT=no
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=OVSPort
+ DEVICETYPE=ovs
+ OVS_BRIDGE=cloudbr0
+
+ /etc/sysconfig/network-scripts/ifcfg-eth1
+ DEVICE=eth1
+ BOOTPROTO=none
+ IPV6INIT=no
+ NM_CONTROLLED=no
+ ONBOOT=yes
+ TYPE=OVSPort
+ DEVICETYPE=ovs
+ OVS_BRIDGE=cloudbr1
+
+ /etc/sysconfig/network-scripts/ifcfg-cloudbr0
+ DEVICE=cloudbr0
+ ONBOOT=yes
+ DEVICETYPE=ovs
+ TYPE=OVSBridge
+ BOOTPROTO=static
+ IPADDR=172.16.10.10
+ GATEWAY=172.16.10.1
+ NETMASK=255.255.255.0
+ HOTPLUG=no
+
+ /etc/sysconfig/network-scripts/ifcfg-cloudbr1
+ DEVICE=cloudbr1
+ ONBOOT=yes
+ DEVICETYPE=ovs
+ TYPE=OVSBridge
+ BOOTPROTO=none
+ HOTPLUG=no
+
+ /etc/sysconfig/network
+ NETWORKING=yes
+ HOSTNAME=testkvm1
+ GATEWAY=172.10.10.1
+
+- Edit /etc/cloudstack/agent/agent.properties
+
+ ::
+
+ network.bridge.type=openvswitch
+ libvirt.vif.driver=com.cloud.hypervisor.kvm.resource.OvsVifDriver
+
Enabling the service provider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -146,8 +179,9 @@ isolation type. Navigate to the OVS provider and press the
"Enable Provider" button.
.. figure:: /_static/images/ovs-physical-network-gre-enable.png
- :align: center
- :alt: a screenshot of an enabled OVS provider
+ :align: center
+ :alt: a screenshot of an enabled OVS provider
+
Network Offerings
~~~~~~~~~~~~~~~~~
@@ -168,29 +202,30 @@ OVS plugin.
+----------------------+-----------------+
| Firewall | VirtualRouter |
+----------------------+-----------------+
-| Load Balancer | OVS |
+| Load Balancer | OVS |
+----------------------+-----------------+
| User Data | VirtualRouter |
+----------------------+-----------------+
| Source NAT | VirtualRouter |
+----------------------+-----------------+
-| Static NAT | OVS |
+| Static NAT | OVS |
+----------------------+-----------------+
-| Post Forwarding | OVS |
+| Post Forwarding | OVS |
+----------------------+-----------------+
-| Virtual Networking | OVS |
+| Virtual Networking | OVS |
+----------------------+-----------------+
Table: Isolated network offering with regular services from the Virtual
Router.
.. figure:: /_static/images/ovs-network-offering.png
- :align: center
- :alt: a screenshot of a network offering.
+ :align: center
+ :alt: a screenshot of a network offering.
-.. note:: The tag in the network offering should be set to the name of the
- physical network with the OVS provider.
+.. note::
+ The tag in the network offering should be set to the name of the
+ physical network with the OVS provider.
Isolated network with network services. The virtual router is still
required to provide network services like dns and dhcp.
@@ -206,22 +241,24 @@ required to provide network services like dns and dhcp.
+----------------------+-----------------+
| Source NAT | VirtualRouter |
+----------------------+-----------------+
-| Static NAT | OVS |
+| Static NAT | OVS |
+----------------------+-----------------+
-| Post Forwarding | OVS |
+| Post Forwarding | OVS |
+----------------------+-----------------+
-| Load Balancing | OVS |
+| Load Balancing | OVS |
+----------------------+-----------------+
-| Virtual Networking | OVS |
+| Virtual Networking | OVS |
+----------------------+-----------------+
Table: Isolated network offering with network services
+
Using the OVS plugin with VPC
-----------------------------
OVS plugin does not work with VPC at that time
+
Revision History
----------------
http://git-wip-us.apache.org/repos/asf/cloudstack-docs/blob/e55976f3/rtd/source/networking/vxlan.rst
----------------------------------------------------------------------
diff --git a/rtd/source/networking/vxlan.rst b/rtd/source/networking/vxlan.rst
index 24520a3..d3b54a8 100644
--- a/rtd/source/networking/vxlan.rst
+++ b/rtd/source/networking/vxlan.rst
@@ -1,3 +1,19 @@
+.. 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.
+
+
The VXLAN Plugin
================
@@ -21,6 +37,7 @@ The following table lists the requirements for the hypervisor.
Table: Hypervisor Requirement for VXLAN
+
Linux Distributions that meet the requirements
----------------------------------------------
@@ -39,6 +56,7 @@ The following table lists distributions which meet requirements.
Table: List of Linux distributions which meet the hypervisor
requirements
+
Check the capability of your system
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -46,13 +64,13 @@ To check the capability of your system, execute the following commands.
::
- $ sudo modprobe vxlan && echo $?
- # Confirm the output is "0".
- # If it's non-0 value or error message, your kernel doesn't have VXLAN kernel module.
+ $ sudo modprobe vxlan && echo $?
+ # Confirm the output is "0".
+ # If it's non-0 value or error message, your kernel doesn't have VXLAN kernel module.
- $ ip link add type vxlan help
- # Confirm the output is usage of the command and that it's for VXLAN.
- # If it's not, your iproute2 utility doesn't support VXLAN.
+ $ ip link add type vxlan help
+ # Confirm the output is usage of the command and that it's for VXLAN.
+ # If it's not, your iproute2 utility doesn't support VXLAN.
Advanced: Build kernel and iproute2
@@ -62,54 +80,55 @@ Even if your system doesn't support VXLAN, you can compile the kernel
and iproute2 by yourself. The following procedure is an example for
CentOS 6.4.
+
Build kernel
^^^^^^^^^^^^
::
- $ sudo yum groupinstall "Development Tools"
- $ sudo yum install ncurses-devel hmaccalc zlib-devel binutils-devel elfutils-libelf-devel bc
-
- $ KERNEL_VERSION=3.10.4
- # Declare the kernel version you want to build.
-
- $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-${KERNEL_VERSION}.tar.xz
- $ tar xvf linux-${KERNEL_VERSION}.tar.xz
- $ cd linux-${KERNEL_VERSION}
- $ cp /boot/config-`uname -r` .config
- $ make oldconfig
- # You may keep hitting enter and choose the default.
-
- $ make menuconfig
- # Dig into "Device Drivers" -> "Network device support",
- # then select "Virtual eXtensible Local Area Network (VXLAN)" and hit space.
- # Make sure it indicates "<M>" (build as module), then Save and Exit.
-
- # You may also want to check "IPv4 NAT" and its child nodes in "IP: Netfilter Configuration"
- # and "IPv6 NAT" and its child nodes in "IPv6: Netfilter Configuration".
- # In 3.10.4, you can find the options in
- # "Networking support" -> "Networking options"
- # -> "Network packet filtering framework (Netfilter)".
-
- $ make # -j N
- # You may use -j N option to make the build process parallel and faster,
- # generally N = 1 + (cores your machine have).
-
- $ sudo make modules_install
- $ sudo make install
- # You would get an error like "ERROR: modinfo: could not find module XXXX" here.
- # This happens mainly due to config structure changes between kernel versions.
- # You can ignore this error, until you find you need the kernel module.
- # If you feel uneasy, you can go back to make menuconfig,
- # find module XXXX by using '/' key, enable the module, build and install the kernel again.
-
- $ sudo vi /etc/grub.conf
- # Make sure the new kernel isn't set as the default and the timeout is long enough,
- # so you can select the new kernel during boot process.
- # It's not a good idea to set the new kernel as the default until you confirm the kernel works fine.
-
- $ sudo reboot
- # Select the new kernel during the boot process.
+ $ sudo yum groupinstall "Development Tools"
+ $ sudo yum install ncurses-devel hmaccalc zlib-devel binutils-devel elfutils-libelf-devel bc
+
+ $ KERNEL_VERSION=3.10.4
+ # Declare the kernel version you want to build.
+
+ $ wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-${KERNEL_VERSION}.tar.xz
+ $ tar xvf linux-${KERNEL_VERSION}.tar.xz
+ $ cd linux-${KERNEL_VERSION}
+ $ cp /boot/config-`uname -r` .config
+ $ make oldconfig
+ # You may keep hitting enter and choose the default.
+
+ $ make menuconfig
+ # Dig into "Device Drivers" -> "Network device support",
+ # then select "Virtual eXtensible Local Area Network (VXLAN)" and hit space.
+ # Make sure it indicates "<M>" (build as module), then Save and Exit.
+
+ # You may also want to check "IPv4 NAT" and its child nodes in "IP: Netfilter Configuration"
+ # and "IPv6 NAT" and its child nodes in "IPv6: Netfilter Configuration".
+ # In 3.10.4, you can find the options in
+ # "Networking support" -> "Networking options"
+ # -> "Network packet filtering framework (Netfilter)".
+
+ $ make # -j N
+ # You may use -j N option to make the build process parallel and faster,
+ # generally N = 1 + (cores your machine have).
+
+ $ sudo make modules_install
+ $ sudo make install
+ # You would get an error like "ERROR: modinfo: could not find module XXXX" here.
+ # This happens mainly due to config structure changes between kernel versions.
+ # You can ignore this error, until you find you need the kernel module.
+ # If you feel uneasy, you can go back to make menuconfig,
+ # find module XXXX by using '/' key, enable the module, build and install the kernel again.
+
+ $ sudo vi /etc/grub.conf
+ # Make sure the new kernel isn't set as the default and the timeout is long enough,
+ # so you can select the new kernel during boot process.
+ # It's not a good idea to set the new kernel as the default until you confirm the kernel works fine.
+
+ $ sudo reboot
+ # Select the new kernel during the boot process.
Build iproute2
@@ -117,22 +136,23 @@ Build iproute2
::
- $ sudo yum install db4-devel
+ $ sudo yum install db4-devel
- $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git
- $ cd iproute2
- $ git tag
- # Find the version that matches the kernel.
- # If you built kernel 3.10.4 as above, it would be v3.10.0.
+ $ git clone git://git.kernel.org/pub/scm/linux/kernel/git/shemminger/iproute2.git
+ $ cd iproute2
+ $ git tag
+ # Find the version that matches the kernel.
+ # If you built kernel 3.10.4 as above, it would be v3.10.0.
- $ git checkout v3.10.0
- $ ./configure
- $ make # -j N
- $ sudo make install
+ $ git checkout v3.10.0
+ $ ./configure
+ $ make # -j N
+ $ sudo make install
.. note:: Please use rebuild kernel and tools at your own risk.
+
Configure PRODUCT to use VXLAN Plugin
-------------------------------------
@@ -146,6 +166,7 @@ In addition to "KVM Hypervisor Host Installation" in "PRODUCT
Installation Guide", you have to configure the following item on the
host.
+
Create bridge interface with IPv4 address
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -165,6 +186,7 @@ this way.
Let ``cloudbr1`` be the bridge interface for the instances' private
network.
+
Configure in RHEL or CentOS
'''''''''''''''''''''''''''
@@ -172,35 +194,33 @@ When you configured the ``cloudbr1`` interface as below,
::
- $ sudo vi /etc/sysconfig/network-scripts/ifcfg-cloudbr1
-
+ $ sudo vi /etc/sysconfig/network-scripts/ifcfg-cloudbr1
::
- DEVICE=cloudbr1
- TYPE=Bridge
- ONBOOT=yes
- BOOTPROTO=none
- IPV6INIT=no
- IPV6_AUTOCONF=no
- DELAY=5
- STP=yes
-
+ DEVICE=cloudbr1
+ TYPE=Bridge
+ ONBOOT=yes
+ BOOTPROTO=none
+ IPV6INIT=no
+ IPV6_AUTOCONF=no
+ DELAY=5
+ STP=yes
you would change the configuration similar to below.
::
- DEVICE=cloudbr1
- TYPE=Bridge
- ONBOOT=yes
- BOOTPROTO=static
- IPADDR=192.0.2.X
- NETMASK=255.255.255.0
- IPV6INIT=no
- IPV6_AUTOCONF=no
- DELAY=5
- STP=yes
+ DEVICE=cloudbr1
+ TYPE=Bridge
+ ONBOOT=yes
+ BOOTPROTO=static
+ IPADDR=192.0.2.X
+ NETMASK=255.255.255.0
+ IPV6INIT=no
+ IPV6_AUTOCONF=no
+ DELAY=5
+ STP=yes
Configure in Ubuntu
@@ -210,72 +230,71 @@ When you configured ``cloudbr1`` as below,
::
- $ sudo vi /etc/network/interfaces
+ $ sudo vi /etc/network/interfaces
::
- auto lo
- iface lo inet loopback
-
- # The primary network interface
- auto eth0.100
- iface eth0.100 inet static
- address 192.168.42.11
- netmask 255.255.255.240
- gateway 192.168.42.1
- dns-nameservers 8.8.8.8 8.8.4.4
- dns-domain lab.example.org
-
- # Public network
- auto cloudbr0
- iface cloudbr0 inet manual
- bridge_ports eth0.200
- bridge_fd 5
- bridge_stp off
- bridge_maxwait 1
-
- # Private network
- auto cloudbr1
- iface cloudbr1 inet manual
- bridge_ports eth0.300
- bridge_fd 5
- bridge_stp off
- bridge_maxwait 1
-
+ auto lo
+ iface lo inet loopback
+
+ # The primary network interface
+ auto eth0.100
+ iface eth0.100 inet static
+ address 192.168.42.11
+ netmask 255.255.255.240
+ gateway 192.168.42.1
+ dns-nameservers 8.8.8.8 8.8.4.4
+ dns-domain lab.example.org
+
+ # Public network
+ auto cloudbr0
+ iface cloudbr0 inet manual
+ bridge_ports eth0.200
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+ # Private network
+ auto cloudbr1
+ iface cloudbr1 inet manual
+ bridge_ports eth0.300
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
you would change the configuration similar to below.
::
- auto lo
- iface lo inet loopback
-
- # The primary network interface
- auto eth0.100
- iface eth0.100 inet static
- address 192.168.42.11
- netmask 255.255.255.240
- gateway 192.168.42.1
- dns-nameservers 8.8.8.8 8.8.4.4
- dns-domain lab.example.org
-
- # Public network
- auto cloudbr0
- iface cloudbr0 inet manual
- bridge_ports eth0.200
- bridge_fd 5
- bridge_stp off
- bridge_maxwait 1
-
- # Private network
- auto cloudbr1
- iface cloudbr1 inet static
- addres 192.0.2.X
- netmask 255.255.255.0
- bridge_ports eth0.300
- bridge_fd 5
- bridge_stp off
- bridge_maxwait 1
+ auto lo
+ iface lo inet loopback
+
+ # The primary network interface
+ auto eth0.100
+ iface eth0.100 inet static
+ address 192.168.42.11
+ netmask 255.255.255.240
+ gateway 192.168.42.1
+ dns-nameservers 8.8.8.8 8.8.4.4
+ dns-domain lab.example.org
+
+ # Public network
+ auto cloudbr0
+ iface cloudbr0 inet manual
+ bridge_ports eth0.200
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
+
+ # Private network
+ auto cloudbr1
+ iface cloudbr1 inet static
+ addres 192.0.2.X
+ netmask 255.255.255.0
+ bridge_ports eth0.300
+ bridge_fd 5
+ bridge_stp off
+ bridge_maxwait 1
Configure iptables to pass XVLAN packets
@@ -284,6 +303,7 @@ Configure iptables to pass XVLAN packets
Since VXLAN uses UDP packet to forward encapsulated the L2 frames,
UDP/8472 port must be opened.
+
Configure in RHEL or CentOS
'''''''''''''''''''''''''''
@@ -292,7 +312,7 @@ extra ports by executing the following iptable commands:
::
- $ sudo iptables -I INPUT -p udp -m udp --dport 8472 -j ACCEPT
+ $ sudo iptables -I INPUT -p udp -m udp --dport 8472 -j ACCEPT
These iptable settings are not persistent accross reboots, we have to
@@ -300,7 +320,7 @@ save them first.
::
- $ sudo iptables-save > /etc/sysconfig/iptables
+ $ sudo iptables-save > /etc/sysconfig/iptables
With this configuration you should be able to restart the network,
@@ -308,11 +328,14 @@ although a reboot is recommended to see if everything works properly.
::
- $ sudo service network restart
- $ sudo reboot
+ $ sudo service network restart
+ $ sudo reboot
-.. warning:: Make sure you have an alternative way like IPMI or ILO to reach the machine in case you made a configuration error and the network stops functioning!
+.. warning::
+ Make sure you have an alternative way like IPMI or ILO to reach the machine
+ in case you made a configuration error and the network stops functioning!
+
Configure in Ubuntu
'''''''''''''''''''
@@ -324,21 +347,24 @@ To open the required ports, execute the following commands:
::
- $ sudo ufw allow proto udp from any to any port 8472
+ $ sudo ufw allow proto udp from any to any port 8472
-
-.. note:: By default UFW is not enabled on Ubuntu. Executing these commands with the firewall disabled does not enable the firewall.
+.. note::
+ By default UFW is not enabled on Ubuntu. Executing these commands with the
+ firewall disabled does not enable the firewall.
With this configuration you should be able to restart the network,
although a reboot is recommended to see if everything works properly.
::
- $ sudo service networking restart
- $ sudo reboot
+ $ sudo service networking restart
+ $ sudo reboot
+.. warning::
+ Make sure you have an alternative way like IPMI or ILO to reach the machine
+ in case you made a configuration error and the network stops functioning!
-.. warning:: Make sure you have an alternative way like IPMI or ILO to reach the machine in case you made a configuration error and the network stops functioning!
Setup zone using VXLAN
~~~~~~~~~~~~~~~~~~~~~~
@@ -349,6 +375,7 @@ is not required to add a network element nor to reconfigure the network
offering. The only thing you have to do is configure the physical
network to use VXLAN as the isolation method for Guest Network.
+
Configure the physical network
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -363,6 +390,7 @@ Guest Network traffic label should be the name of the physical interface
or the name of the bridge interface and the bridge interface and they
should have an IPv4 address. See ? for details.
+
Configure the guest traffic
^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -371,6 +399,6 @@ Configure the guest traffic
Specify a range of VNIs you would like to use for carrying guest network
traffic.
-.. warning:: VNI must be unique per zone and no duplicate VNIs can exist in the zone. Exercise care when designing your VNI allocation policy.
-
-
+.. warning::
+ VNI must be unique per zone and no duplicate VNIs can exist in the zone.
+ Exercise care when designing your VNI allocation policy.