vmtplanner

The base module of vmt-plan package provides a plan engine class called Plan, which executes a Turbonomic plan as defined by the settings in a PlanSpec.

Enumerations

class vmtplanner.AutomationSetting(value)

Automation Settings.

class vmtplanner.AutomationValue(value)

Automation Settings Values.

class vmtplanner.CloudLicense(value)

Cloud OS licensing.

class vmtplanner.CloudOS(value)

Cloud OS definitions.

class vmtplanner.CloudTargetOS(value)

Cloud Target OS definitions.

class vmtplanner.ConstraintCommodity(value)

Plan constraint commodities.

class vmtplanner.EntityAction(value)

Plan entity changes.

class vmtplanner.MarketState(value)

Market states.

class vmtplanner.PlanType(value)

Plan scenario types.

class vmtplanner.ServerResponse(value)

Turbonomic service responses.

Classes

class vmtplanner.Plan(connection, spec=None, market='Market', name=None)

Plan instance.

Parameters

  • connection (Connection) – Connection or Session.

  • spec (PlanSpec, optional) – Settings to apply to the market, if running a plan.

  • market (str, optional) – Base market UUID to apply the settings to.

  • name (str, optional) – Plan display name.

duration

Plan duration in seconds, or None if unavailable.

Type

int

initialized

True if the market is initialized and usable.

Type

bool

market_id

Market UUID, read-only attribute.

Type

str

market_name

Market name, read-only attribute.

Type

str

result

Market run result state.

Type

MarketState

scenario_id

Scenario UUID, read-only attribute.

Type

str

scenario_name

Scenario name, read-only attribute.

Type

str

script_duration

Plan script duration in seconds.

Type

int

server_duration

Plan server side duration in seconds.

Type

int

state

Current state of the market.

Type

MarketState

start

datetime object representing the start time, or None if no plan has been run.

Type

datetime

unplaced_entities

True if there are unplaced entities.

Type

bool

delete(scenario=True)

Removes the market, and the scenario.

Parameters

scenario (bool, optional) – If True, removes the scenario as well. (default: True)

Returns

True upon success, False otherwise.

Return type

bool

Raises
get_state()

Returns the current market state.

Returns

Current market state.

Return type

MarketState

get_stats()

Returns statistics for the market.

Returns

A list of statistics by period.

Return type

list

is_complete()

Returns True if the market completed successfully.

is_ready()

Returns True if market is initialized and ready to start.

is_running()

Returns True if market state is currently running.

is_state(state)

Checks if the market is in the given state.

Parameters

state (MarketState) – Market state to compare to.

Returns

True if matched, False otherwise.

Return type

bool

is_stopped()

Returns True if market state is stopped.

is_system()

Checks if the market is a protected system market.

Returns

True if the market is a designated system market, False otherwise.

Return type

bool

run()

Runs the market with currently applied scenario and settings.

Raises

PlanError if retry limit is reached. –

run_async()

Runs the market plan in asynchronous mode.

When run asynchronously the plan will be started and the state returned immediately. All settings pertaining to polling, timeout, and retry will be ignored. The duration will not be recorded, and plan hooks are not called.

stop()

Stops the market.

Returns

True upon success. Raises an exception otherwise.

Return type

bool

Raises
class vmtplanner.PlanSpec(name=None, type=<PlanType.CUSTOM: 'CUSTOM'>, scope=None, version=None)

Plan scenario specification.

Parameters

  • name (str, optional) – Name of the plan scenario.

  • type (PlanType, optional) – Type of plan to be run. (default: PlanType.CUSTOM)

  • scope (list, optional) – Scope of the plan market.

  • version (vmtconnect.Version, optional) – PlanSpec version.

abort_timeout

Abort timeout in minutes.

Type

int

abort_poll_freq

Abort status polling interval in seconds.

Type

int

max_retry

Plan retry limit.

Type

int

poll_freq

Status polling interval in seconds, 0 = dynamic.

Type

int

timeout

Plan timeout in minutes, 0 = infinite.

Type

int

Note

The changes and entities parameters were removed in v2.0.0. If version is not supplied, the Connection version will be used when the scenario is evaluated by the Plan class. If you need to generate a scenario DTO without a Plan class, you will need to supply the version prior to calling to_json() or accessing the json property.

add_entity(id, count=1, periods=None)

Add copies of an entity.

Important

Deprecated legacy interface. Use change_entity() instead.

This is an alias for change_entity() provided for backward compatibility.

Parameters

  • id (str) – Target entity UUID.

  • count (int, optional) – Number of copies to add. (default: 1)

  • periods (list, optional) – List of periods to add copies. (default: [0])

See also

See Plan Periods.

add_hist(value=True)

Alias for add_historical().

add_historical(value=True)

Add VMs based on previous month.

Parameters

value (bool) – True or False. (default: True)

add_template(id, count=1, periods=None)

Add copies of a template.

Important

Deprecated legacy interface. Use change_entity() instead.

This is an alias for change_entity() provided for backward compatibility.

Parameters

  • id (str) – Target entity UUID.

  • count (int, optional) – Number of copies to add. (default: 1)

  • periods (list, optional) – List of periods to add copies. (default: [0])

See also

See Plan Periods.

change_automation_setting(setting, value)

Change plan automation settings.

Parameters

  • setting (AutomationSetting) – Setting to modify.

  • value – For most settings, the value will be a bool. For desired state changes, the value will be an int.

Note

  • Classic 6.1 - Automation settings are either on or off, thus a value of True or False is required.

  • XL 7.19 - Automation settings are either on or off, thus a value of True or False is required.

  • XL 7.20 - Automation settings now follow, approximately, the action mode model, and the value must be one of AutomationValue .

change_entity(action, targets, projection=[0], count=None, new_target=None)

Change entities handles adding, removing, replacing, and migrating entities within the plan. Each EntityAction has different required parameters, as defined below.

Common Parameters

  • action - required

  • targets - required

  • projection - optional

Add Entity Specific Parameters

  • count - optional

Replace Entity Specific Parameters

  • new_target - required

Migrate Entity Specific Parameters

  • new_target - required

Parameters

  • action (EntityAction) – Change to effect on the entity.

  • targets (list) – List of entity or group UUIDs.

  • projection (list) – List of days from today at which to make change. (default: [0])

  • count (int) – Number of copies to add. (default: 1)

  • new_target (str) – Template UUID to replace target with. Destination group or host UUID for migrations.

See also

See Plan Periods.

change_max_utilization(targets, type='', value=0, projection=0)

Set the max percentage of a commodity’s capacity a VM or group of VMs can consume.

Parameters

  • targets (list) – List of entity or group UUIDs.

  • type (str, conditional) – Commodity type to modify. (ignored in 6.1.0+)

  • value (int) – Utilization value as a positive integer 0 to 100.

  • projection (int, optional) – Singular period in which to set the setting. (default: 0)

Note

This method provides backwards compatibility with previous versions of Turbonomic which require deprecated parameters. The type parameter is required by versions of Turbonomic prior to 6.1.0, and ignored otherewise.

change_utilization(targets, value, projection=0)

Change load of virtual machines by specified percentage.

Parameters

  • targets (list) – List of entity or group UUIDs.

  • value (int) – Utilization value as a positive integer 0 to 100.

  • projection (int, optional) – Singular period in which to set the setting.

cloud_os_profile(match_source=None, unlicensed=None, source=None, target=None, custom_map=None)

Configures OS migration profile for Migrate to Cloud plans.

Custom mapping dict format:

{‘source’: CloudOS, ‘target’: CloudOS, ‘unlicensed’: bool}

Parameters

  • match_source (bool, optional) – If True, the source OS will be matched.

  • unlicensed (bool, optional) – If True, destination targets will be selected without licensed OSes.

  • source (CloudOS) – Source OS to map from.

  • target (CloudOS) – Target OS to map to.

  • custom (list, optional) – List of dict custom OS settings.

delete_entity(id, periods=None)

Remove an entity.

Important

Deprecated legacy interface. Use change_entity() instead.

This is an alias for change_entity() provided for backward compatibility.

Parameters

  • id (str) – Target entity UUID.

  • periods (list, optional) – List of periods to add copies. (default: [0])

See also

See Plan Periods.

include_reserved(value=True)

Setting to include reserved VMs in the plan.

Parameters

value (bool) – True or False. (default: True)

migrate_entity(id, destination_id, period=0)

Migrate entity.

Important

Deprecated legacy interface. Use change_entity() instead.

This is an alias for change_entity() provided for backward compatibility.

Parameters

  • id (str) – Target entity or group UUID to migrate.

  • destination_id (str) – Destination entity or group UUID.

  • period (int, optional) – Period in which to migrate. (default: 0)

See also

See Plan Periods.

relieve_pressure(sources, targets, projection=0)

Migrates hot clusters to cold clusters to alleviate resource pressure.

Scope should not be set to market for this plan type. Unlike other entity methods, relieve_pressure() is primairly purposed for the ALLEVIATE_PRESSURE plan type. It should only be used in ALLEVIATE_PRESSURE or CUSTOM plans.

Parameters

  • sources (list) – list of one or more cluster UUIDs to migrate.

  • targets (list) – list of one or more destination cluster UUIDs.

  • projection (int, optional) – Period in which to migrate.

remove_constraints(targets=None, commodity=None, projection=0)

Removes specific constraints for selected entities, or all constraints for the entire market.

Parameters

  • targets (list, optional) – List of entity or group UUIDs.

  • commodity (ConstraintCommodity, optional) – Commodity constraint to remove on a target. targets is required with this parameter, or it is ignored.

  • projection (int, optional) – Singular period in which to set the setting.

Note

To remove all constraints from the entire market (global level), leave the targets and commodity fields empty.

replace_entity(id, replacement_id, count=1, periods=None)

Replace an entity with a template.

Important

Deprecated legacy interface. Use change_entity() instead.

This is an alias for change_entity() provided for backward compatibility.

Parameters

  • id (str) – UUID of the entity to replace.

  • replacement_id (str) – Template UUID to use as a replacement.

  • count (int, optional) – Number of copies to add. (default: 1)

  • periods (list, optional) – List of periods to add copies. (default: [0])

See also

See Plan Periods.

set(center=None, diameter=None, description=None)

Deprecated - see change_automation_setting()

set_hist_baseline(value)

Alias for set_historical_baseline().

set_historical_baseline(value)

Set the used and peak utilization for the plan based on historical data.

Parameters

value (int) – Date as a Unix timestamp in milliseconds.

set_max_utilization(type, value, ids, periods=None)

Deprecated - see change_max_utilization()

set_peak_baseline(targets, value)

Loads a peak baseline from history.

Parameters

  • value (int) – Date as a Unix timestamp in milliseconds.

  • ids (list) – List of VM cluster UUIDs.

set_scope(targets, append=False)

Sets the plan scope.

Parameters

  • targets (list) – List of entity or group UUIDs.

  • append (bool, optional) – If True, scope will be extended. (default: False)

set_used(value, ids)

Deprecated - see change_utilization()

set_utilization(type, value, ids)

Deprecated - see change_max_utilization()

to_json(version=None, **kwargs)

Returns the version specific DTO for the scenario.

Parameters

  • version (object, optional) – Version object.

  • **kwargs – Additional JSON processing arguments.

Raises

PlanError if no version definition is supplied. –

Exceptions

exception vmtplanner.MarketError

Base market exception class.

exception vmtplanner.InvalidMarketError

Raised when trying to reference a market that does not exist.

exception vmtplanner.PlanError

Base plan exception class.

exception vmtplanner.PlanRunning

Raised when a plan is already running.

exception vmtplanner.PlanRunFailure

Raised when a plan fails to run properly.

exception vmtplanner.PlanDeprovisionError

Raised when there is an error removing a plan.

exception vmtplanner.PlanExecutionExceeded

Raised when a plan exceeds the timeout period specified.