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:28 UTC
[3/4] fixed the formatting in all the files and added the license to
each file: This closes #4
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
-----------