Return-Path:
Installing the Deltacloud Ruby client also gives you the deltacloudc command line tool. This executable uses the Deltacloud client library to speak to the Deltacloud server through the REST API. This means that you can control your cloud infrastructure from the command line. The general usage pattern for deltacloudc is:
@@ -18,7 +32,7 @@ title: Command Line Tools
The cURL documentation is pretty comprehensive, but the following are some general points to remember for using cURL against Deltacloud. All the examples on this page assume the deltacloud server is running at localhost:3001: Display a complete list of instances in xml format: Launch an instance. Note that in this example parameters are specified as application/x-www-form-urlencoded through the use of the -d flag: Alternatively, you can use the -F flag to specify the parameters as multipart/form-data: Launch an instance action - reboot: Run command on an instance (where available): Get the details of a specific image: Create an image from an existing instance (where available): Delete an image: Get a list of all hardware profiles: Get the details of a specific hardware profile: Get a list of all realms: Get the details of a specific realm: Get a list of all keys: Create a new key (where available): Import an existing key (where available): Delete a key: Get a list of all firewalls: Create a new firewall: Create a new firewall rule - port 22 tcp, with one source firewall (group) and 2 IP addresses: Delete a firewall rule: Delete a firewall: Get a list of all addresses: Create a new address: Associate an address with an instance: Disassociate an address from an instance: Delete an address: Get a list of all load balancers: Create a load balancer: Register an instance with a load balancer: Unregister an instance from a load balancer: Delete a load balancer: Get the details of a bucket: Create a new bucket: Create a new blob, specifying a content-type and some metadata: Note that the --upload-file parameter above causes cURL to issue a HTTP PUT Get blob metadata: Note that blob metadata is returned in the HTTP response headers. So the use of the -v flag is important here or you will not see the metadata. Update blob metadata: Delete a blob: Delete a bucket: Get a list of all storage volumes: Create a new storage volume: Attach a volume to a running instance: Detach a volume (from whichever instance it is connected to): Delete a storage volume: Get details about a specific storage snapshot: Create a new storage snapshot: Delete a storage snapshot:
+
+deltacloudc is being deprecated
+
+The deltacloudc command line tool is being deprecated. For now the code making up deltacloudc has been moved to the /deltacloud/clients/console directory but will ultimately be removed from the repo. If the command line client is important to you then please let us know. A new command line client may be put onto the roadmap if there is demand for one.
+
+The deltacloud core developers use (almost exclusively) cURL as a command line client for working with a deltacloud server. You can find more information on working with cURL against deltacloud here.
+
+
+
+ /deprecated:
+
+
+
+
Using Deltacloud command tool
+
+Working with cURL as a command line client
+
+
+
+
+
+curl -v -X DELETE --user "username:password" -H "Accept: application/xml" http://localhost:3001/api/keys/mykey
+
+
+
+Working with instances
+
+ curl --user "user:pass" http://localhost:3001/api/instances?format=xml
+
+Alternatively and if you prefer you can manually specify the Accept header:
+
+ curl --user "user:pass" -H "Accept: application/xml" http://localhost:3001/api/instances
+
+ curl -X POST --user "user:pass" -d "image_id=ami-84db39ed&hwp_id=m1.small&keyname=marios_key" http://localhost:3001/api/instances?format=xml
+
+ curl -X POST --user "user:pass" -F "image_id=ami-84db39ed" -F "hwp_id=m1.small" -F "keyname=marios_key" http://localhost:3001/api/instances?format=xml
+
+ curl -X POST --user "user:pass" http://localhost:3001/api/instances/reboot?format=xml
+
+ curl -X POST --user "user:pass" -F "cmd=uname -a; ls -l" -F "private_key=`cat /location/of/ssh/keyfile`" http://localhost:3001/api/instances/i-d77cd0ac/run?format=xml
+
+Working with images
+
+ curl --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml
+
+curl -X POST --user "user:pass" -d "instance_id=i-d77cd0ac&name=mariostestimage" http://localhost:3001/api/images?format=xml
+
+curl -X DELETE --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml
+
+Working with hardware profiles
+
+ curl --user "user:pass" http://localhost:3001/api/hardware_profiles?format=xml
+
+ curl --user "user:pass" http://localhost:3001/api/hardware_profiles/m2.4xlarge?format=xml
+
+Working with realms
+
+ curl --user "user:pass" http://localhost:3001/api/realms?format=xml
+
+ curl --user "user:pass" http://localhost:3001/api/realms/us-east-1a?format=xml
+
+Working with keys
+
+ curl --user "user:pass" http://localhost:3001/api/keys?format=xml
+
+ curl -X POST --user "user:pass" -d "name=mynewkey" http://localhost:3001/api/keys?format=xml
+
+ curl -X POST --user "user:pass" -F "name=mynewkey" -F "public_key=`cat /location/of/public/key/id_rsa.pub`" http://localhost:3001/api/keys?format=xml
+
+ curl -X DELETE --user "user:pass" http://localhost:3001/api/keys/mynewkey?format=xml
+
+Working with firewalls
+
+ curl -v --user "user:pass" http://localhost:3001/api/firewalls?format=xml
+
+ curl -v -X POST --user "user:pass" -d "name=my_new_firewall&description=a test firewall" http://localhost:3001/api/firewalls?format=xml
+
+ curl -v -X POST --user "user:pass" -F "protocol=tcp" -F "port_from=22" -F "port_to=22" -F "group1=default" -F "group1owner=821108636519" -F "ip_address1=192.168.1.1/24" -F "ip_address2=65.128.31.27/32" http://localhost:3001/api/firewalls/my_new_firewall/rules
+
+ curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall/821108636519~tcp~22~22~@group,821108636519,default,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32?format=xml
+
+curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall?format=xml
+
+Working with addresses
+
+ curl -v --user "user:pass" http://localhost:3001/api/addresses?format=xml
+
+ curl -v --user "user:pass" -X POST http://localhost:3001/api/addresses?format=xml
+
+
+ curl -v -X POST --user "user:pass" -d "instance_id=i-d77cd0ac" http://localhost:3001/api/addresses/23.23.176.127/associate?format=xml
+
+
+curl -v -X POST --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127/disassociate?format=xml
+
+curl -v -X DELETE --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127?format=xml
+
+Working with load balancers
+
+ curl -v --user "user:pass" http://localhost:3001/api/load_balancers?format=xml
+
+ curl -v -X POST --user "user:pass" -d "name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP&
+listener_balancer_port=80&listener_instance_port=3001" http://localhost:3001/api/load_balancers?format=xml
+
+ curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/register?format=xml
+
+ curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/unregister?format=xml
+
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/load_balancers/web-traffic-balancer
+
+Working with buckets
+
+curl -v --user "user:pass" http://localhost:3001/api/buckets/my_bucket?format=xml
+
+curl -v --user "user:pass" -X POST -d "name=shinynewbucket" http://localhost:3001/api/buckets?format=xml
+
+curl -v --user "user:pass" -H "content-type: image/jpg" -H 'X-Deltacloud-Blobmeta-Name:mariosblob' -H 'X-Deltacloud-Blobmeta-Author:me' --upload-file "/some/location/image.jpg" http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml
+
+ curl -v --user "user:pass" -X HEAD http://localhost:3001/api/buckets/shinynewbucket/newblob
+
+curl -v --user "user:pass" -X POST -H 'X-Deltacloud-Blobmeta-Name:mariosblobV2' -H 'X-Deltacloud-Blobmeta-Version:v2.1.1' http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml
+
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml
+
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/bucket/shinynewbucket
+
+
+Working with storage volumes
+
+curl -v --user "user:pass" http://localhost:3001/api/storage_volumes?format=xml
+
+curl -v --user "user:pass" -X POST -d "capacity=10&realm_id=us-east-1c" http://localhost:3001/api/storage_volumes?format=xml
+
+curl -v --user "user:pass" -X POST -d "instance_id=i-b100b3d0&device=/dev/sdi" http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach?format=xml
+
+curl -v --user "user:pass" -X POST http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach?format=xml
+
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_volumes/vol-0bc0de60?format=xml
+
+Working with storage snapshots
+
+curl -v --user "user:pass" http://localhost:3001/api/storage_snapshots/snap-45b8d024?format=xml
+
+curl -v --user "user:pass" -X POST -d "volume_id=vol-99fbe5f2" http://localhost:3001/api/storage_snapshots?format=xml
+
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_snapshots/snap-dda6cebc?format=xml
+
Modified: deltacloud/trunk/site/content/usage.md
URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/content/usage.md?rev=1371141&r1=1371140&r2=1371141&view=diff
==============================================================================
--- deltacloud/trunk/site/content/usage.md (original)
+++ deltacloud/trunk/site/content/usage.md Thu Aug 9 10:19:58 2012
@@ -1,4 +1,4 @@
----
+---
site_name: Deltacloud API
title: Usage
---
@@ -10,7 +10,7 @@ title: Usage
Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.
The Deltacloud Ruby Client
-You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
+You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
$ sudo gem install deltacloud-client
@@ -129,6 +129,12 @@ http://localhost:3001/api/buckets/mybuck
The '-iv' flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body).
Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API. @@ -144,7 +150,7 @@ As of version 0.9, libdeltacloud is most
-Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud. +Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
Libdeltacloud documentation Modified: deltacloud/trunk/site/output/command-tools.html URL: http://svn.apache.org/viewvc/deltacloud/trunk/site/output/command-tools.html?rev=1371141&r1=1371140&r2=1371141&view=diff ============================================================================== --- deltacloud/trunk/site/output/command-tools.html (original) +++ deltacloud/trunk/site/output/command-tools.html Thu Aug 9 10:19:58 2012 @@ -89,6 +89,17 @@The deltacloudc command line tool is being deprecated. For now the code making up deltacloudc has been moved to the /deltacloud/clients/console directory but will ultimately be removed from the repo. If the command line client is important to you then please let us know. A new command line client may be put onto the roadmap if there is demand for one.
+ +The deltacloud core developers use (almost exclusively) cURL as a command line client for working with a deltacloud server. You can find more information on working with cURL against deltacloud here.
+ +Installing the Deltacloud Ruby client also gives you the deltacloudc command line tool. This executable uses the Deltacloud client library to speak to the Deltacloud server through the REST API. This means that you can control your cloud infrastructure from the command line. The general usage pattern for deltacloudc is:
@@ -102,7 +113,7 @@
The cURL documentation is pretty comprehensive, but the following are some general points to remember for using cURL against Deltacloud. All the examples on this page assume the deltacloud server is running at localhost:3001:
+ ++curl -v -X DELETE --user "username:password" -H "Accept: application/xml" http://localhost:3001/api/keys/mykey ++
Display a complete list of instances in xml format:
+ +curl --user "user:pass" http://localhost:3001/api/instances?format=xml+ +
Alternatively and if you prefer you can manually specify the Accept header:
+ +curl --user "user:pass" -H "Accept: application/xml" http://localhost:3001/api/instances+ +
Launch an instance. Note that in this example parameters are specified as application/x-www-form-urlencoded through the use of the -d flag:
+ +curl -X POST --user "user:pass" -d "image_id=ami-84db39ed&hwp_id=m1.small&keyname=marios_key" http://localhost:3001/api/instances?format=xml+ +
Alternatively, you can use the -F flag to specify the parameters as multipart/form-data:
+ +curl -X POST --user "user:pass" -F "image_id=ami-84db39ed" -F "hwp_id=m1.small" -F "keyname=marios_key" http://localhost:3001/api/instances?format=xml+ +
Launch an instance action - reboot:
+ +curl -X POST --user "user:pass" http://localhost:3001/api/instances/reboot?format=xml+ +
Run command on an instance (where available):
+ +curl -X POST --user "user:pass" -F "cmd=uname -a; ls -l" -F "private_key=`cat /location/of/ssh/keyfile`" http://localhost:3001/api/instances/i-d77cd0ac/run?format=xml+ +
Get the details of a specific image:
+ +curl --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml+ +
Create an image from an existing instance (where available):
+ +curl -X POST --user "user:pass" -d "instance_id=i-d77cd0ac&name=mariostestimage" http://localhost:3001/api/images?format=xml+ +
Delete an image:
+ +curl -X DELETE --user "user:pass" http://localhost:3001/api/images/ami-3dc06a54?format=xml+ +
Get a list of all hardware profiles:
+ +curl --user "user:pass" http://localhost:3001/api/hardware_profiles?format=xml+ +
Get the details of a specific hardware profile:
+ +curl --user "user:pass" http://localhost:3001/api/hardware_profiles/m2.4xlarge?format=xml+ +
Get a list of all realms:
+ +curl --user "user:pass" http://localhost:3001/api/realms?format=xml+ +
Get the details of a specific realm:
+ +curl --user "user:pass" http://localhost:3001/api/realms/us-east-1a?format=xml+ +
Get a list of all keys:
+ +curl --user "user:pass" http://localhost:3001/api/keys?format=xml+ +
Create a new key (where available):
+ +curl -X POST --user "user:pass" -d "name=mynewkey" http://localhost:3001/api/keys?format=xml+ +
Import an existing key (where available):
+ +curl -X POST --user "user:pass" -F "name=mynewkey" -F "public_key=`cat /location/of/public/key/id_rsa.pub`" http://localhost:3001/api/keys?format=xml+ +
Delete a key:
+ +curl -X DELETE --user "user:pass" http://localhost:3001/api/keys/mynewkey?format=xml+ +
Get a list of all firewalls:
+ +curl -v --user "user:pass" http://localhost:3001/api/firewalls?format=xml+ +
Create a new firewall:
+ +curl -v -X POST --user "user:pass" -d "name=my_new_firewall&description=a test firewall" http://localhost:3001/api/firewalls?format=xml+ +
Create a new firewall rule - port 22 tcp, with one source firewall (group) and 2 IP addresses:
+ +curl -v -X POST --user "user:pass" -F "protocol=tcp" -F "port_from=22" -F "port_to=22" -F "group1=default" -F "group1owner=821108636519" -F "ip_address1=192.168.1.1/24" -F "ip_address2=65.128.31.27/32" http://localhost:3001/api/firewalls/my_new_firewall/rules+ +
Delete a firewall rule:
+ +curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall/821108636519~tcp~22~22~@group,821108636519,default,@address,ipv4,192.168.1.1,24,@address,ipv4,65.128.31.27,32?format=xml+ +
Delete a firewall:
+ +curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall?format=xml+ +
Get a list of all addresses:
+ +curl -v --user "user:pass" http://localhost:3001/api/addresses?format=xml+ +
Create a new address:
+ +curl -v --user "user:pass" -X POST http://localhost:3001/api/addresses?format=xml+ +
Associate an address with an instance:
+ +curl -v -X POST --user "user:pass" -d "instance_id=i-d77cd0ac" http://localhost:3001/api/addresses/23.23.176.127/associate?format=xml+ +
Disassociate an address from an instance:
+ +curl -v -X POST --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127/disassociate?format=xml+ +
Delete an address:
+ +curl -v -X DELETE --user "user:pass" http://localhost:3001/api/addresses/23.23.176.127?format=xml+ +
Get a list of all load balancers:
+ +curl -v --user "user:pass" http://localhost:3001/api/load_balancers?format=xml+ +
Create a load balancer:
+ +curl -v -X POST --user "user:pass" -d "name=webtraffic-balancer&realm_id=us-east-1c&listener_protocol=HTTP& +listener_balancer_port=80&listener_instance_port=3001" http://localhost:3001/api/load_balancers?format=xml+ +
Register an instance with a load balancer:
+ +curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/register?format=xml+ +
Unregister an instance from a load balancer:
+ +curl -v -X POST --user "user:pass" -d "instance_id=i-4f06b52e" http://localhost:3001/api/load_balancers/webtraffic-balancer/unregister?format=xml+ +
Delete a load balancer:
+ +curl -v --user "user:pass" -X DELETE http://localhost:3001/api/load_balancers/web-traffic-balancer+ +
Get the details of a bucket:
+ +curl -v --user "user:pass" http://localhost:3001/api/buckets/my_bucket?format=xml+ +
Create a new bucket:
+ +curl -v --user "user:pass" -X POST -d "name=shinynewbucket" http://localhost:3001/api/buckets?format=xml+ +
Create a new blob, specifying a content-type and some metadata:
+ +curl -v --user "user:pass" -H "content-type: image/jpg" -H 'X-Deltacloud-Blobmeta-Name:mariosblob' -H 'X-Deltacloud-Blobmeta-Author:me' --upload-file "/some/location/image.jpg" http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml+ +
Note that the --upload-file parameter above causes cURL to issue a HTTP PUT
+ +Get blob metadata:
+ +curl -v --user "user:pass" -X HEAD http://localhost:3001/api/buckets/shinynewbucket/newblob+ +
Note that blob metadata is returned in the HTTP response headers. So the use of the -v flag is important here or you will not see the metadata.
+ +Update blob metadata:
+ +curl -v --user "user:pass" -X POST -H 'X-Deltacloud-Blobmeta-Name:mariosblobV2' -H 'X-Deltacloud-Blobmeta-Version:v2.1.1' http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml+ +
Delete a blob:
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/buckets/shinynewbucket/newblob?format=xml+ +
Delete a bucket:
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/bucket/shinynewbucket+ +
Get a list of all storage volumes:
+ +curl -v --user "user:pass" http://localhost:3001/api/storage_volumes?format=xml+ +
Create a new storage volume:
+ +curl -v --user "user:pass" -X POST -d "capacity=10&realm_id=us-east-1c" http://localhost:3001/api/storage_volumes?format=xml+ +
Attach a volume to a running instance:
+ +curl -v --user "user:pass" -X POST -d "instance_id=i-b100b3d0&device=/dev/sdi" http://localhost:3001/api/storage_volumes/vol-0bc0de60/attach?format=xml+ +
Detach a volume (from whichever instance it is connected to):
+ +curl -v --user "user:pass" -X POST http://localhost:3001/api/storage_volumes/vol-0bc0de60/detach?format=xml+ +
Delete a storage volume:
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_volumes/vol-0bc0de60?format=xml+ +
Get details about a specific storage snapshot:
+curl -v --user "user:pass" http://localhost:3001/api/storage_snapshots/snap-45b8d024?format=xml+ +
Create a new storage snapshot:
+curl -v --user "user:pass" -X POST -d "volume_id=vol-99fbe5f2" http://localhost:3001/api/storage_snapshots?format=xml+ +
Delete a storage snapshot:
+curl -v --user "user:pass" -X DELETE http://localhost:3001/api/storage_snapshots/snap-dda6cebc?format=xml+ + + +
Instead of dealing with HTTP interface you can use various clients to communicate with Deltacloud server.
You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
+You need to install Ruby client seperately to the Deltacloud API server. Assuming you already have Ruby and RubyGems setup, you can install the Deltacloud client by simply typing:
$ sudo gem install deltacloud-client@@ -211,7 +211,10 @@ http://localhost:3001/api/buckets/mybuck The '-iv' flags will ensure that cURL displays the request and response headers (blob metadata are reported in the response headers with an empty response body). -
Libdeltacloud is a C/C++ library for accessing the Deltacloud API. It exports convenient structures and functions for manipulating cloud objects through the Deltacloud API.
@@ -226,7 +229,7 @@ As of version 0.9, libdeltacloud is most-Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud. +Due to the magic of libtool versioning, programs built against an older version of libdeltacloud will refuse to run against a newer version of libdeltacloud if the size of the structures has changed. If this happens, then the program must be recompiled against the newer libdeltacloud.
Libdeltacloud documentation