initial documentation - note this is not current and needs to be updated

2013-04-24 11:05:07 +02:00 · 2013-04-24 11:05:07 +02:00 · e24f1fefc3
parent c22ee1ff90
commit e24f1fefc3
1 changed files with 108 additions and 0 deletions
--- a/doc/occi.md
+++ b/doc/occi.md
@ -0,0 +1,108 @@
+# OCCI and OpenStack: What can I do?
+This guide will explain what you can do with the current OCCI implementation for OpenStack
+
+## First up, prerequisites:
+### Get a running instance of OpenStack
+Lots of ways to do this:
+
+ * Install via apt-get
+ * Install with puppet
+ * Install with chef
+ * Install with crowbar
+ * Install with devstack
+ 
+The easiest is devstack.
+### Get the OCCI code
+
+#### OCCI Library
+On the machine(s) that you run the OCCI API, likely the same as the machine(s) as you run the OS-API, run the following:
+
+>```pip install pyssf```
+
+#### OCCI API Implementation
+On the machine(s) that you want to run the OCCI API, likely the same as the machine(s) as you run the OS-API, run the following:
+
+>```cd $YOUR_NOVA_INSTALL_LOCATION```
+
+>```git add remote occi-upstream git://git@github.com/dizz/nova```
+
+>```git fetch occi-upstream```
+
+>```git merge occi-upstream/master```
+
+### Configure devstack to run the volume service. Edit localrc and insert:
+>```ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-obj,n-cpu,n-net,n-sch,n-novnc,n-xvnc,n-cauth,horizon,mysql,rabbit,n-vol,openstackx```
+
+### Run the OS-OCCI API
+>```./bin/nova-api-occi --verbose --glance_api_servers=10.211.55.27:9292 --rabbit_host=10.211.55.27 --rabbit_password=admin --sql_connection=mysql://root:admin@10.211.55.27/nova```
+
+### Get Authentication Credentials from Keystone
+>```curl -d '{"auth":{"passwordCredentials":{"username": "admin", "password": "admin"}}}' -H "Content-type: application/json" http://10.211.55.27:35357/v2.0/tokens
+```
+
+>```export $KID=<<Token from Keystone>>```
+
+## OCCI-ness
+
+_Note:_ some confusion will happen if a content-type is not specified.
+
+### See What Can be Provisioned
+>```curl -v -H 'X-Auth-Token: '$KID -H -X GET 0.0.0.0:8787/-/
+```
+
+### Create a VM
+>```curl -v -X POST localhost:8787/compute/ -H 'Category: compute; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"' -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: m1.tiny; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"' -H 'Category: cirros-0.3.0-x86_64-blank; scheme="http://schemas.openstack.org/template/os#"; class="mixin"'
+```
+
+### Get a Listing of VMs
+>```curl -v -X GET localhost:8787/compute/ -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1'
+```
+
+### Get an Individual VM's details
+>```curl -v -X GET localhost:8787/compute/d54b4344-16be-486a-9871-2c566ef2263d -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1'
+```
+
+### Execute a Stop Action Upon a VM
+>```curl -v -X POST localhost:8787/compute/d54b4344-16be-486a-9871-2c566ef2263d?action=stop -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: stop; scheme="http://schemas.ogf.org/occi/infrastructure/compute/action#"; class="action"'
+```
+
+### Execute a Start Action Upon a VM
+_Note: this will probably result in an error state. Currently looking into the issue._
+
+>```curl -v -X POST localhost:8787/compute/888fc64a-4500-4543-bed4-8ddf3938dcb5?action=start -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: start; scheme="http://schemas.ogf.org/occi/infrastructure/compute/action#"; class="action"'
+```
+
+### Delete a VM
+>```curl -v -X DELETE localhost:8787/compute/d54b4344-16be-486a-9871-2c566ef2263d -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' 
+```
+
+### Create some a block storage volume
+>```curl -v -X POST localhost:8787/storage/ -H 'Category: storage; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"' -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'occi.storage.size = 1.0'
+```
+
+### Link and associate that volume to the new instance
+>```curl -v -X POST localhost:8787/storage/link/ -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: storagelink; scheme="http://schemas.ogf.org/occi/infrastructure#"; class="kind"' -H 'X-OCCI-Attribute: occi.core.source="http://localhost:8787/compute/e7a34bc4-02e7-43e3-a543-8aec630b5364"' -H 'X-OCCI-Attribute: occi.core.target="http://localhost:8787/storage/1"' -H 'X-OCCI-Attribute: occi.storagelink.mountpoint="/dev/vdb"' -H 'Content-Type: text/occi'```
+
+### Unlink and disassociate that volume with the new instance
+>```curl -v -X DELETE localhost:8787/storage/link/6cb97f63-7d8a-4474-87cb-4d1c9c581de1 -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Content-Type: text/occi'```
+
+## Upcoming
+### Update a VM: Scale up!
+Let's bump the current instance from tiny (512) to a custom flavour (768R, 1C).
+_Notes:_ 
+
+* This is a partial update with respect to OCCI.
+* This only works with Xen currently
+  * otherwise it fails silently
+
+>```curl -v -X POST localhost:8787/compute/2ee26373-db62-4bbf-9325-ff68a81097e3 -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: m1.medium; scheme="http://schemas.openstack.org/template/resource#"; class="mixin"'
+```
+
+### Update a VM: Change the OS!
+Let's use SmartOS as the new OS
+_Notes:_ 
+
+* this is in effect a partial update.
+
+>```curl -v -X POST localhost:8787/compute/d54b4344-16be-486a-9871-2c566ef2263d -H 'Content-Type: text/occi' -H 'X-Auth-Token: '$KID -H 'X-Auth-Project-ID: 1' -H 'Category: SmartOS; scheme="http://schemas.openstack.org/template/os#"; class="mixin"'
+```