HardwareManager

class SoftLayer.managers.HardwareManager(client, ordering_manager=None)

Manage SoftLayer hardware servers.

Example:

# Initialize the Manager.
# 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.HardwareManager(client)

See product information here: https://www.ibm.com/cloud/bare-metal-servers

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.

__init__(client, ordering_manager=None)

Methods

__init__(client[, ordering_manager])
add_notification(hardware_id, user_id)	Create a user hardware notification entry
authorize_storage(hardware_id, username_storage)	Authorize File or Block Storage to a Hardware Server.
cancel_hardware(hardware_id[, reason, ...])	Cancels the specified dedicated server.
change_port_speed(hardware_id, public, speed)	Allows you to change the port speed of a server's NICs.
clear_vlan(hardware_id)	Clears all vlan trunks from a hardware_id
create_credential(template)	Create a password for a software component
edit(hardware_id[, userdata, hostname, ...])	Edit hostname, domain name, notes, user data of the hardware.
get_bandwidth_allocation(instance_id)	Combines getBandwidthAllotmentDetail() and getBillingCycleBandwidthUsage()
get_bandwidth_data(instance_id[, ...])	Gets bandwidth data for a server
get_cancellation_reasons()	Returns a dictionary of valid cancellation reasons.
get_components(hardware_id[, mask, ...])	Get details about a hardware components.
get_create_options([datacenter])	Returns valid options for ordering hardware.
get_hard_drives(instance_id)	Returns the hardware server hard drives.
get_hardware(hardware_id, **kwargs)	Get details about a hardware device.
get_hardware_fast(hardware_id)	Get details about a hardware device.
get_hardware_item_prices(location)	Returns the hardware server item prices by location.
get_instance(instance_id)	Get details about a hardware server instance.
get_maintenance_windows_detail(location_id)	Get the disks prices to be added or upgraded.
get_network_components(hardware_id[, mask, ...])	Calls SoftLayer_Hardware_Server::getNetworkComponents()
get_notifications(hardware_id)	Returns all hardware notifications.
get_sensors(hardware_id)	Returns Hardware sensor data
get_software_components(hardware_id)	Returns a piece of hardware’s installed software.
get_storage_credentials(instance_id)	Returns the hardware server storage credentials.
get_storage_details(instance_id, nas_type)	Returns the hardware server attached network storage.
get_tracking_id(instance_id)	Returns the Metric Tracking Object Id for a hardware server
list_hardware([tags, cpus, memory, ...])	List all hardware (servers and bare metal computing instances).
place_order(**kwargs)	Places an order for a piece of hardware.
reflash_firmware(hardware_id[, ipmi, ...])	Reflash hardware firmware.
reload(hardware_id[, post_uri, ssh_keys, lvm])	Perform an OS reload of a server with its current configuration.
remove_notification(identifier)	Remove a user hardware notification entry
remove_vlan(component_id, vlans)	Calls SoftLayer_Network_Component::removeNetworkVlanTrunks()
rescue(hardware_id)	Reboot a server into the a recsue kernel.
resolve_ids(identifier)	Takes a string and tries to resolve to a list of matching ids.
trunk_vlan(component_id, vlans)	Calls SoftLayer_Network_Component::addNetworkVlanTrunks()
update_firmware(hardware_id[, ipmi, ...])	Update hardware firmware.
upgrade(instance_id[, memory, nic_speed, ...])	Upgrades a hardware server instance.
verify_order(**kwargs)	Verifies an order for a piece of hardware.
wait_for_ready(instance_id[, limit, delay, ...])	Determine if a Server is ready.

Attributes

resolvers

add_notification(hardware_id, user_id)

Create a user hardware notification entry

authorize_storage(hardware_id, username_storage)

Authorize File or Block Storage to a Hardware Server.

Parameters:

• hardware_id (int) – Hardware server id.

• username_storage (string) – Storage username.

Returns:

bool.

cancel_hardware(hardware_id, reason='unneeded', comment='', immediate=False)

Cancels the specified dedicated server.

Example:

# Cancels hardware id 1234
result = mgr.cancel_hardware(hardware_id=1234)

Parameters:

• hardware_id (int) – The ID of the hardware to be cancelled.

• reason (string) – The reason code for the cancellation. This should come from get_cancellation_reasons().

• comment (string) – An optional comment to include with the cancellation.

• immediate (bool) – If set to True, will automatically update the cancelation ticket to request the resource be reclaimed asap. This request still has to be reviewed by a human

Returns:

True on success or an exception

change_port_speed(hardware_id, public, speed, redundant=None)

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

Parameters:

• hardware_id (int) – The ID of the server

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

Example:

#change the Public interface to 10Mbps on instance 12345
result = mgr.change_port_speed(hardware_id=12345,
                               public=True, speed=10)
# result will be True or an Exception

clear_vlan(hardware_id)

Clears all vlan trunks from a hardware_id

Parameters:

hardware_id (int) – server to clear vlans from

create_credential(template)

Create a password for a software component

edit(hardware_id, userdata=None, hostname=None, domain=None, notes=None, tags=None)

Edit hostname, domain name, notes, user data of the hardware.

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

Parameters:

• hardware_id (integer) – the instance ID to edit

• userdata (string) – user data on the hardware to edit. If none exist it will be created

• hostname (string) – valid hostname

• domain (string) – valid domain name

• notes (string) – notes about this particular hardware

• tags (string) – tags to set on the hardware as a comma separated list. Use the empty string to remove all tags.

Example:

# Change the hostname on instance 12345 to 'something'
result = mgr.edit(hardware_id=12345 , hostname="something")
#result will be True or an Exception

get_bandwidth_allocation(instance_id)

Combines getBandwidthAllotmentDetail() and getBillingCycleBandwidthUsage()

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

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_cancellation_reasons()

Returns a dictionary of valid cancellation reasons.

These can be used when cancelling a dedicated server via cancel_hardware().

get_components(hardware_id, mask=None, filter_component=None)

Get details about a hardware components.

Parameters:

hardware_id (int) – the instance ID

Returns:

A dictionary containing a large amount of information about the specified components.

get_create_options(datacenter=None)

Returns valid options for ordering hardware.

Parameters:

datacenter (string) – short name, like dal09

get_hard_drives(instance_id)

Returns the hardware server hard drives.

Parameters:

instance_id (int) – Id of the hardware server

get_hardware(hardware_id, **kwargs)

Get details about a hardware device.

Parameters:

id (integer) – the hardware ID

Returns:

A dictionary containing a large amount of information about the specified server.

Example:

object_mask = "mask[id,networkVlans[vlanNumber]]"
# Object masks are optional
result = mgr.get_hardware(hardware_id=1234,mask=object_mask)

get_hardware_fast(hardware_id)

Get details about a hardware device. Similar to get_hardware() but this uses threads

Parameters:

id (integer) – the hardware ID

Returns:

A dictionary containing a large amount of information about the specified server.

get_hardware_item_prices(location)

Returns the hardware server item prices by location.

Parameters:

location (string) – location to get the item prices.

get_instance(instance_id)

Get details about a hardware server instance.

Parameters:

instance_id (int) – the instance ID

Returns:

A dictionary containing a large amount of information about the specified instance.

get_maintenance_windows_detail(location_id)

Get the disks prices to be added or upgraded.

Parameters:

location_id (int) – Hardware Server location id.

Return int:

get_network_components(hardware_id, mask=None, space=None)

Calls SoftLayer_Hardware_Server::getNetworkComponents()

Parameters:

• hardware_id (int) – SoftLayer_Hardware_Server id

• mask (string) – The object mask to use if you do not want the default

• space (string) – ‘public’, ‘private’, or None for both.

Returns:

https://sldn.softlayer.com/reference/datatypes/SoftLayer_Network_Component/

get_notifications(hardware_id)

Returns all hardware notifications.

get_sensors(hardware_id)

Returns Hardware sensor data

get_software_components(hardware_id)

Returns a piece of hardware’s installed software.

get_storage_credentials(instance_id)

Returns the hardware server storage credentials.

Parameters:

instance_id (int) – Id of the hardware server

get_storage_details(instance_id, nas_type)

Returns the hardware server attached network storage.

Parameters:

• instance_id (int) – Id of the hardware server

• nas_type – storage type.

get_tracking_id(instance_id)

Returns the Metric Tracking Object Id for a hardware server

Parameters:

instance_id (int) – Id of the hardware server

list_hardware(tags=None, cpus=None, memory=None, hostname=None, domain=None, datacenter=None, nic_speed=None, owner=None, public_ip=None, private_ip=None, **kwargs)

List all hardware (servers and bare metal computing instances).

param list tags:

filter based on tags

param integer cpus:

filter based on number of CPUS

param integer memory:

filter based on amount of memory in gigabytes

param string hostname:

filter based on hostname

param string domain:

filter based on domain

param string datacenter:

filter based on datacenter

param integer nic_speed:

filter based on network speed (in MBPS)

param string public_ip:

filter based on public ip address

param string private_ip:

filter based on private ip address

param dict **kwargs:

response-level options (mask, limit, etc.)

returns:

Returns a list of dictionaries representing the matching hardware. This list will contain both dedicated servers and bare metal computing instances

Example:

# Using a custom object-mask. Will get ONLY what is specified
# These will stem from the SoftLayer_Hardware_Server datatype
object_mask = "mask[hostname,monitoringRobot[robotStatus]]"
result = mgr.list_hardware(mask=object_mask)

place_order(**kwargs)

Places an order for a piece of hardware.

See get_create_options() for valid arguments.

Parameters:

• size (string) – server size name or presetId

• hostname (string) – server hostname

• domain (string) – server domain name

• location (string) – location (datacenter) name

• os (string) – operating system name

• port_speed (int) – Port speed in Mbps

• ssh_keys (list) – list of ssh key ids

• post_uri (string) – The URI of the post-install script to run after reload

• hourly (boolean) – True if using hourly pricing (default). False for monthly.

• no_public (boolean) – True if this server should only have private interfaces

• extras (list) – List of extra feature names

reflash_firmware(hardware_id: int, ipmi: bool = True, raid_controller: bool = True, bios: bool = True)

Reflash hardware firmware.

This will cause the server to be unavailable for ~60 minutes. The firmware will not be upgraded but rather reflashed to the version installed. https://sldn.softlayer.com/reference/services/SoftLayer_Hardware_Server/createFirmwareReflashTransaction/

Parameters:

• hardware_id (int) – The ID of the hardware to have its firmware reflashed.

• ipmi (bool) – Reflash the ipmi firmware.

• raid_controller (bool) – Reflash the raid controller firmware.

• bios (bool) – Reflash the bios firmware.

Example:

# Check the servers active transactions to see progress
result = mgr.reflash_firmware(hardware_id=1234)

reload(hardware_id, post_uri=None, ssh_keys=None, lvm=False)

Perform an OS reload of a server with its current configuration.

https://sldn.softlayer.com/reference/datatypes/SoftLayer_Container_Hardware_Server_Configuration/ :param integer hardware_id: the instance ID to reload :param string post_uri: The URI of the post-install script to run after reload :param list ssh_keys: The SSH keys to add to the root user :param bool lvm: A flag indicating that the provision should use LVM for all logical drives.

remove_notification(identifier)

Remove a user hardware notification entry

remove_vlan(component_id, vlans)

Calls SoftLayer_Network_Component::removeNetworkVlanTrunks()

Parameters:

• component_id (int) – SoftLayer_Network_Component id

• vlans (list) – list of SoftLayer_Network_Vlan objects to remove. Each object needs at least id or vlanNumber

rescue(hardware_id)

Reboot a server into the a recsue kernel.

Parameters:

instance_id (integer) – the server ID to rescue

Example:

result = mgr.rescue(1234)

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:

trunk_vlan(component_id, vlans)

Calls SoftLayer_Network_Component::addNetworkVlanTrunks()

Parameters:

• component_id (int) – SoftLayer_Network_Component id

• vlans (list) – list of SoftLayer_Network_Vlan objects to add. Each object needs at least id or vlanNumber

update_firmware(hardware_id: int, ipmi: bool = True, raid_controller: bool = True, bios: bool = True, hard_drive: bool = True, network: bool = True)

Update hardware firmware.

This will cause the server to be unavailable for ~20 minutes. https://sldn.softlayer.com/reference/services/SoftLayer_Hardware_Server/createFirmwareUpdateTransaction/

Parameters:

• hardware_id (int) – The ID of the hardware to have its firmware updated.

• ipmi (bool) – Update the ipmi firmware.

• raid_controller (bool) – Update the raid controller firmware.

• bios (bool) – Update the bios firmware.

• hard_drive (bool) – Update the hard drive firmware.

• network (bool) – Update the network card firmware

Example:

# Check the servers active transactions to see progress
result = mgr.update_firmware(hardware_id=1234)

upgrade(instance_id, memory=None, nic_speed=None, drive_controller=None, public_bandwidth=None, disk=None, test=False)

Upgrades a hardware server instance.

Parameters:

• instance_id (int) – Instance id of the hardware server to be upgraded.

• memory (int) – Memory size.

• nic_speed (string) – Network Port Speed data.

• drive_controller (string) – Drive Controller data.

• public_bandwidth (int) – Public keyName data.

• disk (list) – List of disks to add or upgrade Hardware Server.

• test (bool) – Test option to verify the request.

Returns:

bool

verify_order(**kwargs)

Verifies an order for a piece of hardware.

See place_order() for a list of available options.

wait_for_ready(instance_id, limit=14400, delay=10, pending=False)

Determine if a Server is ready.

A server is ready when no transactions are running on it.

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.