Bug Reference & Branch

CLOUDSTACK-....

template-upload branch off master

Introduction

Cloudstack accepts only urls to add a template/volume. If the user has a downloaded template/volume available, he has to host it either on dropbox etc. or run apache server so as to get downloadable url. 

This feature enables the user to directly upload the template/volume to cloudstack and eliminates the dependency on an external http server.

use cases

1. A user, who wants to upload a template and launch a vm with it on cludstack
2. A user, who want to upload a volume and attach it to a vm on cloudstack

Design

1. Management Server generates a unique pre-shared key (PSK) on install and shares it with the SSVM agent. Nobody else has access to this key of course.
2. New API request "getUploadParams" encoded the usual CloudStack API way using api keys. Request parameters include format, hypervisor, md5 sum
3. Management Server response to (b) returns post url to upload the file along with signature generated using PSK and a params json which is to be sent while uploading the file. 
4. API user makes a POST request over HTTPS to the URL obtained in (c)
5. The Apache web server on the SSVM matches the url, decrypts and passes on to the SSVM java agent as plain HTTP. The SSVM agent checks the signature against the params using the key PSK1. Once the params are verified, it writes to the NFS storage to the location encoded in the URL. 
6. Once the upload completes, the MD5 checksum is compared (if available from step c). 

API changes

A new API getUploadParams which takes all the params as the registertemplate/uploadvolume except for URL and  which returns all the required params plus a post URL to be used to uploadVolume/registerTemplate

• Request 
  • type: volume or template : required
  • params while uploading a volume
    • format: the format for the volume. Possible values include QCOW2, OVA, and VHD : required
    • name: the name of the volume : required
    • zoneid: the ID of the zone the volume is to be hosted on : required
    • account: an optional accountName. Must be used with domainId.
    • checksum: the MD5 checksum value of this volume
    • domainid: an optional domainId. If the account parameter is used, domainId must also be used.
    • imagestoreuuid: Image store uuid
    • projectid: Upload volume for the project
  • params while uploading a tempalte
    • displaytext: the display text of the template. This is usually used for display purposes: required
    • format: the format for the template. Possible values include QCOW2, RAW, and VHD : required
    • hypervisor: the target hypervisor for the template : required
    • name: the name of the template : required
    • ostypeid: the ID of the OS Type that best represents the OS of this template : required
    • zoneid: the ID of the zone the template is to be hosted on : required
    • account: an optional accountName. Must be used with domainId.
    • bits: 32 or 64 bits support. 64 by default
    • checksum: the MD5 checksum value of this template
    • details: Template details in key/value pairs.
    • domainid: an optional domainId. If the account parameter is used, domainId must also be used.
    • isdynamicallyscalable: true if template contains XS/VMWare tools inorder to support dynamic scaling of VM cpu/memory
    • isextractable: true if the template or its derivatives are extractable; default is false
    • isfeatured: true if this template is a featured template, false otherwise
    • ispublic: true if the template is available to all accounts; default is true
    • isrouting: true if the template type is routing i.e., if template is used to deploy router
    • passwordenabled: true if the template supports the password reset feature; default is false
    • projectid: Register template for the project
    • requireshvm: true if this template requires HVM
    • sshkeyenabled: true if the template supports the sshkey upload feature; default is false
    • templatetag: the tag for this template.

• Response
  • postURL: post url to upload the file to. Ex: "https://ssvmpublicip/upload/key" (key in the postURL would be generated using PSK initially shared between agent and Management Server.)
  • params: params to be sent in the post request Ex: params:{"store":{"com.cloud.agent.api.to.NfsTO":"nfs://10.147.28.7/export/home/rajani/lxc/secondary"}, "hvm":false,"description":"lxc1","maxDownloadSizeInBytes":53687091200,"id":207,"resourceType":"TEMPLATE","installPath":"template/tmpl/2/207", "format":"TAR","accountId":2,"name":"207-2-09c78adc-065f-3dc8-9621-9e7a036d7dc9"}

POST url to post the data on to SSVM. This post url is returned from the getUploadParams api call Ex: https://ssvmpublicip/upload/key 

• Request: (this is a POST request)
  • params: json string of params returned from previous getUploadParams api call file: file to upload
  • file: the location of the template/volume to be posted a multipart/form-data
• Response: 
  • '200 OK' on successful upload
  • '401 Authorization error' incase the signature key validation or any other validation failed
  • '500 internal server' incase the file upload fails

At any point while this post is active, the api user should be able to call the listtemplates/listvolumes api to get the upload status of it

Sequence Diagram

1. failure at any point during the form upload to ssvm apache would return error to the user and DOWNLOAD_ERROR when the management server pings for download status.
2. polling starts after the success of getUploadParams
3. current polling interval is 10000 ms 
4. currently it polls thrice to check the status. We may need to increase this. (is the current value 5 or 3?)

Agent Commands

1. DownloadProgressCommand will be used the check the download progress (from Management server to Agent)
2. DownloadCommand will be used to start the download(SSVM Apache to SSVM Agent)

State Diagram

Template/Volume states

States:

NOT_DOWNLOADED: getUploadParams API was successful and the template is registered. But, upload hasnt started yet

DOWNLOAD_IN_PROGRESS: User has initiated the POST request SSVM Apache and the validation/download is in progress

DOWNLOADED: SSVM Agent successfully Downloaded the template to secondary storage

DOWNLOAD_ERROR: Any Failure in between user initiating a post request and template being downloaded

ABANDONED: the post request isnt called in the stipulated time (check sequence diagram point 4)

State Transitions:

• 1: This state transition happens, when the user initiates the post request
• 2: Post request is active SSVM agent is downloading validation or downloading the template but, not done yet
• 3: on successful completion of template installation to secondary storage
• 4: This can happen in multiple ways:
  • user stopped/canceled the post request before completion
  • SSL handshake failed
  • params validation with PSK failed
  • uploading the template failed due to a network issue
  • secondary storage is not accessible
  • there isn't enough space in secondary storage and hence agent cant write to it.
    All these errors have the same state as there isnt any way to recover from them or the handling isnt different for these. Additional error information will be provided in the form of a message for respective errors.

• 5: The post request hasn't happened and the timeout has reached

UI Changes

A new register template and upload volume UI which should be able to accept "browse and upload" file. 

UI flow:

1. Browser UI requests the upload form by doing the getUploadParams api call. 
2. Management Server returns a upload url, params json string which should be passed on to the upload url while doing the upload
3. UI shows an upload dialog with a way to browse and upload file.
4. User chooses a file and posts on the url.
5. The post request completes once the template is downloaded/errored. 
6. The user can close the dialog(Post request should still be active) and use list page to check the status of it.

DB Changes

No db changes.

Major Tasks

1. A new SSVM template is required.
2. setting up https on SSVM, opening the relevant ports doing the SSL handshake
   1. http://www.symantec.com/connect/articles/apache-2-ssltls-step-step-part-1
3. initial keystore exchange and authentication using the keystore
4. understanding template code 

Future

1. Upload progress to the user (http://creativejs.com/tutorials/advanced-uploading-techniques-part-1/ )
2. split upload and join in apache so as to not hit browser timeouts

3. post url should be active only for one time call - return proper error message on subsequent calls - how do we determine if its already used?

4. Admin to list all the uploads happening and cancel any if required?

5. Partial data upload and template cleanup (can be due to SSVM to agent restart or network error)

Open Questions

1. Multipart form data - Can this go in multiple connections?

2. SSVM storage issue. What should we tell the user? How can we notify the admin to recover from it?

3. Should there be an unencrypted HTTP version of the post?  No for now

4. No. of parallel uploads SSVM can handle? a default value should be provided to tune the apache to handle those many parallel connections. These should be determined based on the CPU RAM of SSVM - a proper error message to the user on reaching this limit

Needs current code investigation

check download template/volume code to see how the below scenarios are handled

1. multiple SSVMs. Which agent should handle the upload? 

2. cross zone template upload
3. system vm template upload
4.  default timeouts and configurable values - updated default values. There are no configurable values
5. multiple management servers with the one monitoring the download crashed (How is the template status updated? A. when the download hasnt started yet. B. upload in progress C. upload done)
6. How does the agent return template status for DownloadProgressCommand? (in memory hashmap of in progress items. need to check of it recovers the status during a restart or when done)