Virtual
SoftLayer_Virtual_Guest::createObject

Overview

createObject() enables the creation of computing instances on an account. This
method is a simplified alternative to interacting with the ordering system directly.

In order to create a computing instance, a template object must be sent in with a few required
values.

When this method returns an order will have been placed for a computing instance of the specified configuration.

To determine when the instance is available you can poll the instance via getObject, with an object mask requesting the provisionDate relational property. When provisionDate is not null, the instance will be ready.

Warning: Computing instances created via this method will incur charges on your account. For testing input parameters see generateOrderTemplate.

Input - SoftLayer_Virtual_Guest

  • hostname
    Hostname for the computing instance.
    • Required
    • Type - string

  • domain
    Domain for the computing instance.
    • Required
    • Type - string

  • startCpus
    The number of CPU cores to allocate.

  • maxMemory
    The amount of memory to allocate in megabytes.

  • datacenter.name
    Specifies which datacenter the instance is to be provisioned in.
    Example
    { 
        "datacenter": { 
            "name": "dal05" 
        } 
    }

  • hourlyBillingFlag
    Specifies the billing type for the instance.
    • Required
    • Type - boolean
    • When true the computing instance will be billed on hourly usage, otherwise it will be billed on a monthly basis.

  • localDiskFlag
    Specifies the disk type for the instance.
    • Required
    • Type - boolean
    • When true the disks for the computing instance will be provisioned on the host which it runs, otherwise SAN disks will be provisioned.

  • dedicatedAccountHostOnlyFlag
    Specifies whether or not the instance must only run on hosts with instances from the same account
    • Optional
    • Type - boolean
    • Default - false
    • When true this flag specifies that a compute instance is to run on hosts that only have guests from the same account.

  • operatingSystemReferenceCode
    An identifier for the operating system to provision the computing instance with.
    • Conditionally required - Disallowed when blockDeviceTemplateGroup.globalIdentifier is provided, as the template will specify the operating system.
    • Type - string
    • Notice - Some operating systems are charged based on the value specified in startCpus. The price which is used can be determined by calling generateOrderTemplate with your desired device specifications.
    • See getCreateObjectOptions for available options.

  • blockDeviceTemplateGroup.globalIdentifier
    A global identifier for the template to be used to provision the computing instance.
    • Conditionally required - Disallowed when operatingSystemReferenceCode is provided, as the template will specify the operating system.
    • Type - string
    • Notice - Some operating systems are charged based on the value specified in startCpus. The price which is used can be determined by calling generateOrderTemplate with your desired device specifications.
    • Both public and non-public images may be specified.
    • A list of public images may be obtained via a request to getPublicImages.
    • A list of non-public images, images owned by an account or specifically shared with an account, may be obtained via a request to getBlockDeviceTemplateGroups.
    Example
    { 
        "blockDeviceTemplateGroup": { 
            "globalIdentifier": "07beadaa-1e11-476e-a188-3f7795feb9fb" 
        } 
    }

  • networkComponents.maxSpeed
    Specifies the connection speed for the instance's network components.
    • Optional
    • Type - int
    • Default - 10
    • Description - The networkComponents property is an array with a single network component structure. The maxSpeed property must be set to specify the network uplink speed, in megabits per second, of the computing instance.
    • See getCreateObjectOptions for available options.
    Example
    { 
        "networkComponents": [ 
            { 
                "maxSpeed": 1000 
            } 
        ] 
    }

  • privateNetworkOnlyFlag
    Specifies whether or not the instance only has access to the private network
    • Optional
    • Type - boolean
    • Default - false
    • When true this flag specifies that a compute instance is to only have access to the private network.

  • primaryNetworkComponent.networkVlan.id
    Specifies the network vlan which is to be used for the frontend interface of the computing instance.
    • Optional
    • Type - int
    • Description - The primaryNetworkComponent property is a network component structure with the networkVlan property populated with a vlan structure. The id property must be set to specify the frontend network vlan of the computing instance.
    Example
    { 
        "primaryNetworkComponent": { 
            "networkVlan": { 
                "id": 1 
            } 
        } 
    }

  • primaryBackendNetworkComponent.networkVlan.id
    Specifies the network vlan which is to be used for the backend interface of the computing instance.
    • Optional
    • Type - int
    • Description - The primaryBackendNetworkComponent property is a network component structure with the networkVlan property populated with a vlan structure. The id property must be set to specify the backend network vlan of the computing instance.
    Example
    { 
        "primaryBackendNetworkComponent": { 
            "networkVlan": { 
                "id": 2 
            } 
        } 
    }

  • blockDevices
    Block device and disk image settings for the computing instance
    • Optional
    • Type - array of [[SoftLayer_Virtual_Guest_Block_Device (type)|SoftLayer_Virtual_Guest_Block_Device]
    • Default - The smallest available capacity for the primary disk will be used. If an image template is specified the disk capacity will be be provided by the template.
    • Description - The blockDevices property is an array of block device structures.
    • Each block device must specify the device property along with the diskImage property, which is a disk image structure with the capacity property set.
    • The device number '1' is reserved for the SWAP disk attached to the computing instance.
    • See getCreateObjectOptions for available options.
    Example
    { 
        "blockDevices": [ 
            { 
                "device": "0", 
                "diskImage": { 
                    "capacity": 100 
                } 
            } 
        ], 
        "localDiskFlag": true 
    }

  • userData.value
    Arbitrary data to be made available to the computing instance.
    • Optional
    • Type - string
    • Description - The userData property is an array with a single attribute structure with the value property set to an arbitrary value.
    • This value can be retrieved via the getUserMetadata method from a request originating from the computing instance. This is primarily useful for providing data to software that may be on the instance and configured to execute upon first boot.
    Example
    { 
        "userData": [ 
            { 
                "value": "someValue" 
            } 
        ] 
    }

  • sshKeys
    SSH keys to install on the computing instance upon provisioning.
    Example
    { 
        "sshKeys": [ 
            { 
                "id": 123 
            } 
        ] 
    }

  • postInstallScriptUri
    Specifies the uri location of the script to be downloaded and run after installation is complete.
    • Optional
    • Type - string

REST Example

Request
curl -X POST -d '{ 
 "parameters":[ 
     { 
         "hostname": "host1", 
         "domain": "example.com", 
         "startCpus": 1, 
         "maxMemory": 1024, 
         "hourlyBillingFlag": true, 
         "localDiskFlag": true, 
         "operatingSystemReferenceCode": "UBUNTU_LATEST" 
     } 
 ] 
}' https://api.softlayer.com/rest/v3/SoftLayer_Virtual_Guest.json 
Response
HTTP/1.1 201 Created 
Location: https://api.softlayer.com/rest/v3/SoftLayer_Virtual_Guest/1301396/getObject 
 
 
{ 
    "accountId": 232298, 
    "createDate": "2012-11-30T16:28:17-06:00", 
    "dedicatedAccountHostOnlyFlag": false, 
    "domain": "example.com", 
    "hostname": "host1", 
    "id": 1301396, 
    "lastPowerStateId": null, 
    "lastVerifiedDate": null, 
    "maxCpu": 1, 
    "maxCpuUnits": "CORE", 
    "maxMemory": 1024, 
    "metricPollDate": null, 
    "modifyDate": null, 
    "privateNetworkOnlyFlag": false, 
    "startCpus": 1, 
    "statusId": 1001, 
    "globalIdentifier": "2d203774-0ee1-49f5-9599-6ef67358dd31" 
} 

Parameters

templateObject

SoftLayer_Virtual_Guest

The SoftLayer_Virtual_Guest object that you wish to create.

Headers

SoftLayer_Virtual_GuestObjectMask, SoftLayer_ObjectMask
authenticate

Associated Methods

SoftLayer_Virtual_Guest::createObjects
SoftLayer_Virtual_Guest::generateOrderTemplate
SoftLayer_Virtual_Guest::getCreateObjectOptions