2015/07/20 - Apache Deltacloud has been retired.

For more information, please explore the Attic.

Working with cURL as a command line client

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:

  • Credentials are specified with --user "name:password"
  • Request headers are specified with -H "header: value" . For the "Accept" header Deltacloud offers a convenient way of specifying the desired response format; you can include the "?format=" parameter into the request URL rather than setting the Accept header
  • HTTP verbs are specified with -X VERB
  • The -i flag will show you the response headers and the -v flag will show you request and response headers as well as info about cURL activity:
    curl -v -X DELETE --user "username:password" -H "Accept: application/xml" http://localhost:3001/api/keys/mykey

Working with instances

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 

Working with images

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 

Working with hardware profiles

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 

Working with realms

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 

Working with keys

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 

Working with firewalls

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=" -F "ip_address2=" 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,,24,@address,ipv4,,32?format=xml 

Delete a firewall:

curl -v -X DELETE --user "user:pass" http://localhost:3001/api/firewalls/marios_test_firewall?format=xml 

Working with addresses

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/ 

Disassociate an address from an instance:

curl -v -X POST --user "user:pass" http://localhost:3001/api/addresses/  

Delete an address:

curl -v -X DELETE --user "user:pass" http://localhost:3001/api/addresses/  

Working with load balancers

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

Working with buckets

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

Working with storage volumes

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

Working with storage snapshots

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