<commit_before>[![Build Status](https://travis-ci.org/cloudfoundry-community/bosh-cloudstack-cpi-release.png)](https://travis-ci.org/cloudfoundry-community/bosh-cloudstack-cpi-release)



# bosh-cloudstack-cpi-release

This is work in progress / feedbacks welcome (use issues).


## Design :
* this CPI is a Bosh external CPI i.e a dedicated bosh release wich must be deployed alongside a bosh release OR configured with bosh release in a bosh-init yml manifest
*  CPI business logic is in a dedicated spring boot app, included in bosh-cloudstack-cpi-release, called cpi-core. This java component has a dedicated template / monit service.
* leverages Apache Jclouds support for CloudStack, nice java adapter for Cloudstack API
* supports Cloudstack advanced zone
* secondary / ephemeral implemented as cloudstack volume (no ephemeral disk concept in CloudStack).
* Uses a webdav http server to enable stemcell / template loading by cloudstack (other option was create volume and transform to template, required bosh / bosh-init to be hosted in the target cloud / tenant). This webdav server is started from the spring boot cpi core jvm

* Out of Scope : security groups provisioning / CS Basic Zones

## Current Status:



### Global status
* micro-bosh creation (with an externally launched cpi-core process)
* compilation vms ok, blobstore ok
* bosh-master creation from micro-bosh
* concourse creation from bosh-master
	
### Issues
* local storage issues (persistent disks happen to not be on the same host as vm when reconfiguring a deployment)
* ip conflicts when recreating vm, due to cloudstack expunge delay (orig vm is destroyed but ip not yet releases)
* disk / mount issues (probably related to vm expunge delay)
* stemcell agent.json user data url is hardcoded. must find a way to find the correct cloudstack userdata url on the fly
* stemcell : cant get keys from cloudstack metadata (requires stemcell code change to match cloudstack)
* no support for vip / floating ip yet	


## TODO

* run Director BATS against the cpi
	https://github.com/cloudfoundry/bosh/blob/master/docs/running_tests.md

* expunge vm
	required with static ip vms (ip not freed until vm is expunged)
	default value expunge.delay = 300 (5 mins)
	option 1
		reduce to 30s as cloudstack admin => need to restart management server 
		wait 30s in CPI after vm delete
	option2
		expunge with cloudstack API. option not avail in jclouds 1.9, use escaping mechanism to add the expunge flag?
* check template publication
	from cpi-core webdav, only public template possible ?
	validate publication state (instant OK for registering, need to wait for the ssvm (secondary storage vm) to copy the template
	connectivity issue when cloudstack tries asynchronously to copy template : vlan opened, dedicated chunk encoding compatible spring boot endpoint
	(workaround: mock template mode in cpi. copies an existing template and use it as a stemcell image)
	
	add a garbarge collection mechanism to the webdav server (remove old templates when consumed by cloudstack)	

* use isolated / dedicated networks for bosh vms
	http://www.shapeblue.com/using-the-api-for-advanced-network-management/
	static API assigned through API deployVirtualMachine	

* persist bosh registry.
	now hsqldb
	set persistent file in /var/vcap/store/cpi
	TBC : use bosh postgres db (add postgres jdbc driver + dialect config + bosh *db credentials injection)


* globals
	harden Exception mangement
	map spring boot /error to an intelligible CPI rest payload / stdout
	update json reference files for unit tests

	

* provision ssh keys
	generate keypair with cloudstack API (no support on portail)
	use keypair name + private key in bosh.yml
	see http://cloudstack-administration.readthedocs.org/en/latest/virtual_machines.html?highlight=ssh%20keypair
	see http://chriskleban-internet.blogspot.fr/2012/03/build-cloud-cloudstack-instance.html




## Typical bosh.yml configuration to activate the CloudStack external CPI

```yml

# add the cpi bosh release
releases:
- {name: bosh, version: "185"}
- {name:  bosh-cloudstack-cpi, version: latest}

# add the template for cpi-core rest server
jobs:
- name: bosh_apidata
  templates:
  - {name: nats, release: bosh}
  - {name: redis, release: bosh}
  - {name: postgres, release: bosh}
  - {name: blobstore, release: bosh}
  - {name: director, release: bosh}
  - {name: health_monitor, release: bosh}
  - {name: powerdns, release: bosh}
  - {name: cpi, release: bosh-cloudstack-cpi}


# activate external cpi
properties:
  director:
    cpi_job: cpi

# set external cpi credentials
   cloudstack:
      endpoint: <your_end_point_url> # Ask for your administrator
      api_key: <your_api_key> # You can find at your user page
      secret_access_key: <your_secret_access_key> # Same as above
      default_key_name: <default_keypair_name> # Your keypair name (see the next section)
      private_key: <path_to_your_private_key> # The path to the private key file of your key pair
      state_timeout: 600
      state_timeout_volume: 1200
      stemcell_public_visibility: true
      default_zone: <default_zone_name> # Zone name
      proxy_host: <proxy to cloudstack api> #proxy acces active if set
      proxy_port: <proxy port>
      proxy_user: <proxy user>
      proxy_password: <proxy password>
      
```


Typical bosh manifest to deploy on cloudstack<commit_msg>update manifest with expected cpi-core cpi.* properties<commit_after>[![Build Status](https://travis-ci.org/cloudfoundry-community/bosh-cloudstack-cpi-release.png)](https://travis-ci.org/cloudfoundry-community/bosh-cloudstack-cpi-release)



# bosh-cloudstack-cpi-release

This is work in progress / feedbacks welcome (use issues).


## Design :
* this CPI is a Bosh external CPI i.e a dedicated bosh release wich must be deployed alongside a bosh release OR configured with bosh release in a bosh-init yml manifest
*  CPI business logic is in a dedicated spring boot app, included in bosh-cloudstack-cpi-release, called cpi-core. This java component has a dedicated template / monit service.
* leverages Apache Jclouds support for CloudStack, nice java adapter for Cloudstack API
* supports Cloudstack advanced zone
* secondary / ephemeral implemented as cloudstack volume (no ephemeral disk concept in CloudStack).
* Uses a webdav http server to enable stemcell / template loading by cloudstack (other option was create volume and transform to template, required bosh / bosh-init to be hosted in the target cloud / tenant). This webdav server is started from the spring boot cpi core jvm

* Out of Scope : security groups provisioning / CS Basic Zones

## Current Status:



### Global status
* micro-bosh creation (with an externally launched cpi-core process)
* compilation vms ok, blobstore ok
* bosh-master creation from micro-bosh
* concourse creation from bosh-master
	
### Issues
* local storage issues (persistent disks happen to not be on the same host as vm when reconfiguring a deployment)
* ip conflicts when recreating vm, due to cloudstack expunge delay (orig vm is destroyed but ip not yet releases)
* disk / mount issues (probably related to vm expunge delay)
* stemcell agent.json user data url is hardcoded. must find a way to find the correct cloudstack userdata url on the fly
* stemcell : cant get keys from cloudstack metadata (requires stemcell code change to match cloudstack)
* no support for vip / floating ip yet	


## TODO

* run Director BATS against the cpi
	https://github.com/cloudfoundry/bosh/blob/master/docs/running_tests.md

* expunge vm
	required with static ip vms (ip not freed until vm is expunged)
	default value expunge.delay = 300 (5 mins)
	option 1
		reduce to 30s as cloudstack admin => need to restart management server 
		wait 30s in CPI after vm delete
	option2
		expunge with cloudstack API. option not avail in jclouds 1.9, use escaping mechanism to add the expunge flag?
* check template publication
	from cpi-core webdav, only public template possible ?
	validate publication state (instant OK for registering, need to wait for the ssvm (secondary storage vm) to copy the template
	connectivity issue when cloudstack tries asynchronously to copy template : vlan opened, dedicated chunk encoding compatible spring boot endpoint
	(workaround: mock template mode in cpi. copies an existing template and use it as a stemcell image)
	
	add a garbarge collection mechanism to the webdav server (remove old templates when consumed by cloudstack)	

* use isolated / dedicated networks for bosh vms
	http://www.shapeblue.com/using-the-api-for-advanced-network-management/
	static API assigned through API deployVirtualMachine	

* persist bosh registry.
	now hsqldb
	set persistent file in /var/vcap/store/cpi
	TBC : use bosh postgres db (add postgres jdbc driver + dialect config + bosh *db credentials injection)


* globals
	harden Exception mangement
	map spring boot /error to an intelligible CPI rest payload / stdout
	update json reference files for unit tests

	

* provision ssh keys
	generate keypair with cloudstack API (no support on portail)
	use keypair name + private key in bosh.yml
	see http://cloudstack-administration.readthedocs.org/en/latest/virtual_machines.html?highlight=ssh%20keypair
	see http://chriskleban-internet.blogspot.fr/2012/03/build-cloud-cloudstack-instance.html




## Typical bosh.yml configuration to activate the CloudStack external CPI

```yml

# add the cpi bosh release
releases:
- {name: bosh, version: "185"}
- {name:  bosh-cloudstack-cpi, version: latest}

# add the template for cpi-core rest server
jobs:
- name: bosh_apidata
  templates:
  - {name: nats, release: bosh}
  - {name: redis, release: bosh}
  - {name: postgres, release: bosh}
  - {name: blobstore, release: bosh}
  - {name: director, release: bosh}
  - {name: health_monitor, release: bosh}
  - {name: powerdns, release: bosh}
  - {name: cpi, release: bosh-cloudstack-cpi}


# activate external cpi
properties:
  director:
    cpi_job: cpi

# set external cpi credentials
   cloudstack:
      endpoint: <your_cloudstack api end_point_url> # Ask for your administrator
      api_key: <your_api_key> # You can find at your user page
      secret_access_key: <your_secret_access_key> # Same as above
      default_key_name: <default_keypair_name> # Your keypair name (see the next section)
      private_key: <path_to_your_private_key> # The path to the private key file of your key pair
      state_timeout: 600
      state_timeout_volume: 1200
      stemcell_public_visibility: true
      default_zone: <default_zone_name> # Zone name
      proxy_host: <proxy to cloudstack api> #proxy acces active if set
      proxy_port: <proxy port>
      proxy_user: <proxy user>
      proxy_password: <<PASSWORD>>
      
	  cpi:
	    webdav_host: *bosh_static_ip
	    mock_create_stemcell: true
	    existing_template_name: "bosh-stemcell-3033-po10.vhd.bz2"
	
	    registry:
	      endpoint: http://<bosh_ip>:8080
	
	    blobstore:
	        address: *bosh_static_ip
	        port: 25251
	        provider: dav
	        agent: {user: agent, password: <PASSWORD>}
	    agent:
	      mbus: "nats://nats:nats-password@<bosh_ip>:4222"
	    ntp: ""
       
      
      
# define disk_pool, refering to cloudstack disk offering      
disk_pools:
- name: disks
  disk_size: 10000
  cloud_properties:
    disk_offering: "DO2 - Medium STD" #<--- Replace with your disk offering name for persistent disk
      
# define vm pool, refering to cloudstack compute offering      
resource_pools:
- name: vms
  stemcell:
    name: bosh-cloudstack-xeb-ubuntu-trusty-go_agent-raw
    version: latest
  network: private
  size: 1
  cloud_properties:
    compute_offering: "CO1 - Small STD" #<--- Replace with your compute offering name
    disk: 20000
    ephemeral_disk_offering : "DO2 - Medium STD" #<--- Replace with the disk offering u want for ephemeral disk
      
      
```


Typical bosh manifest to deploy on cloudstack
{'fraction_non_alphanumeric': 0.06847360912981455, 'fraction_numerical': 0.007887891247797265, 'mean_word_length': 3.9493355481727574, 'pattern_counts': {'":': 0, '<': 30, '<?xml version=': 0, '>': 29, 'https://': 6, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1610600', 'n_tokens_mistral': 3663, 'n_tokens_neox': 3423, 'n_words': 1409}