A key captures the credentials required to access an Instance. The Deltacloud API supports two main types of keys:
The key type is determined by the back-end cloud provider.
Some cloud providers require the specification of the credentials used for connecting to an instance as a parameter for instance creation. For example, the Amazon EC2 cloud uses key type of keys; the identifier of the key used with a given instance is supplied within the keyname parameter to the POST /api/instances call (see the Create an instance section).
Other cloud providers report the instance credentials in response to instance creation and make them available for subsequent retrieval. For example, the Gogrid Cloud uses the password type of keys.
The Rackspace cloud also reports credentials during instance creation though it does not provide a mechanism with which to retrieve those passwords thereafter).
To get a list of all available keys use call GET /api/keys. The example below shows keys from the Amazon EC2 cloud (key type). The XML response does not contain the private key attribute. It is because EC2 only provides the private key once, when the key is created (see the Create/delete a key section).
Example request:
GET /api/keys?format=xml HTTP/1.1 Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) Host: localhost:3001 Accept: */*
Server response:
HTTP/1.1 200 OK
Content-Type: application/xml
Date: Tue, 26 Jul 2011 08:09:26 GMT
Content-Length: 733
<?xml version='1.0' encoding='utf-8' ?>
<keys>
<key href='http://localhost:3001/api/keys/deltacloud_jsmith' id='deltacloud_jsmith' type='key'>
<actions>
<link href='http://localhost:3001/api/keys/deltacloud_jsmith' method='delete' rel='destroy' />
</actions>
<fingerprint>38:93:81:11:83:c2:c7:27:e8:79:17:e2:08:c9:13:99:73:90:8e:cc</fingerprint>
<state>AVAILABLE</state>
</key>
<key href='http://localhost:3001/api/keys/the_key' id='the_key' type='key'>
<actions>
<link href='http://localhost:3001/api/keys/the_key' method='delete' rel='destroy' />
</actions>
<fingerprint>39:d3:9b:bb:93:92:97:27:e9:7d:b7:e2:09:9d:b3:dd:73:d0:9e:99</fingerprint>
<state>AVAILABLE</state>
</key>
</keys>
To get the XML description for a specific key use call GET /api/keys/:id. The example below shows a password type of key from the Gogrid cloud:
Example request:
GET /api/keys/72398?format=xml HTTP/1.1 Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== User-Agent: curl/7.21.2 (x86_64-apple-darwin10.3.1) Host: localhost:3001 Accept: */*
Server response:
HTTP/1.1 200 OK
Content-Type: application/xml
Date: Tue, 26 Jul 2011 11:13:25 GMT
Content-Length: 269
<?xml version='1.0' encoding='utf-8' ?>
<key href='http://localhost:3001/api/keys/72398' id='72398' type='password'>
<actions>
</actions>
<username><![CDATA[26648]]></username>
<password><![CDATA[3woc7UWdJsJEcm8@]]></password>
<state></state>
</key>
To create a new key use call POST /api/keys. Some back-end cloud providers allow a client to create new credentials for accessing instances. The parameters (key attributes) required by this function will depend on the back-end cloud provider and are specified in the relevant driver. At present, only the Amazon EC2 cloud implements a key creation method. The method requires to specify the key name as a parameter.
Note that the private key attribute of a newly created key is reported only once, in response to the create operation (see the example below). The client should save the private key for following use with instance authentication. In all subsequent calls, the Deltacloud server response displays only the fingerprint attribute, as illustrated in the Get a list of all keys section.
As with other HTTP POST calls in the Deltacloud REST API, client requests may specify the required parameters as multipart/form-data, or using the application/x-www-form-urlencoded content type.
Example request:
POST /api/keys?format=xml HTTP/1.1 Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) Host: localhost:3001 Accept: */* Content-Length: 19 Content-Type: application/x-www-form-urlencoded name=jsmith_new_key
Server response:
HTTP/1.1 201 Created
Content-Type: application/xml
Date: Tue, 26 Jul 2011 10:58:58 GMT
Content-Length: 2062
<?xml version='1.0' encoding='utf-8' ?>
<key href='http://localhost:3001/api/keys/jsmith_new_key' id='jsmith_new_key' type='key'>
<actions>
<link href='http://localhost:3001/api/keys/jsmith_new_key' method='delete' rel='destroy' />
</actions>
<fingerprint>c6:80:5c:0a:b8:66:0d:58:5a:bf:0f:c2:5d:35:d3:c7:49:f3:5a:5f</fingerprint>
<pem>
<![CDATA[-----BEGIN RSA PRIVATE KEY-----
MIIEpgIBAAKCAQEAsPIzLQEpoLkxd0WESPEWQ4AMn9e0T6jHIMl/a2GUx2TA2Q10n6i5h4VAXXrK
m9fNnPJhw1uRbuL7Oz57QSftGUfz05EaLOsvIEq3OXA0HqnFPF7Dd4yvy07KfgNHe2c26NqIqxgw
GCy6tfd/9iKQIlFCG8I/M6fgEG/vw30GP5EywYLS0J7lYfNHJAVAznjX0LoOWvT0zYajZ7gWJ30/
sQ/IFaKxC3BpT6K2aQP+RgAimALHinFuoT4+07SsrQXEezLemAG/gdbw3+7DL9BGq0CCoY1RxeC7
qNh9BJwHtq9QPYg/RKruiYak/TSoB71/VP67lJv0WEkCRJKEFpz5SQIDAQABAoIBAQChVyZcmdvI
JjS5aVSWYeWIBMD+GmPZ4q428iPR2LcdHHxPLVqyndkVfeXTlrwZX6umuMd1pw+zyRmEypL+NRaW
36mutnbkkEl3K0loASw07V3fjxSx9EDyo1Q1lG3gUpuZtHG7eCGaWWahtxwhZSCBehBKWVLhmefP
dRFs8Zn56LhfxByS/HcmHYddq1ggynFgg1DszYKTiJ0k5Zd/w4gh3GXH02S50cNFumJh9tbZNeDz
yqa6a12N21loZ/VRRL7lEjpf3K2n0DCQ5pp0I9/FiwuwHMWr6qPSsQt9N/XclNiVg7fz+btNsqVY
US1kBkvazoaANmF3VOXT9bmiFnuBAoGBAOkURD2uBe9UUl7xvWON7yS+tBcs1KyYDsTEhsS5dLdk
n73/5vyEVzozdywTR7lQWVQhWWwkK/FJd9Xo/VV5bGXl+MK/JxIQHrEhLzO1OeYEBiw2eKhigyDb
lm7pk/DuBNqgnA9YVnSvRYjpnvgBeb89CHvdhqn52GcbB2ShXurRAoGBAMJYyqNyl8CiIqesigts
tlRk0UmS/LS6I58f7nbcrkgO3ZDsYhXhj9aKSJx56bpWTwoFdl7nTSUwkFgq2ts3g7EPQbYD/5G6
kwpq0tvC23zZTfYvjExNVORh9PJBCrBl1tC/5nqYSrHC7H3Ys/SW3DF+0LPTdOtx5FwL5Utr3lT5
AoGBAM3Y8EvpHaS5O+ZOaY07FTHGmxa8qTelM6XkS4ICqGovnEUZdM8fskncmit6+6VWqQ38RhWT
/Jsk34k0NEkA7BMyf/i/CaqSQgj93co1C+VxOGJj2TwdhOHIDZv2/omSLQdJQYrr4a87/JVmftdZ
tkSHiq6afwwvdEfbPzRIsKOBAoGBAK5EjEAP6z+So1yS/J3N95ipZnmA0hUErBhtu5jdvXFj0w22
ySUxw5bvHLkjIJA0AF/OEhx7b9OfPm+wzdqwZugH9DZQU4TLNjqrGzRv//xtptjQPg/Vb//yToBE
Dl+qkftReEwJ70CCtykJfiQeeofvXRlCzZ6p28kl6Y+9w/mRAoGBANI8AGB1iUDMQDiEfTAuH7jB
nZTZUsfAaysoku3gyVmtcu1Zo7T02b8YW3ypuNu664KO7eNik9q68yKa7oDuLVrVj6Sh2DInoeW9
vbjp2KcyMVEPHzWh86LV9IY5oHjQxlK/PMhQWMEeysi6j2qFqrx2rqRhG6kZUcFHFoHQpmv2
-----END RSA PRIVATE KEY-----]]>
</pem>
<state>AVAILABLE</state>
</key>
To delete a key, specified by its :id attribute, use call DELETE /api/keys/:id. As well as the create operation, this feature is currently only available in the Amazon EC2 driver.
Example request:
DELETE /api/keys/jsmith_new_key?format=xml HTTP/1.1 Authorization: Basic AU1J3UB2121Afd1DdyQWxLaTYTmJMNF4zTXBoRGdhMDh2RUw5ZDAN9zVXVa== User-Agent: curl/7.20.1 (i386-redhat-linux-gnu) Host: localhost:3001 Accept: */*
Server response:
HTTP/1.1 204 No Content Date: Tue, 26 Jul 2011 10:18:38 GMT