Creating a Cartridge on vCloud

Follow the instructions below to configure a cartridge image for WSO2 Private PaaS on vCloud:

Step 1 - Install VMWare Tools on the VM 

1. Log in to the VMWare vCloud Director console. 
2. Click My Cloud on the top menu bar and click VMs on the left navigation bar.
3. Right-click on the VM from the list and click Install VMWare Tools on the pop-up menu.
   
   

Step 2 - Add the VM and vApp to My Cloud

1. Click Catalogs on the top menu bar and click Public Catalogs on the left navigation bar.
   
2. Right click on any of the available options in OS Templates and click Add to My Cloud from the available options.
   
3. In the Select name and Location window, enter a preferred name for the vApp. The virtual data center, on which the vApp will be stored, will appear automatically.
   
4. Click Next in the Configure Resources window, since you do not need to specify any information in it.
5. In the Configure Networking window, make sure to select Direct Internet connection in the Networks column.
   
6. In the Customize Hardware window, enter the details of the hardware configurations as required for CPU, Memory and Hard Disks.
   
7. In the  Ready to Complete  window, select the option to power on vApp after this wizard is finished,  as we need to configure init scripts inside the VM.
   
8. Click Finish to complete the configuration wizard and to add the vApp to your cloud.     

Step 3 - Configure the VM

1. On My Cloud, you will see the vApp and the VM being started as below.  
   
   
2. Click on VMs to find out the IP of the spawned VM that is mentioned in the IP Address column.
   
3. Click Properties on the Actions menu to view the property configurations of the VM.
   
   
4. Click on Guest OS Customization and copy the generated password.
   

5. Use the IP address that you found out in step 2 of this section, and the password that you copied in the above step, to log in to the VM  via SSH as root.

   ssh root@<IP Address>

   Example:  ssh root@212.54.141.146

6. Create a new folder named bin in the root/ directory using the following command:
   

   mkdir bin

7. Copy the required files to the bin/ folder.

   projects/incubator-stratos/tools/puppet3-agent$ scp -r init-vcloud.sh puppetinstall stratos_sendinfo.rb root@212.54.141.146:bin

8. Install zip and unzip programs on the server as we will be using those in the init script.
   

   apt-get install zip unzip

Step 4 - Create the vApp template from the vApp and adding it to the Catalog

1. Click  Shutdown Guest OS  on the Actions menu of VMs,  to shutdown the OS.
   
2. Click Stop on the Actions menu of vApps to stop the vApp.
   
3. Click Add to Catalog to add the vApp to the Catalog in the Actions menu.
   
4. Click OK in the Add to Catalog window to create the  vApp template. 
   
5. Go to  Catalogs and click  My Organization's Catalogs.  Select  vApp Templates to view the created template.
   

Step 5 - Get the URL of the created template

Get the URL of this created template by invoking vCloud REST APIs as follows:    

1.   Get the authorization token from vCloud using the following command: 
   

   curl -i -k -H "Accept:application/*+xml;version=5.1" -u "udarasampath@YourOrg:vcloudpassword" -X POST  https://mycloud.stratogen.sg/api/sessions

   The response of the above, including the obtained authorization token, will be as follows:

   HTTP/1.1 200 OK
   Date: Fri, 21 Mar 2014 16:02:10 GMT
   Vary: Accept-Encoding
   x-vcloud-authorization: wTCD0dTcH8urNZH6BfXGIKVAuJgE6fy4PpgjKiY3ZOg=
   Content-Type: application/vnd.vmware.vcloud.session+xml;version=5.1
   Content-Length: 1268
   Set-Cookie: vcloud-token=wTCD0dTcH8urNZH6BfXGIKVAuJgE6fy4PpgjKiY3ZOg=; Secure; Path=/
   Set-Cookie: ROUTEID=.vcd2; path=/
   Connection: close
   
   <Session xmlns="http://www.vmware.com/vcloud/v1.5" user="udarasampath" org="YourOrg" type="application/vnd.vmware.vcloud.session+xml" href="https://mycloud.stratogen.sg/api/session/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://mycloud.stratogen.sg/api/v1.5/schema/master.xsd">
           <Link rel="down" type="application/vnd.vmware.vcloud.orgList+xml" href="https://mycloud.stratogen.sg/api/org/"/>
           <Link rel="remove" href="https://mycloud.stratogen.sg/api/session/"/>
           <Link rel="down" type="application/vnd.vmware.admin.vcloud+xml" href="https://mycloud.stratogen.sg/api/admin/"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.org+xml" name="YourOrg" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.query.queryList+xml" href="https://mycloud.stratogen.sg/api/query"/>
           <Link rel="entityResolver" type="application/vnd.vmware.vcloud.entity+xml" href="https://mycloud.stratogen.sg/api/entity/"/>
           <Link rel="down:extensibility" type="application/vnd.vmware.vcloud.apiextensibility+xml" href="https://mycloud.stratogen.sg/api/extensibility"/>
   </Session>

   The x-vcloud-authorization token and the URL with the type="application/vnd.vmware.vcloud.org+xml" and name="YourOrg", which are obtained from the above response, will be used in the next step.

2. Get the details of the organization using the following command:

   curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: wTCD0dTcH8urNZH6BfXGIKVAuJgE6fy4PpgjKiY3ZOg=" -X GET https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013

     The response of the above including the obtained organization details,  will be as follows:

    HTTP/1.1 200 OK
   Date: Fri, 21 Mar 2014 16:03:43 GMT
   Vary: Accept-Encoding
   Content-Type: application/vnd.vmware.vcloud.org+xml;version=5.1
   Content-Length: 3189
   Set-Cookie: ROUTEID=.vcd2; path=/
   Connection: close
    
   
   <Org xmlns="http://www.vmware.com/vcloud/v1.5" name="YourOrg" id="urn:vcloud:org:95339bad-7431-4f6c-a0b0-4b323742013c" type="application/vnd.vmware.vcloud.org+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://mycloud.stratogen.sg/api/v1.5/schema/master.xsd">
           <Link rel="down" type="application/vnd.vmware.vcloud.vdc+xml" name="YourOrg" href="https://mycloud.stratogen.sg/api/vdc/fb594881-b50c-4ac9-91c8-f536f9beb03d"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.tasksList+xml" href="https://mycloud.stratogen.sg/api/tasksList/95339bad-7431-4f6c-a0b0-4b323742013c"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" name="OS Templates" href="https://mycloud.stratogen.sg/api/catalog/6663ed3b-7575-46bc-b449-2333be86eff7"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalog/6663ed3b-7575-46bc-b449-2333be86eff7/controlAccess/"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" name="stratos_base_image" href="https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalog/85520199-e007-4536-aa67-fa3179a3ca9b/controlAccess/"/>
           <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalog/85520199-e007-4536-aa67-fa3179a3ca9b/action/controlAccess"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.catalog+xml" name="YourOrgsamples" href="https://mycloud.stratogen.sg/api/catalog/306b5c57-f2a7-445d-ada3-0c1e64bc8b6a"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalog/306b5c57-f2a7-445d-ada3-0c1e64bc8b6a/controlAccess/"/>
           <Link rel="controlAccess" type="application/vnd.vmware.vcloud.controlAccess+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalog/306b5c57-f2a7-445d-ada3-0c1e64bc8b6a/action/controlAccess"/>
           <Link rel="add" type="application/vnd.vmware.admin.catalog+xml" href="https://mycloud.stratogen.sg/api/admin/org/95339bad-7431-4f6c-a0b0-4b323742013c/catalogs"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.orgNetwork+xml" name="Direct Internet connection" href="https://mycloud.stratogen.sg/api/network/d4e95fb6-c1b7-4d80-94b0-65ecd58516cc"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.supportedSystemsInfo+xml" href="https://mycloud.stratogen.sg/api/supportedSystemsInfo/"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c/metadata"/>
           <Description>YourOrg</Description>
           <FullName>YourOrg</FullName>
   </Org>

   The x-vcloud-authorization token received in step 1 of this section and, the URL with the type="application/vnd.vmware.vcloud.catalog+xml" and name="stratos_base_image", which is obtained from the above response, will be used in the next step.

3. Get the details of the catalog using the following command:
   

   curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: wTCD0dTcH8urNZH6BfXGIKVAuJgE6fy4PpgjKiY3ZOg=" -X GET https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b

     The response of the above with the obtained catalog details, will be as follows: 

   HTTP/1.1 200 OK
   Date: Fri, 21 Mar 2014 16:04:00 GMT
   Vary: Accept-Encoding
   Content-Type: application/vnd.vmware.vcloud.catalog+xml;version=5.1
   Content-Length: 1643
   Set-Cookie: ROUTEID=.vcd2; path=/
   Connection: close
    
   
   <Catalog xmlns="http://www.vmware.com/vcloud/v1.5" name="stratos_base_image" id="urn:vcloud:catalog:85520199-e007-4536-aa67-fa3179a3ca9b" type="application/vnd.vmware.vcloud.catalog+xml" href="https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://mycloud.stratogen.sg/api/v1.5/schema/master.xsd">
           <Link rel="up" type="application/vnd.vmware.vcloud.org+xml" href="https://mycloud.stratogen.sg/api/org/95339bad-7431-4f6c-a0b0-4b323742013c"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b/metadata"/>
           <Link rel="add" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b/catalogItems"/>
           <Description>base image for stratos cartirages</Description>
           <CatalogItems>
               <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="vApp_base_cartridge" id="f0dc78f0-2c57-469d-9f71-fc242f03ca30" href="https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30"/>
               <CatalogItem type="application/vnd.vmware.vcloud.catalogItem+xml" name="vApp_stratos_setup" id="726b3baa-be60-4163-8d63-aec9e03b16fe" href="https://mycloud.stratogen.sg/api/catalogItem/726b3baa-be60-4163-8d63-aec9e03b16fe"/>
           </CatalogItems>
           <IsPublished>false</IsPublished>
           <DateCreated>2014-02-03T14:34:13.538+08:00</DateCreated>
   </Catalog>

   The x-vcloud-authorization token received in step 1 of this section and, the URL with the type="application/vnd.vmware.vcloud.catalog+xml" and name="stratos_base_image", which is obtained from the above response, will be used in the next step.

4. Retrieve the catalog item for the vApp Template which you created as follows:
   

   curl -i -k -H "Accept:application/*+xml;version=5.1" -H "x-vcloud-authorization: wTCD0dTcH8urNZH6BfXGIKVAuJgE6fy4PpgjKiY3ZOg=" -X GET https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30

    The response of the above with the obtained  catalog item  will be as follows:

   HTTP/1.1 200 OK
   Date: Fri, 21 Mar 2014 16:04:10 GMT
   Vary: Accept-Encoding
   Content-Type: application/vnd.vmware.vcloud.catalogitem+xml;version=5.1
   Content-Length: 1381
   Set-Cookie: ROUTEID=.vcd2; path=/
   Connection: close
   
   
   <CatalogItem xmlns="http://www.vmware.com/vcloud/v1.5" size="0" name="vApp_base_cartridge" id="urn:vcloud:catalogitem:f0dc78f0-2c57-469d-9f71-fc242f03ca30" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.vmware.com/vcloud/v1.5 http://mycloud.stratogen.sg/api/v1.5/schema/master.xsd">
           <Link rel="up" type="application/vnd.vmware.vcloud.catalog+xml" href="https://mycloud.stratogen.sg/api/catalog/85520199-e007-4536-aa67-fa3179a3ca9b"/>
           <Link rel="down" type="application/vnd.vmware.vcloud.metadata+xml" href="https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30/metadata"/>
           <Link rel="edit" type="application/vnd.vmware.vcloud.catalogItem+xml" href="https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30"/>
           <Link rel="remove" href="https://mycloud.stratogen.sg/api/catalogItem/f0dc78f0-2c57-469d-9f71-fc242f03ca30"/>
           <Entity type="application/vnd.vmware.vcloud.vAppTemplate+xml" name="vApp_base_cartridge" href="https://mycloud.stratogen.sg/api/vAppTemplate/vappTemplate-13c0a522-aefb-4567-ba09-b3b9fd4de0a6"/>
           <DateCreated>2014-03-21T22:46:17.930+08:00</DateCreated>
   </CatalogItem>

   Use the vApp template URL with the t ype="application/vnd.vmware.vcloud.vAppTemplate+xml" and name="vApp_base_cartridge" in the above response, as the image ID in the cartridge definition.

5. Use the following script to pass payload to the VM using shell script.
   

   /opt/stratos/apache-stratos-cc-4.0.0/repository/conf/scripts/sh/customization

   The script content must be as follows:
   

   #!/bin/sh
   mkdir -p /tmp/payload
   echo "PAYLOAD" > /tmp/payload/launch-params
   /root/bin/init-vcloud.sh > /tmp/puppet_log

   The "PAYLOAD" string will be replaced by the actual payload when spawning the instance.  

   The above example on passing payload is defined only for the “sh” shell type. This expects that target OS will able to run “sh” scripts. We need to define this shell type in the cartridge definition as follows:

   {
             "type": "php",
             "provider": "apache",
             "host": "stratosvcloud.com",
             "displayName": "PHP",
             "description": "PHP Cartridge",
             "version": "5.0",
             "multiTenant": "false",
             "portMapping": [
                {
                   "protocol": "http",
                   "port": "80",
                   "proxyPort": "8280"
                },
                {
                   "protocol": "https",
                   "port": "443",
                   "proxyPort": "8243"
                }
              ],
             "deployment": {
               },
              "iaasProvider": [
               {
                 "type": "vcloud",
                 "imageId": "https://mycloud.stratogen.sg/api/vAppTemplate/vappTemplate-13c0a522-aefb-4567-ba09-b3b9fd4de0a6",
                 "maxInstanceLimit": "4",
   		"property": [
               {
                    "name": "shellType",
                    "value": "sh"
                   }
              ]
   
               }
             ],
            "loadBalancer": {
               "type": "lb",
               "property": {
                   "name": "default.load.balancer",
                   "value": "true"
               }
             },
    }