createObject


SoftLayer_Virtual_Guest::createObject

Create a new computing instance

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 [[SoftLayer_Virtual_Guest/getObject|getObject]], with an [[Extended-Object-Masks|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 [[SoftLayer_Virtual_Guest/generateOrderTemplate|generateOrderTemplate]].

Input - [[SoftLayer_Virtual_Guest (type)|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.
    • Required
    • Type - int
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|getCreateObjectOptions]] for available options.

  • maxMemory
    The amount of memory to allocate in megabytes.
    • Required
    • Type - int
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|getCreateObjectOptions]] for available options.

  • datacenter.name
    Specifies which datacenter the instance is to be provisioned in.
    • Required
    • Type - string
    • The datacenter property is a [[SoftLayer_Location (type)|location]] structure with the name field set.
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|getCreateObjectOptions]] for available options.
    { “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 [[SoftLayer_Virtual_Guest/generateOrderTemplate|generateOrderTemplate]] with your desired device specifications.
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|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 [[SoftLayer_Virtual_Guest/generateOrderTemplate|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 [[SoftLayer_Virtual_Guest_Block_Device_Template_Group/getPublicImages|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 [[SoftLayer_Account/getBlockDeviceTemplateGroups|getBlockDeviceTemplateGroups]].
    { “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 [[SoftLayer_Virtual_Guest_Network_Component (type)|network component]] structure. The maxSpeed property must be set to specify the network uplink speed, in megabits per second, of the computing instance.
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|getCreateObjectOptions]] for available options.
    { “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 [[SoftLayer_Virtual_Guest_Network_Component (type)|network component]] structure with the networkVlan property populated with a [[SoftLayer_Network_Vlan (type)|vlan]] structure. The id property must be set to specify the frontend network vlan of the computing instance.
    { “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 [[SoftLayer_Virtual_Guest_Network_Component (type)|network component]] structure with the networkVlan property populated with a [[SoftLayer_Network_Vlan (type)|vlan]] structure. The id property must be set to specify the backend network vlan of the computing instance.
    { “primaryBackendNetworkComponent”: { “networkVlan”: { “id”: 2 } } }
  • primaryNetworkComponent.securityGroupBindings
    Specifies the security groups to be attached to this VSI’s Frontend Network Adapter
    • Optional
    • Type - array of [[SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding (type)| SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding]] with the securityGroup property set.
    • Description - The primaryNetworkComponent property is a [[SoftLayer_Virtual_Guest_Network_Component (type)|network component]] structure with the securityGroupBindings property populated with an array of [[SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding (type)|Security Group Order Binding]] structures. The securityGroup property in each must be set to specify the security group to be attached to the primary frontend network component.
    { “primaryNetworkComponent”: { “securityGroupBindings”: [ { “securityGroup”: { “id”: 1 } }, { “securityGroup”: { “id”: 2 } } ] } }
  • primaryBackendNetworkComponent.securityGroupBindings
    Specifies the security groups to be attached to this VSI’s Backend Network Adapter
    • Optional
    • Type - array of [[SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding (type)| SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding]] with the securityGroup property set.
    • Description - The primaryBackendNetworkComponent property is a [[SoftLayer_Virtual_Guest_Network_Component (type)|network component]] structure with the securityGroupBindings property populated with an array of [[SoftLayer_Virtual_Network_SecurityGroup_NetworkComponentBinding (type)|Security Group Order Binding]] structures. The securityGroup property in each must be set to specify the security group to be attached to the primary backend network component.
    { “primaryBackendNetworkComponent”: { “securityGroupBindings”: [ { “securityGroup”: { “id”: 1 } }, { “securityGroup”: { “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 [[SoftLayer_Virtual_Guest_Block_Device (type)|block device]] structures.
    • Each block device must specify the device property along with the diskImage property, which is a [[SoftLayer_Virtual_Disk_Image (type)|disk image]] structure with the capacity property set.
    • The device number ‘1’ is reserved for the SWAP disk attached to the computing instance.
    • See [[SoftLayer_Virtual_Guest/getCreateObjectOptions|getCreateObjectOptions]] for available options.
    { “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 [[SoftLayer_Virtual_Guest_Attribute (type)|attribute]] structure with the value property set to an arbitrary value.
    • This value can be retrieved via the [[SoftLayer_Resource_Metadata/getUserMetadata|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.
    { “userData”: [ { “value”: “someValue” } ] }
  • sshKeys
    SSH keys to install on the computing instance upon provisioning.
    • Optional
    • Type - array of [[SoftLayer_Security_Ssh_Key (type)|SoftLayer_Security_Ssh_Key]]
    • Description - The sshKeys property is an array of [[SoftLayer_Security_Ssh_Key (type)|SSH Key]] structures with the id property set to the value of an existing SSH key.
    • To create a new SSH key, call [[SoftLayer_Security_Ssh_Key/createObject|createObject]] on the [[SoftLayer_Security_Ssh_Key]] service.
    • To obtain a list of existing SSH keys, call [[SoftLayer_Account/getSshKeys|getSshKeys]] on the [[SoftLayer_Account]] service.
    { “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

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

Name Type Description
templateObject SoftLayer_Virtual_Guest The SoftLayer_Virtual_Guest object that you wish to create.

Required Headers

  • authenticate

Optional Headers

  • SoftLayer_Virtual_GuestObjectMask
  • SoftLayer_ObjectMask

Return Values

SoftLayer_Virtual_Guest

associatedMethods


/reference/services/SoftLayer_Virtual_Guest/createObject/