VSManager
- class SoftLayer.managers.VSManager(client, ordering_manager=None)[source]
Manages SoftLayer Virtual Servers.
See product information here: https://www.ibm.com/cloud/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.
Methods
__init__
(client[, ordering_manager])add_notification
(virtual_id, user_id)Create a user virtual notification entry
attach_portable_storage
(vs_id, portable_id)Attach portal storage to a Virtual Server.
authorize_storage
(vs_id, username_storage)Authorize File or Block Storage to a Virtual Server.
browser_access_log
(identifier)A virtual guest’s browser access logs.
cancel_instance
(instance_id)Cancel an instance immediately, deleting all its data.
capture
(instance_id, name[, ...])Capture one or all disks from a VS to a SoftLayer image.
change_port_speed
(instance_id, public, speed)Allows you to change the port speed of a virtual server's NICs.
create_instance
(**kwargs)Creates a new virtual server instance.
create_instances
(config_list)Creates multiple virtual server instances.
edit
(instance_id[, userdata, hostname, ...])Edit hostname, domain name, notes, and/or the user data of a VS.
get_bandwidth_allocation
(instance_id)Combines getBandwidthAllotmentDetail() and getBillingCycleBandwidthUsage()
get_bandwidth_data
(instance_id[, ...])Gets bandwidth data for a server
get_create_options
([vsi_type, datacenter])Retrieves the available options for creating a VS.
Uses Product_Package::getItemPrices to get all disk items with its categories and
get_instance
(instance_id, **kwargs)Get details about a virtual server instance.
get_local_disks
(instance_id)Returns the virtual server local disks.
get_notifications
(vs_id)Returns all virtual notifications.
get_portable_storage
(instance_id)Returns the virtual server portable storage.
get_storage_credentials
(instance_id)Returns the virtual server storage credentials.
get_storage_details
(instance_id, nas_type)Returns the virtual server attached network storage.
get_summary_data_usage
(instance_id[, ...])Retrieve the usage information of a virtual server.
get_tracking_id
(instance_id)Returns the Metric Tracking Object Id for a hardware server
list_instances
([hourly, monthly, tags, ...])Retrieve a list of all virtual servers on the account.
migrate
(instance_id)Calls SoftLayer_Virtual_Guest::migrate
migrate_dedicated
(instance_id, host_id)Calls SoftLayer_Virtual_Guest::migrate
order_guest
(guest_object[, test])Uses Product_Order::placeOrder to create a virtual guest.
reload_instance
(instance_id[, post_uri, ...])Perform an OS reload of an instance.
remove_notification
(identifier)Remove a user vs notification entry
rescue
(instance_id)Reboot a VSI into the Xen recsue kernel.
resolve_ids
(identifier)Takes a string and tries to resolve to a list of matching ids.
set_tags
(tags, guest_id)Sets tags on a guest with a retry decorator
upgrade
(instance_id[, cpus, memory, ...])Upgrades a VS instance.
verify_create_instance
(**kwargs)Verifies an instance creation command.
wait_for_ready
(instance_id[, limit, delay, ...])Determine if a VS is ready and available.
wait_for_transaction
(instance_id, limit[, delay])Waits on a VS transaction for the specified amount of time.
Attributes
resolvers
- attach_portable_storage(vs_id, portable_id)[source]
Attach portal storage to a Virtual Server.
- Parameters:
vs_id (int) – Virtual server id.
portable_id (int) – Portal storage id.
- Returns:
SoftLayer_Provisioning_Version1_Transaction.
- authorize_storage(vs_id, username_storage)[source]
Authorize File or Block Storage to a Virtual Server.
- Parameters:
vs_id (int) – Virtual server id.
username_storage (string) – Storage username.
- Returns:
bool.
- browser_access_log(identifier)[source]
A virtual guest’s browser access logs.
- Parameters:
identifier (int) – Virtual server id.
- Returns:
SoftLayer_Virtual_BrowserConsoleAccessLog.
- 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(vsi_type='PUBLIC_CLOUD_SERVER', datacenter=None)[source]
Retrieves the available options for creating a VS.
- Parameters:
vsi_type (string) – vs keyName.
datacenter (string) – short name, like dal09
- Returns:
A dictionary of creation options.
Example:
# Prints out the create option dictionary options = mgr.get_create_options() print(options)
- get_disk_category_id_by_disk_number(capacity, disk_number)[source]
Uses Product_Package::getItemPrices to get all disk items with its categories and
disk_key_names dictionary to convert disk numbers (int) to ordinal numbers (string)
- 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_local_disks(instance_id)[source]
Returns the virtual server local disks.
- Parameters:
instance_id (int) – Id of the virtual server
- get_portable_storage(instance_id)[source]
Returns the virtual server portable storage.
- Parameters:
instance_id (int) – Id of the virtual server
- get_storage_credentials(instance_id)[source]
Returns the virtual server storage credentials.
- Parameters:
instance_id (int) – Id of the virtual server
- get_storage_details(instance_id, nas_type)[source]
Returns the virtual server attached network storage.
- Parameters:
instance_id (int) – Id of the virtual server
nas_type – storage type.
- 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
valid_type (string 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
- migrate(instance_id)[source]
Calls SoftLayer_Virtual_Guest::migrate
Only actually does anything if the virtual server requires a migration. Will return an exception otherwise.
- Parameters:
instance_id (int) – Id of the virtual server
- migrate_dedicated(instance_id, host_id)[source]
Calls SoftLayer_Virtual_Guest::migrate
Only actually does anything if the virtual server requires a migration. Will return an exception otherwise.
- Parameters:
instance_id (int) – Id of the virtual server
- 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, disk=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.