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