Introduction

Purpose

The objective of this feature is to bring EC2 support into mainstream CloudStack by migrating CloudBridge code into the CloudStack database. Improving fidelity with the EC2 API is also a goal.

Scope

Scope of this document is to provide a functional specification for the EC2 integration and fidelity work planned for the Bonita release of CloudStack.

References

• CloudBridge docs: http://docs.cloudstack.org/CloudBridge_Documentation
• EC2 API documentation:http://docs.amazonwebservices.com/AWSEC2/2010-11-15/APIReference/
• EC2 – CloudStack API compatibility analysis: http://confluence.cloudstack.org/display/dev/EC2+API+Fidelity+Work

Document History

Feature Specifications

Feature Objectives

• EC2 support into CloudStack:

      This involves integration of the CloudBridge codebase to the mainline of CloudStack and expose the EC2 support as part of CloudStack. Once integrated under CloudStack, we will rename the CloudBridge project to 'awsapi'

• *# CloudBridge runs as a separate deployment in a separate server. Aim is to deploy CloudStack and CloudBridge code in the same tomcat server as two different webapps, listening on the same port.
  1. The build and packaging scripts need to take care of distributing CloudBridge as part of CloudStack.
  2. Also the EC2 API in CloudBridge should run along with CloudStack 3.0.x release. Currently the standalone CloudBridge supports 2.2.x version of CloudStack, we need to provide any fixes needed to support CloudStack 3.0.x

• EC2 API fidelity:

      Currently CloudBridge does not support all the EC2 APIs. Goal is to achieve maximum fidelity to EC2 API by bridging the API gap between EC2 and CloudStack as much as possible.

      For Bonita release following are the API gaps that need to be closed:

• *# EC2 AllocateAddress – Provide a default Zone:

CloudStack assigns an IP address from a Zone and CloudBridge picks the first available Zone to do so.However AWS does not assign an IP address from a particular AvailabilityZone.
To bridge this gap, a new CloudStack API needs to be implemented to enable a user to mark a zone as ‘default’ for the account. CloudBridge can then use this default Zone to allocate an IP address from.

• 1. EC2 AssociateAddress – fix IP address reassignment :
     AWS associates an elastic IP address with an instance. If the IP address is currently assigned to another instance, the IP address is assigned to the new instance. In such cases CloudStack errors out if IP is already assigned.
     Solution is to fix CloudStack to allow reassigning the IP address in case it has been already assigned to some other VM.
  2. EC2 DescribeImageAttribute – support launchPermission: 
     Need to implement the support for ‘launchPermission’ image attribute. CloudStack listTemplatePermissions API can be used for this purpose.
  3. EC2 RunInstances – default SecurityGroup: 

CloudStack needs to be fixed to not place the instance in default security group if a groupId is provided.

Limitations

• Current CloudBridge is developed against EC2 API dated Nov-15-2010. For Bonita, we plan to continue supporting the 2010 EC2 API. For future releases we plan to update the support to latest EC2 APIs.
• For Bonita, only the above stated API gaps are planned to be bridged.
• CloudBridge works with version 1.3.6230 of the EC2 Tools
• The integrated version of CloudBridge with CloudStack 3.0.x will support only the Basic Zone setup.
• Also to support features like EIP in a basic zone, netscalar setup should be available. CloudBridge will search for the networkOffering with netscalar Provider while deploying a VM. If no such offering is available, the default Guest networkOffering will be picked and EIP will not be supported in this case.

Logging and Debugging

• Even though we will integrate CloudBridge to CloudStack, for logs related to CloudBridge, check the file awsapi.log
• Developers can attach Eclipse to the same port 8787 as CloudStack, for debugging the code.

Configuration Characteristics

• The build and deployment scripts will include CloudBridge and deploy in tomcat server along with CloudStack
• Admin will be able to enable/disable the support for EC2 API through a global configuration variable named 'enable.ec2.api'. The default value will be false.
• After enabling, Admin will have to create service offerings in CloudStack with names that match the Amazon service offering names. If these offerings are not created, deploying instances through EC2 API will not work.

Deployment requirements

EC2 Support through CloudStack will be available through fresh installations of CloudStack only. EC2 API will not be available through upgrade of previous versions.

Use cases

Case 1: Admin user - Install

• An admin downloads the rpm's and runs install.sh
• This should deploy CloudBridge webapp along with CloudStack into Tomcat
• However by default, EC2 API will remain disabled when management server is started

Case 2: Admin user - Enable EC2 API

• Admin can change the global configuration parameter 'enable.ec2.api' through CloudStack UI and set the value to 'true' to enable EC2 API
• Admin creates service offerings in CloudStack having names that match the Amazon service offering names.
• Restart Management Server
• Admin can add more service offerings anytime later through CloudStack UI.

Case 3: EC2 user setup

• Obtain the following from your CloudStack cloud administrator:
  1.         The CloudStack server's publicly available DNS name or IP address
  2.         Your account's API key and Secret key
• Generate a private key and a self-signed X.509 certificate. Substitute your own desired storage location for /path/to/… below.
  $ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /path/to/private_key.pem -out /path/to/cert.pem
• Register the mapping from the X.509 certificate to your accounts API keys with CloudStack. Download the script to do this from <location TBD>
  $ cloudstack-aws-api-register --apikey=<User’s Cloudstack API key> --secretkey=<User’s CloudStack Secret key> --cert=</path/to/cert.pem> --url=http://<cloud-stack-server>:7080/awsapi
• Setup the necessary environment variables for the EC2 tools.
  $ export EC2_ACCESS_KEY=<CloudStack API key>
  $ export EC2_SECRET_KEY=<CloudStack Secret key>
  $ export EC2_CERT=/path/to/cert.pem
  $ export EC2_PRIVATE_KEY=/path/to/private_key.pem
  $ export EC2_URL=http://cloud-stack-hostname:8080/awsapi
  % export EC2_HOME=/path/to/EC2_installation_directory

Architecture and Design description

Currently an EC2 Soap or REST request flows to CloudStack as shown below:

• CloudBridge and CloudStack run in separate tomcat servers.
• EC2 tools call the CloudBridge webapp which acts as the translation layer between EC2 API and CloudStack API.
• CloudBridge routes the call to CloudStack API layer and translates the response to EC2 on way back.
  

With Bonita release plan is to integrate the two codebases to run in single server under CloudStack but maintaining this call flow.

Thus even after integration, plan is to have CloudBridge call CloudStack API layer as before:

Reasons to go with this design were:

• Alternatives to this design were doing a full integration of CloudBridge to CloudStack by placing calls to Service layer from CloudBridge directly and have a component parallel to the CloudStack API layer.
• CloudStack Service layer is not yet completely independent of the API layer. API layer objects are passed in to the Service layer as input.
• The Service layer refactoring will be happening in parallel, after which the above method of integration could be undertaken.
• Until then, having CloudBridge call the CloudStack API layer is a simpler and faster approach of integration.

Integration of CloudBridge code

• We will integrate the CloudBridge code from github.com with 3.0.x branch of CloudStack.
• CloudBridge will be added as a separate project under cloudstack-oss.
• All the setup files including db schema and user setup scripts will be contained in ‘cloudbridge-setup’ directory under cloudstack-oss
• All the thirdparty libraries that CloudBridge requires will be kept separate from CloudStack thirdparty libraries under cloudstack-oss/deps/cloudbridge-lib

Following is a screenshot of the proposed code base integration:

Tomcat Deployment changes\* \[This has been changed, please refer section 'Changes to awsapi port' below\]

Following design is no longer supported. This has been changed and now awsapi will be listening on URL: http://<server>:7080/awsapi/
Under tomcat cloudbridge will be still deployed as a separate webapp. It can be accessed on the same port as cloudstack but with different URL: http://<server>:8080/awsapi/

Avoiding Loopback requests in Tomcat:

• After integration we plan to deploy CloudBridge and CloudStack as two separate webapps in the same tomcat server.
• Thus all EC2 requests will be routed through CloudBridge webapp listening on port 8080 which will internally call the CloudStack webapp again listening on 8080 and using the same tomcat threadpool.
• So we need to make sure that N incoming EC2 requests don’t establish N loopback requests to the CloudStack API, essentially using up 2*N threads from the same pool.
• This can lead to a deadlock where the EC2 requests might be blocked waiting on the same thread pool.
• To avoid this we plan to define a new localhost-only http connector listening on some other port, say 7080 and using a separate threadpool.
• CloudBridge will place the call to CloudStack API on this separate port. Thus CloudStack will listen on 8080 for external requests and also on 7080 for localhost requests.
  

  * Changes to awsapi port:

After integration in to CloudStack in 3.0.3, EC2 API listens on the same port 8080 as CloudStack API, under a different context. This was intended to make it appear that CloudStack is able to accept EC2/S3 requests as wel and also to avoid the loopback issues as mentioned above.

Problem: This design of using the 7080 localhost only port, is breaking any other applications who proxy CloudStack requests coming on 8080. Since CS API requests made by EC2 go on port 7080, these applications cannot proxy the EC2 requests.

Solution:

We will have to revert back this design and make awsapi listen on a different port than the CloudStack port. We will make awsapi listen on port 7080 by default.

Thus EC2/S3 will listen on http://<server_ip_of_CloudStack>:7080/awsapi and will call CloudStack on 8080.

No loopback issues will arise since awsapi EC2/S3 API and Cloudstack API are now using different ports on tomcat.

New deployment looks like this:

API Changes

MarkDefaultZoneForAccountCmd

This will be a new API added to CloudStack to enable a user to mark a particular zone as ‘default’ to be used for any operations for the account. This will be useful for users of EC2 API in use cases like AllocateAddress.

Parameters:

• accountName: Name of the user account
• domainid: Domain the account belongs to
• zoneid*:* Zone Id

DB Changes

EC2 support will be available only for new installs. So there is no need to include any DB changes in upgrade scripts.

CloudBridge DB

• As part of Bonita, no major DB integration is planned
• CloudBridge has its own database that we intend to keep it separate after the integration
• The DB schema files will rest under cloudstack-oss/awsapi-setup/db/mysql
• The ant target to install the database will be ‘deploy-awsapi-db’
• DB user and password for CloudStack and CloudBridge will be same

CloudStack  DB

• `cloud`.`account` table

 A new Column ‘default_zone’ will be added to this table to store the zoneid of the zone to be marked default for the account.

• `cloud`.`configuration`

We need to add a new Configuration parameter called 'enable.ec2.api' to enable EC2 API through global settings. Default value of this parameter should be 'false'.