smartdc.machine Module

class smartdc.machine.Machine(datacenter, machine_id=None, data=None, credentials=False)

A local proxy representing the state of a remote CloudAPI machine.

A smartdc.machine.Machine object is intended to be a convenient container for methods and data relevant to a remotely running compute node managed by CloudAPI. A smartdc.machine.Machine is tied to a smartdc.datacenter.DataCenter object, and makes all its requests via that interface. It does not attempt to manage the state cache in most cases, instead requiring the user to explicitly update with a refresh() call.

Parameters:
  • datacenter (smartdc.datacenter.DataCenter) – datacenter that contains this machine
  • machine_id (basestring) – unique ID of the machine
  • data (dict) – raw data for instantiation
  • credentials (bool) – whether credentials should be returned

Typically, a smartdc.machine.Machine object is instantiated automatically by a smartdc.datacenter.DataCenter object, but a user may instantiate one with a minimum of a datacenter parameter and a unique ID according to the machine. The object then pulls in the machine data from the datacenter API. If data is passed in to instantiate, then ingest the dict and populate internal values from that.

All of the following attributes are read-only:

Variables:
  • name – human-readable label for the machine
  • id – identifier for the machine
  • type – type (smartmachine or virtualmachine) of the machine
  • state – last-known state of the machine
  • dataset – the machine template
  • memory – the RAM (MiB) allocated for the machine (int)
  • disk – the persistent storage (MiB) allocated for the machine (int)
  • ipslist of IPv4 addresses for the machine
  • metadatadict of user-generated attributes for the machine
  • createddatetime.datetime of machine creation time
  • updateddatetime.datetime of machine update time
datacenter = None

the smartdc.datacenter.DataCenter object that holds this machine

path

Convenience property to insert the id into a relative path for requests.

public_ips

Filter through known IP addresses for the machine to return a list of public IPs.

private_ips

Filter through known IP addresses for the machine to return a list of private IPs.

ips

If IPs are not immediately available, then re-GET the resource.

classmethod create_in_datacenter(datacenter, **kwargs)
POST /:login/machines

Class method, provided as a convenience.

Parameters:datacenter (smartdc.datacenter.DataCenter) – datacenter for creating the machine

Provision a machine in the current smartdc.datacenter.DataCenter, returning an instantiated smartdc.machine.Machine object. All of the parameter values are optional, as they are assigned default values by the Datacenter’s API itself.

‘datacenter’ is the only required argument. The rest of the arguments are passed to the DataCenter object as with smartdc.datacenter.DataCenter.create_machine().

refresh(credentials=False)
GET /:login/machines/:id
Parameters:credentials (bool) – whether to return machine passwords

Fetch the existing state and values for the smartdc.machine.Machine from the datacenter and commit the values locally.

credentials()
GET /:login/machines/:id?credentials=True
Returns :known login-password pairs for the machine
Return type:dict

Provisionally re-fetch the machine information with the credentials flag enabled.

status()
GET /:login/machines/:id
Returns :the current machine state
Return type:basestring

Refresh the machine’s information by fetching it remotely, then returning the state as a string.

stop()
POST /:login/machines/:id?action=stop

Initiate shutdown of the remote machine.

start()
POST /:login/machines/:id?action=start

Initiate boot of the remote machine.

reboot()
POST /:login/machines/:id?action=reboot

Initiate reboot of the remote machine.

resize(package)
POST /:login/machines/:id?action=resize

Initiate resizing of the remote machine to a new package.

delete()
DELETE /:login/machines/:id

Initiate deletion of a stopped remote machine.

poll_until(state, interval=2)
GET /:login/machines/:id
Parameters:
  • state (basestring) – target state
  • interval (int) – pause in seconds between polls

Convenience method that continuously polls the current state of the machine remotely, and returns until the named state argument is reached. The default wait interval between requests is 2 seconds, but it may be changed.

Note

If the next state is wrongly identified, this method may loop forever.

poll_while(state, interval=2)
GET /:login/machines/:id
Parameters:
  • state (basestring) – (assumed) current state
  • interval (int) – pause in seconds between polls

Convenience method that continuously polls the current state of the machine remotely, and returns while the machine has the named state argument. Once the state changes, the method returns. The default wait interval between requests is 2 seconds, but it may be changed.

Note

If a state transition has not correctly been triggered, this method may loop forever.

get_metadata()
GET /:login/machines/:id/metadata
Returns :machine metadata
Return type:dict

Fetch and return the metadata dict for the machine. The method refreshes the locally cached copy of the metadata kept in the metadata attribute and returns it.

update_metadata(**kwargs)
POST /:login/machines/:id/metadata
Returns :current metadata
Return type:dict

Send an metadata dict update for the machine (following dict.update() semantics) using the keys and values passed in the keyword arguments. The method also refreshes the locally cached copy of the metadata kept in the metadata attribute and returns it.

delete_metadata_at_key(key)
DELETE /:login/machines/:id/metadata/:key
Parameters:key (basestring) – identifier for matadata entry
Returns :current metadata
Return type:dict

Deletes the machine metadata contained at ‘key’. Also explicitly requests and returns the machine metadata so that the local copy stays synchronized.

set_boot_script(filename)
POST /:login/machines/:id/metadata
Parameters:filename (basestring) – file path to the script to be uploaded and executed at boot on the machine

Replace the existing boot script for the machine with the data in the named file.

Note

The SMF service that runs the boot script will kill processes that exceed 60 seconds execution time, so this is not necessarily the best vehicle for long pkgin installations, for example.

delete_boot_script()
DELETE /:login/machines/:id/metadata/user-script

Deletes any existing boot script on the machine.

delete_all_metadata()
DELETE /:login/machines/:id/metadata
Returns :current metadata
Return type:empty dict

Deletes all the metadata stored for this machine. Also explicitly requests and returns the machine metadata so that the local copy stays synchronized.

get_tags()
GET /:login/machines/:id/tags
Returns :complete set of tags for this machine
Return type:dict

A local copy is not kept because these are essentially search keys.

add_tags(**kwargs)
POST /:login/machines/:id/tags

Appends the tags (expressed as arbitrary keyword arguments) to those already set for the machine.

get_tag(tag)
GET /:login/machines/:id/tags/:tag
Returns :the value for a single tag
Return type:basestring
delete_tag(tag)
DELETE /:login/machines/:id/tags/:tag

Delete a tag and its corresponding value on the machine.

delete_all_tags()
DELETE /:login/machines/:id/tags

Delete all tags and their corresponding values on the machine.

raw_snapshot_data(name)
GET /:login/machines/:id/snapshots/:name
Parameters:name (basestring) – identifier for snapshot
Return type:dict

Used internally to get a raw dict of a single machine snapshot.

snapshots()
GET /:login/machines/:id/snapshots
Return type:list of smartdc.machine.Snapshot

Lists all snapshots for the Machine.

create_snapshot(name)
POST /:login/machines/:id/snapshots
Parameters:name (basestring) – identifier for snapshot
Return type:smartdc.machine.Snapshot

Create a snapshot for this machine’s current state with the given name.

start_from_snapshot(name)
POST /:login/machines/:id/snapshots/:name
Parameters:name (basestring) – identifier for snapshot

Start the machine from the snapshot with the given ‘name’.

snapshot(name)
GET /:login/machines/:id/snapshots/:name
Parameters:name (basestring) – identifier for snapshot
Return type:smartdc.machine.Snapshot

Return a snapshot that already exists for the machine, identified by name.

class smartdc.machine.Snapshot(machine, name=None, data=None)

A local proxy representing the current state of a machine snapshot.

A smartdc.machine.Snapshot object is intended to be a convenient container for a snapshot’s state and for performing methods on it.

Parameters:
  • machine (smartdc.machine.Machine) – source of the snapshot
  • name (basestring) – identifier for snapshot
  • data (dict) – raw data for instantiation

Typically, a smartdc.machine.Snapshot object is instantiated automatically by creating or listing snapshots for a smartdc.machine.Machine. However, a snapshot may be manually instantiated by giving a ‘machine’ and a ‘name’ as parameters, and the snapshot’s state and other data will be queried from the server.

The following attributes are read-only:

Variables:
  • name – human-readable label for the machine
  • state – last-known state of the machine
  • createddatetime.datetime of machine creation time
  • updateddatetime.datetime of machine update time
machine = None

smartdc.machine.Machine object that contains this snapshot

path

Convenience property to insert the id into a relative path for requests.

refresh()
GET /:login/machines/:id/snapshots/:name

Fetch the existing state and values for the snapshot and commit the values locally.

status()
GET /:login/machines/:id/snapshots/:name
Returns :the current state
Return type:basestring

Refresh the snapshot’s information by fetching it remotely, then returning the state as a string.

delete()
DELETE /:login/machines/:id/snapshots/:name

Deletes the snapshot from the machine.

start()
POST /:login/machines/:id/snapshots/:name
Returns :self

Initiate boot of the machine from this snapshot.

Previous topic

smartdc.datacenter Module

Next topic

smartdc.legacy Module

This Page