Create Server

Verb URI Description
POST /servers Create a new server

Normal Response Code(s): 202

Error Response Code(s): cloudServersFault (400, 500), serviceUnavailable (503), unauthorized (401), badMediaType(415), itemNotFound (404), badRequest (400), serverCapacityUnavailable (503), overLimit (413)

Status Transition: BUILD ACTIVE
BUILD ERROR (on error)

This operation asynchronously provisions a new server. The progress of this operation depends on several factors including location of the requested image, network i/o, host load, and the selected flavor. The progress of the request can be checked by performing a GET on /server/ id , which will return a progress attribute (0-100% completion).

A password will be randomly generated for you and returned in the response object. For security reasons, it will not be returned in subsequent GET calls against a given server ID.

Custom cloud server metadata can also be supplied at launch time. This metadata is stored in the API system where it is retrievable by querying the API for server status. The maximum size of the metadata key and value is each 255 bytes and the maximum number of key-value pairs that can be supplied per server is 5.

You may further customize a cloud server by injecting data into the file system of the cloud server itself. This is useful, for example, for inserting ssh keys, setting configuration files, or storing data that you want to retrieve from within the instance itself. It is intended to provide a minimal amount of launch-time personalization. If significant customization is required, a custom image should be created. The max size of the file p ath data is 255 bytes while the max size of the file contents is 10KB. Note that the file contents should be encoded as a Base64 string and the 10KB limit refers to the number of bytes in the decoded data not the number of characters in the encoded data. The maximum number of file path/content pairs that can be supplied is 5. Any existing files that match the specified file will be renamed to include the extension bak followed by a time stamp. For example, the file /etc/passwd will be backed up as /etc/passwd.bak.1246036261.5785 . All files will have root and the root group as owner and group owner, respectively and will allow user and group read access only ( -r--r----- ).

Servers in the same shared IP group can share public IPs for various high availability and load balancing configurations. To launch an HA server, include the optional sharedIpGroupId element and the server will be launched into that shared IP group.

If you intend to use a shared IP on the server being created and have no need for a separate public IP address, you may launch the server into a shared IP group and specify an IP address from that shared IP group to be used as its public IP. You can accomplish this by specifying the public shared IP address in your request. This is optional and is only valid if sharedIpGroupId is also supplied.

[Note]Note

sharedIpGroupId is an optional parameter and for optimal performance, should ONLY be specified when intending to share IPs between servers.

Example 4.3. Server Create Request: XML

<?xml version="1.0" encoding="UTF-8"?>

<server xmlns="http://docs.rackspacecloud.com/servers/api/v1.0"
	name="new-server-test" imageId="1" flavorId="1">
  <metadata>
    <meta key="My Server Name">Apache1</meta>
  </metadata>
  <personality>
    <file path="/etc/banner.txt">
        ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp
        dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k
        IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs
        c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g
        QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo
        ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv
        dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy
        c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6
        b25zLiINCg0KLVJpY2hhcmQgQmFjaA==
    </file>
  </personality>
</server>

Example 4.4. Server Create Request: JSON

{
    "server" : {
        "name" : "new-server-test",
        "imageId" : 1,
        "flavorId" : 1,
        "metadata" : {
            "My Server Name" : "Apache1" 
        },
        "personality" : [
            {
                "path" : "/etc/banner.txt",
                "contents" : "ICAgICAgDQoiQSBjbG91ZCBkb2VzIG5vdCBrbm93IHdoeSBp dCBtb3ZlcyBpbiBqdXN0IHN1Y2ggYSBkaXJlY3Rpb24gYW5k IGF0IHN1Y2ggYSBzcGVlZC4uLkl0IGZlZWxzIGFuIGltcHVs c2lvbi4uLnRoaXMgaXMgdGhlIHBsYWNlIHRvIGdvIG5vdy4g QnV0IHRoZSBza3kga25vd3MgdGhlIHJlYXNvbnMgYW5kIHRo ZSBwYXR0ZXJucyBiZWhpbmQgYWxsIGNsb3VkcywgYW5kIHlv dSB3aWxsIGtub3csIHRvbywgd2hlbiB5b3UgbGlmdCB5b3Vy c2VsZiBoaWdoIGVub3VnaCB0byBzZWUgYmV5b25kIGhvcml6 b25zLiINCg0KLVJpY2hhcmQgQmFjaA==" 
            } 
        ] 
    }
}

Example 4.5. Server Create Response: XML

<?xml version="1.0" encoding="UTF-8"?>

<server xmlns="http://docs.rackspacecloud.com/servers/api/v1.0"
	id="1235" name="new-server-test" 
	imageId="1" flavorId="1"
	hostId="e4d909c290d0fb1ca068ffaddf22cbd0"
	progress="0" status="BUILD"
	adminPass="GFf1j9aP">
  <metadata>
    <meta key="My Server Name">Apache1</meta>
  </metadata>
  <addresses>
    <public>
      <ip addr="67.23.10.138"/>
    </public>
    <private>
      <ip addr="10.176.42.19"/>
    </private>
  </addresses>
</server>

Example 4.6. Server Create Response: JSON

{
   "server" : {
     "id" : 1235,
       "name" : "new-server-test",
       "imageId" : 1,
       "flavorId" : 1,
       "hostId" : "e4d909c290d0fb1ca068ffaddf22cbd0",
       "progress" : 0,
       "status" : "BUILD",
       "adminPass" : "GFf1j9aP",
        "metadata" : {
            "My Server Name" : "Apache1" 
        },
        "addresses" : {
            "public" : [
                "67.23.10.138"
            ],
            "private" : [
                "10.176.42.19"
            ] 
        }
   }
}

Legal notices