diff --git a/source/conceptsandterminology/concepts.rst b/source/conceptsandterminology/concepts.rst index f621ffaa6d..19d65555c8 100644 --- a/source/conceptsandterminology/concepts.rst +++ b/source/conceptsandterminology/concepts.rst @@ -91,13 +91,6 @@ 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. - - High Availability ~~~~~~~~~~~~~~~~~ @@ -145,8 +138,7 @@ The management server: - Provides the web interface for both the administrator and end user. -- Provides the API interfaces for both the CloudStack API as well as the EC2 - interface. +- Provides the CloudStack API. - Manages the assignment of guest Instances to a specific compute resource diff --git a/source/developersguide/developer_guide.rst b/source/developersguide/developer_guide.rst index 9309c29c0f..73b508a78e 100644 --- a/source/developersguide/developer_guide.rst +++ b/source/developersguide/developer_guide.rst @@ -272,12 +272,8 @@ in XML or JSON. It is used to implement the default web UI. This API is not a standard like `OGF OCCI `__ or `DMTF CIMI `__ but is easy to learn. -Mapping exists between the AWS API and the CloudStack API as will be -seen in the next section. Recently a Google Compute Engine interface was -also developed that maps the GCE REST API to the CloudStack API -described here. The API -`docs `__ are a good start to -learn the extent of the API. Multiple clients exist on +The API `docs `__ are a good start +to learn the extent of the API. Multiple clients exist on `GitHub `__ to use this API, you should be able to find one in your favorite language. The reference documentation for the API and changes that might diff --git a/source/installguide/optional_installation.rst b/source/installguide/optional_installation.rst index d9dee1b85f..51dc3b6a23 100644 --- a/source/installguide/optional_installation.rst +++ b/source/installguide/optional_installation.rst @@ -312,539 +312,3 @@ administrator. In the event of a database failure you should: # service cloudstack-management start - -Amazon Web Services Interface ------------------------------ - -Amazon Web Services Compatible Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -CloudStack can translate Amazon Web Services (AWS) API calls to native -CloudStack API calls so that Users can continue using existing -AWS-compatible tools. This translation service runs as a separate web -application in the same tomcat server as the management server of -CloudStack, listening on a different port. The Amazon Web Services (AWS) -compatible interface provides the EC2 SOAP and Query APIs as well as the -S3 REST API. - -.. note:: - This service was previously enabled by separate software called CloudBridge. - It is now fully integrated with the CloudStack management server. - -.. warning:: - The compatible interface for the EC2 Query API and the S3 API are Work In - Progress. The S3 compatible API offers a way to store data on the - management server file system, it is not an implementation of the S3 - backend. - -Limitations - -- Supported only in zones that use basic networking. - -- Available in fresh installations of CloudStack. Not available through - upgrade of previous versions. - -- Features such as Elastic IP (EIP) and Elastic Load Balancing (ELB) - are only available in an infrastructure with a Citrix NetScaler - device. Users accessing a Zone with a NetScaler device will need to - use a NetScaler-enabled Network offering (DefaultSharedNetscalerEIP - and ELBNetworkOffering). - - -Supported API Version -~~~~~~~~~~~~~~~~~~~~~ - -- The EC2 interface complies with Amazon's WDSL version dated November - 15, 2010, available at `http://ec2.amazonaws.com/doc/2010-11-15/ - `_. - -- The interface is compatible with the EC2 command-line tools *EC2 - tools v. 1.3.6230*, which can be downloaded at - `http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip `_. - -.. note:: - Work is underway to support a more recent version of the EC2 API - - -Enabling the EC2 and S3 Compatible Interface -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The software that provides AWS API compatibility is installed along with -CloudStack. You must enable the services and perform some setup steps -prior to using it. - -#. Set the global configuration parameters for each service to true. See - `*Setting Global Configuration Parameters* - `_. - -#. Create a set of CloudStack service offerings with names that match - the Amazon service offerings. You can do this through the CloudStack - UI as described in the Administration Guide. - - .. warning:: - Be sure you have included the Amazon default service offering, m1.small. - As well as any EC2 instance types that you will use. - -#. If you did not already do so when you set the configuration parameter - in step 1, restart the Management Server. - - .. parsed-literal:: - - # service cloudstack-management restart - -The following sections provides details to perform these steps - - -Enabling the Services -^^^^^^^^^^^^^^^^^^^^^ - -To enable the EC2 and S3 compatible services you need to set the -configuration variables *enable.ec2.api* and *enable.s3.api* to true. -You do not have to enable both at the same time. Enable the ones you -need. This can be done via the CloudStack GUI by going in *Global -Settings* or via the API. - -The Snapshot below shows you how to use the GUI to enable these services - -|Use the GUI to set the configuration variable to true| - -Using the CloudStack API, the easiest is to use the so-called -integration port on which you can make unauthenticated calls. In Global -Settings set the port to 8096 and subsequently call the -*updateConfiguration* method. The following urls shows you how: - -.. parsed-literal:: - - http://localhost:8096/client/api?command=updateConfiguration&name=enable.ec2.api&value=true - http://localhost:8096/client/api?command=updateConfiguration&name=enable.ec2.api&value=true - -Once you have enabled the services, restart the server. - - -Creating EC2 Compatible Service Offerings -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -You will also need to define compute service offerings with names -compatible with the `Amazon EC2 instance -types `_ API names (e.g -m1.small,m1.large). This can be done via the CloudStack GUI. Go under -*Service Offerings* select *Compute offering* and either create a new -compute offering or modify an existing one, ensuring that the name -matches an EC2 instance type API name. The Snapshot below shows you how: - -|Use the GUI to set the name of a compute service offering to an EC2 -instance type API name.| - - -Modifying the AWS API Port -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. note:: - (Optional) The AWS API listens for requests on port 7080. If you prefer AWS - API to listen on another port, you can change it as follows: - - #. Edit the files ``/etc/cloudstack/management/server.xml``, - ``/etc/cloudstack/management/server-nonssl.xml``, and - ``/etc/cloudstack/management/server-ssl.xml``. - - #. In each file, find the tag . Under this tag, locate `_. - -#. Set up the EC2 environment variables. This can be done every time you - use the service or you can set them up in the proper shell profile. - Replace the endpoint (i.e EC2\_URL) with the proper address of your - CloudStack management server and port. In a bash shell do the - following. - -.. parsed-literal:: - - $ export EC2_CERT=/path/to/cert.pem - $ export EC2_PRIVATE_KEY=/path/to/private_key.pem - $ export EC2_URL=http://localhost:7080/awsapi - $ export EC2_HOME=/path/to/EC2_tools_directory - - -Using Timeouts to Ensure AWS API Command Completion -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The Amazon EC2 command-line tools have a default connection timeout. -When used with CloudStack, a longer timeout might be needed for some -commands. If you find that commands are not completing due to timeouts, -you can specify a custom timeouts. You can add the following optional -command-line parameters to any CloudStack-supported EC2 command: - -Specifies a connection timeout (in seconds) - -.. parsed-literal:: - - --connection-timeout TIMEOUT - -Specifies a request timeout (in seconds) - -.. parsed-literal:: - - --request-timeout TIMEOUT - -Example: - -.. parsed-literal:: - - ec2-run-instances 2 –z us-test1 –n 1-3 --connection-timeout 120 --request-timeout 120 - -.. note:: - The timeouts optional arguments are not specific to CloudStack. - - -Supported AWS API Calls -~~~~~~~~~~~~~~~~~~~~~~~ - -The following Amazon EC2 commands are supported by CloudStack when the -AWS API compatible interface is enabled. For a few commands, there are -differences between the CloudStack and Amazon EC2 versions, and these -differences are noted. The underlying SOAP call for each command is also -given, for those who have built tools using those calls. - -Table 1. Elastic IP API mapping - -.. cssclass:: table-striped table-bordered table-hover - -+---------------------------+-----------------------+-------------------------+ -| EC2 command | SOAP call | CloudStack API call | -+===========================+=======================+=========================+ -| ec2-allocate-address | AllocateAddress | associateIpAddress | -+---------------------------+-----------------------+-------------------------+ -| ec2-associate-address | AssociateAddress | enableStaticNat | -+---------------------------+-----------------------+-------------------------+ -| ec2-describe-addresses | DescribeAddresses | listPublicIpAddresses | -+---------------------------+-----------------------+-------------------------+ -| ec2-diassociate-address | DisassociateAddress | disableStaticNat | -+---------------------------+-----------------------+-------------------------+ -| ec2-release-address | ReleaseAddress | disassociateIpAddress | -+---------------------------+-----------------------+-------------------------+ - -| - -Table 2. Availability Zone API mapping - -.. cssclass:: table-striped table-bordered table-hover - -+-----------------------------------+-----------------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+===================================+=============================+=======================+ -| ec2-describe-availability-zones | DescribeAvailabilityZones | listZones | -+-----------------------------------+-----------------------------+-----------------------+ - -| - -Table 3. Images API mapping - -.. cssclass:: table-striped table-bordered table-hover - -+-----------------------+-------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+=======================+===================+=======================+ -| ec2-create-image | CreateImage | createTemplate | -+-----------------------+-------------------+-----------------------+ -| ec2-deregister | DeregisterImage | DeleteTemplate | -+-----------------------+-------------------+-----------------------+ -| ec2-describe-images | DescribeImages | listTemplates | -+-----------------------+-------------------+-----------------------+ -| ec2-register | RegisterImage | registerTemplate | -+-----------------------+-------------------+-----------------------+ - -| - -Table 4. Image Attributes API mapping - -.. cssclass:: table-striped table-bordered table-hover - -+--------------------------------+--------------------------+-----------------------------+ -| EC2 command | SOAP call | CloudStack API call | -+================================+==========================+=============================+ -| ec2-describe-image-attribute | DescribeImageAttribute | listTemplatePermissions | -+--------------------------------+--------------------------+-----------------------------+ -| ec2-modify-image-attribute | ModifyImageAttribute | updateTemplatePermissions | -+--------------------------------+--------------------------+-----------------------------+ -| ec2-reset-image-attribute | ResetImageAttribute | updateTemplatePermissions | -+--------------------------------+--------------------------+-----------------------------+ - -| - -Table 5. Instances API mapping - -.. cssclass:: table-striped table-bordered table-hover - -+---------------------------+----------------------+-------------------------+ -| EC2 command | SOAP call | CloudStack API call | -+===========================+======================+=========================+ -| ec2-describe-instances | DescribeInstances | listVirtualMachines | -+---------------------------+----------------------+-------------------------+ -| ec2-run-instances | RunInstances | deployVirtualMachine | -+---------------------------+----------------------+-------------------------+ -| ec2-reboot-instances | RebootInstances | rebootVirtualMachine | -+---------------------------+----------------------+-------------------------+ -| ec2-start-instances | StartInstances | startVirtualMachine | -+---------------------------+----------------------+-------------------------+ -| ec2-stop-instances | StopInstances | stopVirtualMachine | -+---------------------------+----------------------+-------------------------+ -| ec2-terminate-instances | TerminateInstances | destroyVirtualMachine | -+---------------------------+----------------------+-------------------------+ - -| - -Table 6. Instance Attributes Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+-----------------------------------+-----------------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+===================================+=============================+=======================+ -| ec2-describe-instance-attribute | DescribeInstanceAttribute | listVirtualMachines | -+-----------------------------------+-----------------------------+-----------------------+ - -| - -Table 7. Keys Pairs Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+-------------------------+--------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+=========================+====================+=======================+ -| ec2-add-keypair | CreateKeyPair | createSSHKeyPair | -+-------------------------+--------------------+-----------------------+ -| ec2-delete-keypair | DeleteKeyPair | deleteSSHKeyPair | -+-------------------------+--------------------+-----------------------+ -| ec2-describe-keypairs | DescribeKeyPairs | listSSHKeyPairs | -+-------------------------+--------------------+-----------------------+ -| ec2-import-keypair | ImportKeyPair | registerSSHKeyPair | -+-------------------------+--------------------+-----------------------+ - -| - -Table 8. Passwords API Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+--------------------+-------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+====================+===================+=======================+ -| ec2-get-password | GetPasswordData | getVMPassword | -+--------------------+-------------------+-----------------------+ - -| - -Table 9. Security Groups API Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+----------------------+---------------------------------+---------------------------------+ -| EC2 command | SOAP call | CloudStack API call | -+======================+=================================+=================================+ -| ec2-authorize | AuthorizeSecurityGroupIngress | authorizeSecurityGroupIngress | -+----------------------+---------------------------------+---------------------------------+ -| ec2-add-group | CreateSecurityGroup | createSecurityGroup | -+----------------------+---------------------------------+---------------------------------+ -| ec2-delete-group | DeleteSecurityGroup | deleteSecurityGroup | -+----------------------+---------------------------------+---------------------------------+ -| ec2-describe-group | DescribeSecurityGroups | listSecurityGroups | -+----------------------+---------------------------------+---------------------------------+ -| ec2-revoke | RevokeSecurityGroupIngress | revokeSecurityGroupIngress | -+----------------------+---------------------------------+---------------------------------+ - -| - -Table 10. Snapshots API Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+--------------------------+---------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+==========================+=====================+=======================+ -| ec2-create-snapshot | CreateSnapshot | createSnapshot | -+--------------------------+---------------------+-----------------------+ -| ec2-delete-snapshot | DeleteSnapshot | deleteSnapshot | -+--------------------------+---------------------+-----------------------+ -| ec2-describe-snapshots | DescribeSnapshots | listSnapshots | -+--------------------------+---------------------+-----------------------+ - -| - -Table 11. Volumes API Mapping - -.. cssclass:: table-striped table-bordered table-hover - -+-----------------------+------------------+-----------------------+ -| EC2 command | SOAP call | CloudStack API call | -+=======================+==================+=======================+ -| ec2-attach-volume | AttachVolume | attachVolume | -+-----------------------+------------------+-----------------------+ -| ec2-create-volume | CreateVolume | createVolume | -+-----------------------+------------------+-----------------------+ -| ec2-delete-volume | DeleteVolume | deleteVolume | -+-----------------------+------------------+-----------------------+ -| ec2-describe-volume | DescribeVolume | listVolumes | -+-----------------------+------------------+-----------------------+ -| ec2-detach-volume | DetachVolume | detachVolume | -+-----------------------+------------------+-----------------------+ - -| - - -Examples -~~~~~~~~ - -There are many tools available to interface with a AWS compatible API. -In this section we provide a few examples that users of CloudStack can -build upon. - - -Boto Examples -^^^^^^^^^^^^^^ - -Boto is one of them. It is a Python package available at -https://github.com/boto/boto. In this section we provide two examples of -Python scripts that use Boto and have been tested with the CloudStack -AWS API Interface. - -First is an EC2 example. Replace the Access and Secret Keys with your -own and update the endpoint. - -Example 1. An EC2 Boto example - -.. sourcecode:: python - - #!/usr/bin/env python - - import sys - import os - import boto - import boto.ec2 - - region = boto.ec2.regioninfo.RegionInfo(name="ROOT",endpoint="localhost") - apikey='GwNnpUPrO6KgIdZu01z_ZhhZnKjtSdRwuYd4DvpzvFpyxGMvrzno2q05MB0ViBoFYtdqKd' - secretkey='t4eXLEYWw7chBhDlaKf38adCMSHx_wlds6JfSx3z9fSpSOm0AbP9Moj0oGIzy2LSC8iw' - - def main(): - '''Establish connection to EC2 cloud''' - conn = boto.connect_ec2(aws_access_key_id=apikey, - aws_secret_access_key=secretkey, - is_secure=False, - region=region, - port=7080, - path="/awsapi", - api_version="2010-11-15") - - '''Get list of images that I own''' - images = conn.get_all_images() - print images - myimage = images[0] - '''Pick an instance type''' - vm_type='m1.small' - reservation = myimage.run(instance_type=vm_type,security_groups=['default']) - - if __name__ == '__main__': - main() - -| - -Second is an S3 example. The S3 interface in CloudStack is obsolete. If you need an S3 interface you should look at systems like RiakCS, Ceph or GlusterFS. This example is here for completeness and can be adapted to other S3 endpoint. - -Example 2. An S3 Boto Example - -.. sourcecode:: python - - #!/usr/bin/env python - - import sys - import os - from boto.s3.key import Key - from boto.s3.connection import S3Connection - from boto.s3.connection import OrdinaryCallingFormat - - apikey='ChOw-pwdcCFy6fpeyv6kUaR0NnhzmG3tE7HLN2z3OB_s-ogF5HjZtN4rnzKnq2UjtnHeg_yLA5gOw' - secretkey='IMY8R7CJQiSGFk4cHwfXXN3DUFXz07cCiU80eM3MCmfLs7kusgyOfm0g9qzXRXhoAPCH-IRxXc3w' - - cf=OrdinaryCallingFormat() - - def main(): - '''Establish connection to S3 service''' - conn = S3Connection(aws_access_key_id=apikey,aws_secret_access_key=secretkey, \ - is_secure=False, \ - host='localhost', \ - port=7080, \ - calling_format=cf, \ - path="/awsapi/rest/AmazonS3") - - try: - bucket=conn.create_bucket('cloudstack') - k = Key(bucket) - k.key = 'test' - try: - k.set_contents_from_filename('/Users/runseb/Desktop/s3cs.py') - except: - print 'could not write file' - pass - except: - bucket = conn.get_bucket('cloudstack') - k = Key(bucket) - k.key = 'test' - try: - k.get_contents_to_filename('/Users/runseb/Desktop/foobar') - except: - print 'Could not get file' - pass - - try: - bucket1=conn.create_bucket('teststring') - k=Key(bucket1) - k.key('foobar') - k.set_contents_from_string('This is my silly test') - except: - bucket1=conn.get_bucket('teststring') - k = Key(bucket1) - k.key='foobar' - k.get_contents_as_string() - - if __name__ == '__main__': - main() - - -.. |Use the GUI to set the configuration variable to true| image:: /_static/images/ec2-s3-configuration.png -.. |Use the GUI to set the name of a compute service offering to an EC2 instance type API name.| image:: /_static/images/compute-service-offerings.png