Developer Interfaces

This part of the documentation covers all the interfaces of vmt-connect.

Main Module
Security Module
- Classes
  - Credential
Utility Module

class vmtconnect.Connection(host=None, username=None, password=None, auth=None, base_url=None, req_versions=None, disable_hateoas=True, ssl=True, verify=False, cert=None, headers=None, use_session=True, proxies=None)

Turbonomic instance connection class

The primary API interface. In addition to the noted method parameters, each method also supports a per call fetch_all flag, as well as a pager flag. Each of these override the connection global property, and will be safely ignored if the endpoint does not support, or does not require paging the results. Additionally, you may pass requests.Request keyword arguments to each call if required (e.g. timeout). Care should be taken, as some parameters will break vmt-connect calls if they conflict with existing headers, or alter expected results.

Parameters

host (str, optional) – The hostname or IP address to connect to. (default: localhost)
username (str, optional) – Username to authenticate with.
password (str, optional) – Password to authenticate with.
auth (str, optional) – Pre-encoded ‘Basic Authentication’ string which may be used in place of a username and password pair.
base_url (str, optional) – Base endpoint path to use. (default: /vmturbo/rest/)
req_versions (VersionSpec, optional) – Versions requirements object.
disable_hateoas (bool, optional) – Removes HATEOAS navigation links. (default: True)
ssl (bool, optional) – Use SSL or not. (default: True)
verify (string, optional) – SSL certificate bundle path. (default: False)
cert (string, optional) – Local client side certificate file.
headers (dict, optional) – Dicitonary of additional persistent headers.
use_session (bool, optional) – If set to True, a requests.Session will be created, otherwise individual requests.Request calls will be made. (default: True)
proxies (dict, optional) – Dictionary of proxy definitions.

disable_hateoas

HATEOAS links state.

Type: bool

fetch_all

Fetch all cursor results state.

Type: bool

headers

Dictionary of custom headers for all calls.

Type: dict

last_response

The last response object received.

Type: requests.Response

proxies

Dictionary of proxies to use. You can also configure proxies using the HTTP_PROXY and HTTPS_PROXY environment variables.

Type: dict

results_limit

Results set limiting & curor stepping value.

Type: int

update_headers

Dictionary of custom headers for put and post calls.

Type: dict

version

Turbonomic instance version object.

Type: Version

Raises

VMTConnectionError – If connection to the server failed.
VMTUnknownVersion – When unable to determine the API base path.
HTTP401Error – When access is denied.

Notes

The default minimum version for classic builds is 6.1.x, and for XL it is 7.21.x Using a previous version will trigger a version warning. To avoid this warning, you will need to explicitly pass in a VersionSpec object for the version desired.

Beginning with v6.0 of Turbonomic, HTTP redirects to a self-signed HTTPS connection. Because of this, vmt-connect defaults to using SSL. Versions prior to 6.0 using HTTP will need to manually set ssl to False. If verify is given a path to a directory, the directory must have been processed using the c_rehash utility supplied with OpenSSL. For client side certificates using cert: the private key to your local certificate must be unencrypted. Currently, Requests, which vmt-connect relies on, does not support using encrypted keys. Requests uses certificates from the package certifi which should be kept up to date.

The /api/v2 path was added in 6.4, and the /api/v3 path was added in XL branch 7.21. The XL API is not intended to be an extension of the Classic API, though there is extensive parity. vmt-connect will attempt to detect which API you are connecting to and adjust accordingly where possible.

XL uses OID identifiers internally instead of UUID identifiers. The change generally does not affect the API, the UUID label is still used, although the structure of the IDs is different.

add_group(dto)

Raw group creation method.

Parameters: dto (str) – JSON representation of the GroupApiDTO.
Returns: Group object in dict form.

Session 

class vmtconnect.Session(*args, **kwargs)

Bases: Connection

Alias for Connection to provide convenience.

See Connection for parameter details.

Notes

The value for the session property will always be set to True when using Session

Response Handlers 

Versioning 

Version 

class vmtconnect.Version(version)

Turbonomic instance version object

The Version object contains instance version information, and equivalent Turbonomic version information in the case of a white label product.

Parameters: version (obj) – Version object returned by Turbonomic instance.

version

Reported Instance version

Type: str

product

Reported Product name

Type: str

snapshot

True if the build is a snapshot / dev build, False otherwise.

Type: bool

base_version

Equivalent Turbonomic version

Type: str

base_build

Equivalent Turbonomic build

Type: str

base_branch

Equivalent Turbonomic branch

Type: str

Raises: VMTUnknownVersion – When version data cannot be parsed.

VersionSpec 

class vmtconnect.VersionSpec(versions=None, exclude=None, required=True, snapshot=False, cmp_base=True)

Turbonomic version specification object

The VersionSpec object contains version compatibility and requirements information. Versions must be in dotted format, and may optionally have a ‘+’ postfix to indicate versions greater than or equal to are acceptable. If using ‘+’, you only need to specify the minimum version required, as all later versions will be accepted independent of minor release branch. E.g. 6.0+ includes 6.1, 6.2, and all later branches.

Examples

VersionSpec([‘6.0+’], exclude=[‘6.0.1’, ‘6.1.2’, ‘6.2.5’, ‘6.3.0’])

VersionSpec([‘7.21+’], snapshot=True)

Parameters

versions (list, optional) – A list of acceptable versions.
exclude (list, optional) – A list of versions to explicitly exclude.
required (bool, optional) – If set to True, an error is thrown if no matching version is found when check() is run. (Default: True)
snapshot (bool, optional) – If set to True, will permit connection to snapshot builds tagged with ‘-SNAPSHOT’. (Default: False)
cmp_base (bool, optional) – If True, white label versions will be translated to their corresponding base Turbonomic version prior to comparison. If False, only the explicit product version will be compared. (Default: True)

Raises

VMTFormatError – If the version format cannot be parsed.
VMTVersionError – If version requirement is not met.

Notes

The Turbonomic API is not a well versioned REST API, and each release is treated as if it were a separate API, while retaining the name of “API 2.0” to distinguish it from the “API 1.0” implementation available prior to the Turbonomic HTML UI released with v6.0 of the core product.

As of v3.2.0 required now defaults to True.

check(version)

Checks a Version for validity against the VersionSpec.

Parameters: version (obj) – The Version to check.
Returns: True if valid, False if the version is excluded or not found.
Raises: VMTVersionError – If version requirement is not met.

Utilities 

vmtconnect.enumerate_stats(data, entity=None, period=None, stat=None): Provided as an alias for backwards compatibility only.

Exceptions 

exception vmtconnect.VMTConnectionError: Base connection exception class.

exception vmtconnect.VMTVersionError(message=None): Incompatible version error.

exception vmtconnect.VMTUnknownVersion: Unknown version.

exception vmtconnect.VMTVersionWarning: Generic version warning.

exception vmtconnect.VMTMinimumVersionWarning: Minimum version warnings.

exception vmtconnect.VMTFormatError: Generic format error.

exception vmtconnect.VMTNextCursorMissingError: Raised if the paging cursor header is not provided when expected

exception vmtconnect.HTTPError: Raised when an blocking or unknown HTTP error is returned.

exception vmtconnect.HTTP400Error: Raised when an HTTP 400 error is returned.

exception vmtconnect.HTTP401Error: Raised when access fails, due to bad login or insufficient permissions.

exception vmtconnect.HTTP404Error: Raised when a requested resource cannot be located.

exception vmtconnect.HTTP500Error: Raised when an HTTP 500 error is returned.

exception vmtconnect.HTTP502Error: Raised when an HTTP 502 Bad Gateway error is returned. In most cases this indicates a timeout issue with synchronous calls to Turbonomic and can be safely ignored.

exception vmtconnect.HTTP503Error: Raised when an HTTP 503 Service Unavailable error is returned. Subsequent calls should be expected to fail, and this should be treated as terminal to the session.

exception vmtconnect.HTTPWarning: Raised when an HTTP error can always be safely ignored.

Deprecated Interfaces 

class vmtconnect.VMTConnection(*args, **kwargs)

Alias for Connection to provide backwards compatibility.

See Connection for parameter details.

Notes

The value for session will default to True when using VMTConnection

Warning

Deprecated. Use Connection or Session instead.

class vmtconnect.VMTVersion(versions=None, exclude=None, require=False): Alias for VersionSpec to provide backwards compatibility.

Warning

Deprecated. Use VersionSpec instead.

Security Module 

Import: vmtconnect.security

Classes 

Credential 

class vmtconnect.security.Credential(key=None, cred=None)

Credentials for authenticating to the Turbonomic API.

Upon initialization Credential will check the key filepath, and if present the key will be read into memory; otherwise a new key will be randomly generated.

Parameters

key (str, optional) – Path to the key file.
cred (str, optional) – Path to the credential token.

uid

User id to set new files to.

Type: int

gid

Group id to set new files to.

Type: int

mode

File mode (octal format 0oNNN is ok), to apply to new files.

Type: int

create(message=None, key=None, overwrite=False)

Create and save to file a new cipher key and encrypted message.

Parameters

key (str) – Cipher key to use for encryption. If null, a new key will be generated. (default: None)
message (str) – Message to be encrypted. If null, you will be prompted for a username and password pair interactively.
overwrite (bool) – If True existing key or message data will be overwritten. (default: False)

decrypt(token=None, key=None)

Decrypt the token using the given key, and return the message. If the token file was provided at init, it will be used here, otherwise a valid token must be supplied.

Parameters

token (bytes, optional) – Encrypted token to decrypt.
key (str, optional) – Cipher key to use for decryption.

Returns

The decrypted message.

encrypt(message, key=None)

Encrypt the given message with the given key and return the token.

Parameters

message (str) – Message or data to be encrypted.
key (str, optional) – Cipher key to use for encryption.

Returns

The encrypted token.

get()

Retrieve and decrypt credentials

Returns: Credentials in the form of a Base64 auth string.

get_cipher(key=None): Returns a Fernet cipher for the given key

new_key(): Generate a new key.

prompt_credentials(): Retrieves a new set of credentials from the user, returning a Base64 auth string response.

set(message, key=None, overwrite=False)

Encrypt the given message with the specified key, and save each to their respective files.

Parameters

message (str) – Data to be encrypted.
key (str, optional) – Cipher key to encrypt the message with.
overwrite (bool) – If True existing key or message data will be overwritten. (default: False)

Utility Module 

Import: vmtconnect.util

vmtconnect.util.enumerate_stats(data, entity=None, period=None, stat=None)

Enumerates stats endpoint results

Provides an iterator for more intuitive and cleaner parsing of nested statistics results. Each iteration returns a tuple containing the statistics period date timestamp, as well as the next individual statistic entry as a dictionary.

Parameters

data (list) – Stats endpoint data results to parse.
entity (function, optional) – Optional entity level filter function.
period (function, optional) – Optional period level filter function.
stat (function, optional) – Optional statistic level filter function.

Notes

Filter functions must return True, to continue processing, or False to skip processing the current level element.

Examples

# filter stats for a specific ID
desired_id = '284552108476721'
enumerate_stats(data, entity=lambda x: x['uuid'] == desired_uuid)

# filter specific stats for all IDs
blacklist = ['Ballooning']
enumerate_stats(data, stat=lambda x: x['name'] not in blacklist)

vmtconnect.util.mem_cast(value, unit=None, src=None)

Converts memory from one unit of measure to another. Values are interpreted as base 2 values (JEDEC memory standard), not SI values.

Parameters

value (string) – Base value, represented as a string.
unit (string) – Destination value to convert to. (default: G)
src (string) – Source value unit of measure to convert from. (default: b)

vmtconnect.util.to_defaultdict(factory, data)

Convert a list or dictionary to a defaultdict object

Parameters

factory (obj) – Used as the default value.
data (obj) – List or dict to convert.

Developer Interfaces

Main Module 

Connections 

Connection 

Session 

Response Handlers 

Versioning 

Version 

VersionSpec 

Utilities 

Exceptions 

Deprecated Interfaces 

Security Module 

Classes 

Credential 

Utility Module 