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

For more information, please explore the Attic.


Keys

A key captures the credentials required to access an Instance. The Deltacloud API supports two main types of keys:

  • the password with username and password attributes
  • the key with fingerprint and pem (private key) attributes (public/private keypair)

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).


Get a list of all keys

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>

Get the description of a key

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>

Create a new 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>

Delete a 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

Firewalls