smartdc.datacenter Module

class smartdc.datacenter.DataCenter(location=None, key_id=None, secret='~/.ssh/id_rsa', headers=None, login=None, known_locations=None, allow_agent=False, verify=True, verbose=None)

Basic connection object that makes all API requests.

The smartdc.datacenter.DataCenter is the basic connection unit with the CloudAPI, and it maintains the data it requires for further requests. It lazily updates some internal data as and when the user requests it, and only accesses the REST API on method calls (never on attribute access).

A smartdc.datacenter.DataCenter object may be instantiated without any parameters, but practically speaking, the key_id and secret parameters are necessary before any meaningful requests may be made.

Parameters:

• location (basestring) – SmartDC API’s hostname
• key_id (basestring) – SmartDC identifier for the ssh key
• secret (str) – path to private rsa key (default: ‘~/.ssh/id_rsa’)
• headers (dict) – headers inserted upon every request
• login (basestring) – user path in SmartDC
• known_locations (dict) – keys-to-URLs mapping used by location
• allow_agent (bool) – whether or not to try ssh-agent
• verify (bool) – whether or not to verify server SSL certificates
• verbose (bool) – whether or not to print request URLs to stderr, overrides config

The location is notionally a hostname, but it may be expressed as an FQDN, one of the keys to the known_locations dict, or, as a fallback, a bare hostname as prefix to the API_HOST_SUFFIX. The default location is ‘us-west-1’, because that is where ‘api.joyentcloud.com’ redirects to at the time of writing.

The known_locations dict allows for custom access to a private cloud.

Attributes:

Variables:

• location – location of the machine
• known_locations – dict of known locations for this cluster of datacenters
• login – user path in the SmartDC

add_key(key_id, key)

POST /:login/keys

Parameters:

• key_id (basestring) – label for the new key
• key (str) – the full SSH RSA public key

Uploads a public key to be added to the account’s credentials.

api()

GET /

Returns :a programmatically-generated API summary using HTTP verbs and URL templates Return type:dict

authenticate(key_id=None, secret=None, allow_agent=False)

Parameters:

• key_id (basestring) – SmartDC identifier for the ssh key
• secret (basestring) – path to private rsa key
• allow_agent (bool) – whether or not to try ssh-agent

If no key_id or secret were entered on initialization, or there is a need to change the existing authentication credentials, one may authenticate with a key_id and secret.

base_url

Protocol + hostname

create_machine(name=None, package=None, dataset=None, metadata=None, tags=None, boot_script=None, credentials=False, image=None, networks=None)

POST /:login/machines

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.

Parameters:

• name (basestring) – a human-readable label for the machine
• package (basestring or dict) – cluster of resource values identified by name
• image (basestring or dict) – an identifier for the base operating system image (formerly a dataset)
• dataset (basestring or dict) – base operating system image identified by a globally unique ID or URN (deprecated)
• metadata (dict) – keys & values with arbitrary supplementary details for the machine, accessible from the machine itself
• tags (dict) – keys & values with arbitrary supplementary identifying information for filtering when querying for machines
• networks (list) – list of networks where this machine will belong to
• boot_script (basestring as file path) – path to a file to upload for execution on boot

Return type:

smartdc.machine.Machine

If package, image, or dataset are passed a dict containing a name key (in the case of package) or an id key (in the case of image or dataset), it passes the corresponding value. The server API appears to resolve incomplete or ambiguous dataset URNs with the highest version number.

datacenter(name)

Parameters:name (basestring) – location key Returns :a new DataCenter object

This method treats the ‘name’ argument as a location key (on the known_locations attribute dict) or FQDN, and keeps existing authentication and other configuration from this object.

datacenters()

GET /:login/datacenters

Returns :all datacenters (mapping from short location key to full URL) that this cloud is aware of Return type:dict

This method also updates the local known_locations attribute based upon this information.

dataset(identifier)

GET /:login/datasets/:id

Parameters:identifier (basestring or dict) – unique ID or URN for a dataset Return type:dict

Gets a single dataset identified by the unique ID or URN. URNs are also prefix-matched. If passed a dict that contains an urn or id key, it uses the respective value as the identifier.

datasets(search=None, fields=('description', 'urn'))

GET /:login/datasets

Parameters:

• search (basestring that compiles as a regular expression) – optionally filter (locally) with a regular expression search on the listed fields
• fields (list of basestrings) – filter on the listed fields (defaulting to description and urn)

Returns :

datasets (operating system templates) available in this datacenter

Return type:

list of dicts

default_package()

GET /:login/packages

Returns :the default package for this datacenter Return type:dict or None

Requests all the packages in this datacenter, filters for the default, and returns the corresponding dict, if a default has been defined.

delete_key(key_id)

DELETE /:login/keys/:key

Parameters:key_id (basestring) – identifier for an individual key record for the account

Deletes an SSH key from the server identified by key_id.

image(identifier)

GET /:login/images/:id

Parameters:identifier (basestring or dict) – match on the listed image identifier Returns :the details of the given image matching the identifier Return type:dict

A string or a dictionary containing an id key may be passed in.

images(name=None, os=None, version=None)

GET /:login/images

Parameters:

• name (basestring) – match on the listed name
• os (basestring) – match on the selected os
• version (basestring) – match on the selected version

Returns :

available machine images in this datacenter

Return type:

list of dicts

key(key_id)

GET /:login/keys/:key

Parameters:key_id (basestring) – identifier for an individual key record for the account Returns:details of the key Return type:dict

keys()

GET /:login/keys

Returns :all public keys on record for the authenticated account. Return type:list of dicts

machine(machine_id, credentials=False)

GET /:login/machines/:id

Parameters:machine_id (basestring) – unique identifier for a machine to be found in the datacenter Return type:smartdc.machine.Machine

machines(machine_type=None, name=None, dataset=None, state=None, memory=None, tombstone=None, tags=None, credentials=False, paged=False, limit=None, offset=None)

GET /:login/machines

Query for machines in the current DataCenter matching the input criteria, returning a list of instantiated smartdc.machine.Machine objects.

Parameters:

• machine_type (basestring) – virtualmachine or smartmachine
• name (basestring) – machine name to find (will make the return list size 1 or 0)
• dataset (basestring or dict) – unique ID or URN for a dataset
• state (basestring) – current running state
• memory (int) – current size of the RAM deployed for the machine (Mb)
• tombstone (int) – include machines destroyed in the last N minutes
• tags (dict) – keys and values to query in the machines’ tag space
• credentials (bool) – whether to include the generated credentials for machines, if present
• paged (bool) – whether to return in pages
• limit (int) – return N machines
• offset (int) – get the next limit of machines starting at this point

Return type:

list of smartdc.machine.Machines

The limit and offset are the REST API’s raw paging mechanism. Alternatively, one can let paged remain False, and let the method call attempt to collect all of the machines in multiple calls.

me()

GET /:login

Returns :basic information about the authenticated account Return type:dict

network(identifier)

GET /:login/networks/:id

Parameters:identifier (basestring or dict) – match on the listed network identifier Returns :characteristics of the requested network Return type:dict

Either a string or a dictionary with an id key may be passed in.

networks(search=None, fields='name, ')

GET /:login/networks

Parameters:

• search (basestring that compiles as a regular expression) – optionally filter (locally) with a regular expression search on the listed fields
• fields (list of basestrings) – filter on the listed fields (defaulting to name)

Returns :

network available in this datacenter

Return type:

list of dicts

num_machines(machine_type=None, dataset=None, state=None, memory=None, tombstone=None, tags=None)

HEAD /:login/machines

Counts the number of machines total, or that match the predicates as with machines().

Parameters:

• machine_type (basestring) – virtualmachine or smartmachine
• dataset (basestring or dict) – unique ID or URN for a dataset
• state (basestring) – current running state
• memory (int) – current size of the RAM deployed for the machine (Mb)
• tombstone (int) – include machines destroyed in the last N minutes
• tags (dict) – keys and values to query in the machines’ tag space

Returns :

a count of the number of machines (matching the predicates) owned by the user at this datacenter

Return type:

int

package(name)

GET /:login/packages/:package

Parameters:name – the name identifying the package Return type:dict

Gets a dict representing resource values for a package by name. If passed a dict containing a name key, it uses the corresponding value.

packages(name=None, memory=None, disk=None, swap=None, version=None, vcpus=None, group=None)

GET /:login/packages

Parameters:

• name (basestring) – the label associated with the resource package
• memory (int) – amount of RAM (in MiB) that the package provisions
• disk (int) – amount of disk storage (in MiB) the package provisions
• swap (int) – amount of swap (in MiB) the package provisions
• version (basestring) – the version identifier associated with the package
• vcpus (int) – the number of virtual CPUs provisioned with the package
• group (basestring) – the group to which the package belongs

Returns :

packages (machine “sizes”, with resource types and values) available in this datacenter.

Return type:

list of dicts

raw_machine_data(machine_id, credentials=False)

GET /:login/machines/:machine

Parameters:

• machine_id (basestring or dict) – identifier for the machine instance
• credentials (bool) – whether the SDC should return machine credentials

Return type:

dict

Primarily used internally to get a raw dict for a single machine.

request(method, path, headers=None, data=None, **kwargs)

(Primarily) internal method for making all requests to the datacenter.

Parameters:

• method (str) – HTTP verb
• path (str) – path relative to login path
• headers (dict) – additional headers to send

Returns :

tuple of decoded response body & Response object

Raises :

client (4xx) errors

url

Base URL for SmartDC requests