SoftLayer.vs

VS Manager/helpers

license:MIT, see LICENSE for more details.
class SoftLayer.managers.vs.VSManager(client, ordering_manager=None)[source]

Manages SoftLayer Virtual Servers.

See product information here: http://www.softlayer.com/virtual-servers

Example:

# Initialize the VSManager.
# env variables. These can also be specified in ~/.softlayer,
# or passed directly to SoftLayer.Client()
# SL_USERNAME = YOUR_USERNAME
# SL_API_KEY = YOUR_API_KEY
import SoftLayer
client = SoftLayer.Client()
mgr = SoftLayer.VSManager(client)
Parameters:
  • client (SoftLayer.API.BaseClient) – the client instance
  • ordering_manager (SoftLayer.managers.OrderingManager) – an optional manager to handle ordering. If none is provided, one will be auto initialized.
cancel_instance(instance_id)[source]

Cancel an instance immediately, deleting all its data.

Parameters:instance_id (integer) – the instance ID to cancel

Example:

# Cancels instance 12345
mgr.cancel_instance(12345)
capture(instance_id, name, additional_disks=False, notes=None)[source]

Capture one or all disks from a VS to a SoftLayer image.

Parameters set to None will be ignored and not attempted to be updated.

Parameters:
  • instance_id (integer) – the instance ID to edit
  • name (string) – name assigned to the image
  • additional_disks (bool) – set to true to include all additional attached storage devices
  • notes (string) – notes about this particular image
Returns:

dictionary – information about the capture transaction.

Example::
name = “Testing Images” notes = “Some notes about this image” result = mgr.capture(instance_id=12345, name=name, notes=notes)
change_port_speed(instance_id, public, speed)[source]

Allows you to change the port speed of a virtual server’s NICs.

Example:

#change the Public interface to 10Mbps on instance 12345
result = mgr.change_port_speed(instance_id=12345,
                            public=True, speed=10)
# result will be True or an Exception
Parameters:
  • instance_id (int) – The ID of the VS
  • public (bool) – Flag to indicate which interface to change. True (default) means the public interface. False indicates the private interface.
  • speed (int) – The port speed to set.

Warning

A port speed of 0 will disable the interface.

create_instance(**kwargs)[source]

Creates a new virtual server instance.

Warning

This will add charges to your account

Example:

new_vsi = {
    'domain': u'test01.labs.sftlyr.ws',
    'hostname': u'minion05',
    'datacenter': u'hkg02',
    'flavor': 'BL1_1X2X100'
    'dedicated': False,
    'private': False,
    'os_code' : u'UBUNTU_LATEST',
    'hourly': True,
    'ssh_keys': [1234],
    'disks': ('100','25'),
    'local_disk': True,
    'tags': 'test, pleaseCancel',
    'public_security_groups': [12, 15]
}

vsi = mgr.create_instance(**new_vsi)
# vsi will have the newly created vsi details if done properly.
print vsi
Parameters:
  • cpus (int) – The number of virtual CPUs to include in the instance.
  • memory (int) – The amount of RAM to order.
  • hourly (bool) – Flag to indicate if this server should be billed hourly (default) or monthly.
  • hostname (string) – The hostname to use for the new server.
  • domain (string) – The domain to use for the new server.
  • local_disk (bool) – Flag to indicate if this should be a local disk (default) or a SAN disk.
  • datacenter (string) – The short name of the data center in which the VS should reside.
  • os_code (string) – The operating system to use. Cannot be specified if image_id is specified.
  • image_id (int) – The GUID of the image to load onto the server. Cannot be specified if os_code is specified.
  • dedicated (bool) – Flag to indicate if this should be housed on adedicated or shared host (default). This will incur a fee on your account.
  • public_vlan (int) – The ID of the public VLAN on which you want this VS placed.
  • public_security_groups (list) – The list of security group IDs to apply to the public interface
  • private_security_groups (list) – The list of security group IDs to apply to the private interface
  • private_vlan (int) – The ID of the private VLAN on which you want this VS placed.
  • disks (list) – A list of disk capacities for this server.
  • post_uri (string) – The URI of the post-install script to run after reload
  • private (bool) – If true, the VS will be provisioned only with access to the private network. Defaults to false
  • ssh_keys (list) – The SSH keys to add to the root user
  • nic_speed (int) – The port speed to set
  • tags (string) – tags to set on the VS as a comma separated list
  • flavor (string) – The key name of the public virtual server flavor being ordered.
  • host_id (int) – The host id of a dedicated host to provision a dedicated host virtual server on.
create_instances(config_list)[source]

Creates multiple virtual server instances.

This takes a list of dictionaries using the same arguments as create_instance().

Warning

This will add charges to your account

Example:

# Define the instance we want to create.
new_vsi = {
    'domain': u'test01.labs.sftlyr.ws',
    'hostname': u'minion05',
    'datacenter': u'hkg02',
    'flavor': 'BL1_1X2X100'
    'dedicated': False,
    'private': False,
    'os_code' : u'UBUNTU_LATEST',
    'hourly': True,
    'ssh_keys': [1234],
    'disks': ('100','25'),
    'local_disk': True,
    'tags': 'test, pleaseCancel',
    'public_security_groups': [12, 15]
}

# using .copy() so we can make changes to individual nodes
instances = [new_vsi.copy(), new_vsi.copy(), new_vsi.copy()]

# give each its own hostname, not required.
instances[0]['hostname'] = "multi-test01"
instances[1]['hostname'] = "multi-test02"
instances[2]['hostname'] = "multi-test03"

vsi = mgr.create_instances(config_list=instances)
#vsi will be a dictionary of all the new virtual servers
print vsi
edit(instance_id, userdata=None, hostname=None, domain=None, notes=None, tags=None)[source]

Edit hostname, domain name, notes, and/or the user data of a VS.

Parameters set to None will be ignored and not attempted to be updated.

Parameters:
  • instance_id (integer) – the instance ID to edit
  • userdata (string) – user data on VS to edit. If none exist it will be created
  • hostname (string) – valid hostname
  • domain (string) – valid domain namem
  • notes (string) – notes about this particular VS
  • tags (string) – tags to set on the VS as a comma separated list. Use the empty string to remove all tags.
Returns:

bool – True or an Exception

Example::
# Change the hostname on instance 12345 to ‘something’ result = mgr.edit(instance_id=12345 , hostname=”something”) #result will be True or an Exception
get_bandwidth_allocation(instance_id)[source]

Combines getBandwidthAllotmentDetail() and getBillingCycleBandwidthUsage()

get_bandwidth_data(instance_id, start_date=None, end_date=None, direction=None, rollup=3600)[source]

Gets bandwidth data for a server

Will get averaged bandwidth data for a given time period. If you use a rollup over 3600 be aware that the API will bump your start/end date to align with how data is stored. For example if you have a rollup of 86400 your start_date will be bumped to 00:00. If you are not using a time in the start/end date fields, this won’t really matter.

Parameters:
  • instance_id (int) – Hardware Id to get data for
  • start_date (date) – Date to start pulling data for.
  • end_date (date) – Date to finish pulling data for
  • direction (string) – Can be either ‘public’, ‘private’, or None for both.
  • rollup (int) – 300, 600, 1800, 3600, 43200 or 86400 seconds to average data over.
get_create_options()[source]

Retrieves the available options for creating a VS.

Returns:A dictionary of creation options.

Example:

# Prints out the create option dictionary
options = mgr.get_create_options()
print(options)
get_instance(instance_id, **kwargs)[source]

Get details about a virtual server instance.

Parameters:instance_id (integer) – the instance ID
Returns:A dictionary containing a large amount of information about the specified instance.

Example:

# Print out instance ID 12345.
vsi = mgr.get_instance(12345)
print vsi

# Print out only FQDN and primaryIP for instance 12345
object_mask = "mask[fullyQualifiedDomainName,primaryIpAddress]"
vsi = mgr.get_instance(12345, mask=mask)
print vsi
get_summary_data_usage(instance_id, start_date=None, end_date=None, valid_type=None, summary_period=None)[source]

Retrieve the usage information of a virtual server.

Parameters:
  • instance_id (string) – a string identifier used to resolve ids
  • start_date (string) – the start data to retrieve the vs usage information
  • end_date (string) – the start data to retrieve the vs usage information
  • string valid_type (string) – the Metric_Data_Type keyName.
  • summary_period (int) – summary period.
get_tracking_id(instance_id)[source]

Returns the Metric Tracking Object Id for a hardware server

Parameters:instance_id (int) – Id of the hardware server
list_instances(hourly=True, monthly=True, tags=None, cpus=None, memory=None, hostname=None, domain=None, local_disk=None, datacenter=None, nic_speed=None, public_ip=None, private_ip=None, transient=None, **kwargs)[source]

Retrieve a list of all virtual servers on the account.

Example:

# Print out a list of hourly instances in the DAL05 data center.

for vsi in mgr.list_instances(hourly=True, datacenter='dal05'):
   print vsi['fullyQualifiedDomainName'], vsi['primaryIpAddress']

# Using a custom object-mask. Will get ONLY what is specified
object_mask = "mask[hostname,monitoringRobot[robotStatus]]"
for vsi in mgr.list_instances(mask=object_mask,hourly=True):
    print vsi
Parameters:
  • hourly (boolean) – include hourly instances
  • monthly (boolean) – include monthly instances
  • tags (list) – filter based on list of tags
  • cpus (integer) – filter based on number of CPUS
  • memory (integer) – filter based on amount of memory
  • hostname (string) – filter based on hostname
  • domain (string) – filter based on domain
  • local_disk (string) – filter based on local_disk
  • datacenter (string) – filter based on datacenter
  • nic_speed (integer) – filter based on network speed (in MBPS)
  • public_ip (string) – filter based on public ip address
  • private_ip (string) – filter based on private ip address
  • transient (boolean) – filter on transient or non-transient instances
  • **kwargs (dict) – response-level options (mask, limit, etc.)
Returns:

Returns a list of dictionaries representing the matching virtual servers

order_guest(guest_object, test=False)[source]

Uses Product_Order::placeOrder to create a virtual guest.

Useful when creating a virtual guest with options not supported by Virtual_Guest::createObject specifically ipv6 support.

Parameters:guest_object (dictionary) – See SoftLayer.CLI.virt.create._parse_create_args

Example:

new_vsi = {
    'domain': u'test01.labs.sftlyr.ws',
    'hostname': u'minion05',
    'datacenter': u'hkg02',
    'flavor': 'BL1_1X2X100'
    'dedicated': False,
    'private': False,
    'transient': False,
    'os_code' : u'UBUNTU_LATEST',
    'hourly': True,
    'ssh_keys': [1234],
    'disks': ('100','25'),
    'local_disk': True,
    'tags': 'test, pleaseCancel',
    'public_security_groups': [12, 15],
    'ipv6': True
}

vsi = mgr.order_guest(new_vsi)
# vsi will have the newly created vsi receipt.
# vsi['orderDetails']['virtualGuests'] will be an array of created Guests
print vsi
reload_instance(instance_id, post_uri=None, ssh_keys=None, image_id=None)[source]

Perform an OS reload of an instance.

Parameters:
  • instance_id (integer) – the instance ID to reload
  • post_url (string) – The URI of the post-install script to run after reload
  • ssh_keys (list) – The SSH keys to add to the root user
  • image_id (int) – The GUID of the image to load onto the server

Warning

This will reformat the primary drive. Post-provision script MUST be HTTPS for it to be executed.

Example:

# Reload instance ID 12345 then run a custom post-provision script.
# Post-provision script MUST be HTTPS for it to be executed.
post_uri = 'https://somehost.com/bootstrap.sh'
vsi = mgr.reload_instance(12345, post_uri=post_url)
rescue(instance_id)[source]

Reboot a VSI into the Xen recsue kernel.

Parameters:instance_id (integer) – the instance ID to rescue
Returns:bool – True or an Exception
Example::
# Puts instance 12345 into rescue mode result = mgr.rescue(instance_id=12345)
resolve_ids(identifier)

Takes a string and tries to resolve to a list of matching ids.

What exactly ‘identifier’ can be depends on the resolvers

Parameters:identifier (string) – identifying string
Returns list:
set_tags(tags, guest_id)[source]

Sets tags on a guest with a retry decorator

Just calls guest.setTags, but if it fails from an APIError will retry

upgrade(instance_id, cpus=None, memory=None, nic_speed=None, public=True, preset=None)[source]

Upgrades a VS instance.

Example:

# Upgrade instance 12345 to 4 CPUs and 4 GB of memory
import SoftLayer
client = SoftLayer.create_client_from_env()
mgr = SoftLayer.VSManager(client)
mgr.upgrade(12345, cpus=4, memory=4)
Parameters:
  • instance_id (int) – Instance id of the VS to be upgraded
  • cpus (int) – The number of virtual CPUs to upgrade to of a VS instance.
  • preset (string) – preset assigned to the vsi
  • memory (int) – RAM of the VS to be upgraded to.
  • nic_speed (int) – The port speed to set
  • public (bool) – CPU will be in Private/Public Node.
Returns:

bool

verify_create_instance(**kwargs)[source]

Verifies an instance creation command.

Without actually placing an order. See create_instance() for a list of available options.

Example:

new_vsi = {
    'domain': u'test01.labs.sftlyr.ws',
    'hostname': u'minion05',
    'datacenter': u'hkg02',
    'flavor': 'BL1_1X2X100'
    'dedicated': False,
    'private': False,
    'transient': False,
    'os_code' : u'UBUNTU_LATEST',
    'hourly': True,
    'ssh_keys': [1234],
    'disks': ('100','25'),
    'local_disk': True,
    'tags': 'test, pleaseCancel',
    'public_security_groups': [12, 15]
}

vsi = mgr.verify_create_instance(**new_vsi)
# vsi will be a SoftLayer_Container_Product_Order_Virtual_Guest
# if your order is correct. Otherwise you will get an exception
print vsi
wait_for_ready(instance_id, limit=3600, delay=10, pending=False)[source]

Determine if a VS is ready and available.

In some cases though, that can mean that no transactions are running. The default arguments imply a VS is operational and ready for use by having network connectivity and remote access is available. Setting pending=True will ensure future API calls against this instance will not error due to pending transactions such as OS Reloads and cancellations.

Parameters:
  • instance_id (int) – The instance ID with the pending transaction
  • limit (int) – The maximum amount of seconds to wait.
  • delay (int) – The number of seconds to sleep before checks. Defaults to 10.
  • pending (bool) – Wait for pending transactions not related to provisioning or reloads such as monitoring.

Example:

# Will return once vsi 12345 is ready, or after 10 checks
ready = mgr.wait_for_ready(12345, 10)
wait_for_transaction(instance_id, limit, delay=10)[source]

Waits on a VS transaction for the specified amount of time.

This is really just a wrapper for wait_for_ready(pending=True). Provided for backwards compatibility.

Parameters:
  • instance_id (int) – The instance ID with the pending transaction
  • limit (int) – The maximum amount of time to wait.
  • delay (int) – The number of seconds to sleep before checks. Defaults to 10.