heat.engine.resource module

exception heat.engine.resource.NoActionRequired(res_name='Unknown', reason='')

Bases: Exception

Exception raised when a signal is ignored.

Resource subclasses should raise this exception from handle_signal() to suppress recording of an event corresponding to the signal.

exception heat.engine.resource.PollDelay(period)

Bases: Exception

Exception to delay polling of the resource.

This exception may be raised by a Resource subclass’s check_*_complete() methods to indicate that it need not be polled again immediately. If this exception is raised, the check_*_complete() method will not be called again until the nth time that the resource becomes eligible for polling. A PollDelay period of 1 is equivalent to returning False.

class heat.engine.resource.Resource(name, definition, stack)

Bases: heat.engine.status.ResourceStatus

BASE_ATTRIBUTES = ('show',)

FnGetAtt(key, *path)

For the intrinsic function Fn::GetAtt.

Parameters

• key – the attribute key.

• path – a list of path components to select from the attribute.

Returns

the attribute value.

FnGetRefId()

For the intrinsic function Ref.

Results

the id or name of the resource.

LOCK_ACQUIRE = 1

LOCK_ACTIONS = (None, 1, -1, 0)

LOCK_NONE = None

LOCK_RELEASE = -1

LOCK_RESPECT = 0

SHOW = 'show'

action_handler_task(action, args=None, action_prefix=None)

A task to call the Resource subclass’s handler methods for action.

Calls the handle_<ACTION>() method for the given action and then calls the check_<ACTION>_complete() method with the result in a loop until it returns True. If the methods are not provided, the call is omitted.

Any args provided are passed to the handler.

If a prefix is supplied, the handler method handle_<PREFIX>_<ACTION>() is called instead.

add_dependencies(deps)

Add implicit dependencies specific to the resource type.

Some resource types may have implicit dependencies on other resources in the same stack that are not linked by a property value (that would be set using get_resource or get_attr for example, thus creating an explicit dependency). Such dependencies are opaque to the user and should be avoided wherever possible, however in some circumstances they are required due to magic in the underlying API.

The deps parameter is a Dependencies object to which dependency pairs may be added.

add_explicit_dependencies(deps)

Add all dependencies explicitly specified in the template.

The deps parameter is a Dependencies object to which dependency pairs are added.

adopt(resource_data)

Adopt the existing resource.

Resource subclasses can provide a handle_adopt() method to customise adopt.

always_replace_on_check_failed = True

attributes_schema = {}

base_attributes_schema = {'show': <heat.engine.attributes.Schema object>}

static build_template_dict(res_name, res_type, tmpl_type, params, props, outputs, description)

calc_update_allowed(props)

cancel_grace_period()

check()

Checks that the physical resource is in its expected state.

Gets the current status of the physical resource and updates the database accordingly. If check is not supported by the resource, default action is to fail and revert the resource’s status to its original state with the added message that check was not performed.

classmethod check_is_substituted(new_res_type)

cinder()

clear_hook(hook)

clear_stored_attributes()

client(name=None, version=None)

client_plugin(name=None)

create()

Create the resource.

Subclasses should provide a handle_create() method to customise creation.

create_convergence(template_id, requires, engine_id, timeout, progress_callback=None)

Creates the resource by invoking the scheduler TaskRunner.

data()

Return the resource data for this resource.

Use methods data_set and data_delete to modify the resource data for this resource.

Returns

a dict representing the resource data for this resource.

data_delete(key)

Remove a key from the resource data.

Returns

True if the key existed to delete.

data_set(key, value, redact=False)

Set a key in the resource data.

default_client_name = None

delete()

A task to delete the resource.

Subclasses should provide a handle_delete() method to customise deletion.

delete_convergence(template_id, engine_id, timeout, progress_callback=None)

Destroys the resource if it doesn’t belong to given template.

The given template is suppose to be the current template being provisioned.

Also, since this resource is visited as part of clean-up phase, the needed_by should be updated. If this resource was replaced by more recent resource, then delete this and update the replacement resource’s replaces field.

delete_snapshot(data)

destroy()

A task to delete the resource and remove it from the database.

entity = None

property external_id

frozen_definition()

Return a frozen ResourceDefinition with stored property values.

The returned definition will contain the property values read from the database, and will have all intrinsic functions resolved (note that this makes it useless for calculating dependencies).

frozen_properties()

Context manager to use the frozen property values from the database.

The live property values are always substituted back when the context ends.

get_attribute(key, *path)

Default implementation for function get_attr and Fn::GetAtt.

This may be overridden by resource plugins to add extra logic specific to the resource implementation.

get_live_resource_data()

Default implementation; can be overridden by resources.

Get resource data and handle it with exceptions.

get_live_state(resource_properties)

Default implementation; should be overridden by resources.

Parameters

resource_properties – resource’s object of Properties class.

Returns

dict of resource’s real state of properties.

get_nested_parameters_stack()

Return the nested stack for schema validation.

Regular resources don’t have such a thing.

get_reference_id()

Default implementation for function get_resource.

This may be overridden by resource plugins to add extra logic specific to the resource implementation.

classmethod getdoc()

glance()

handle_adopt(resource_data=None)

handle_delete()

Default implementation; should be overridden by resources.

handle_metadata_reset()

Default implementation; should be overridden by resources.

Now we override this method to reset the metadata for scale-policy and scale-group resources, because their metadata might hang in a wrong state (‘scaling_in_progress’ is always True) if engine restarts while scaling.

handle_preempt()

Pre-empt an in-progress update when a new update is available.

This method is called when a previous convergence update is in progress but a new update for the resource is available. By default it does nothing, but subclasses may override it to cancel the in-progress update if it is safe to do so.

Note that this method does not run in the context of the in-progress update and has no access to runtime information about it; nor is it safe to make changes to the Resource in the database. If implemented, this method should cause the existing update to complete by external means. If this leaves the resource in a FAILED state, that should be taken into account in needs_replace_failed().

handle_update(json_snippet, tmpl_diff, prop_diff)

has_hook(hook)

has_interface(resource_type)

Check if resource is mapped to resource_type or is “resource_type”.

Check to see if this resource is either mapped to resource_type or is a “resource_type”.

has_nested()

Return True if the resource has an existing nested stack.

For most resource types, this will always return False. StackResource subclasses return True when appropriate. Resource subclasses that may return True must also provide a nested_identifier() method to return the identifier of the nested stack, and a nested() method to return a Stack object for the nested stack.

heat()

identifier()

Return an identifier for this resource.

classmethod is_service_available(context)

is_using_neutron()

keystone()

classmethod load(context, resource_id, current_traversal, is_update, data)

Load a specified resource from the database to check.

Returns a tuple of the Resource, the StackDefinition corresponding to the resource’s ResourceDefinition (i.e. the one the resource was last updated to if it has already been created, or the one it will be created with if it hasn’t been already), and the Stack containing the latest StackDefinition (i.e. the one that the latest traversal is updating to.

The latter two must remain in-scope, because the Resource holds weak references to them.

lock(engine_id)

make_replacement(new_tmpl_id, requires)

Create a replacement resource in the database.

Returns the DB ID of the new resource, or None if the new resource cannot be created (generally because the template ID does not exist). Raises UpdateInProgress if another traversal has already locked the current resource.

metadata_get(refresh=False)

metadata_set(metadata, merge_metadata=None)

Write new metadata to the database.

The caller may optionally provide a merge_metadata() function, which takes two arguments - the metadata passed to metadata_set() and the current metadata of the resource - and returns the merged metadata to write. If merge_metadata is not provided, the metadata passed to metadata_set() is written verbatim, overwriting any existing metadata.

If a race condition is detected, the write will be retried with the new result of merge_metadata() (if it is supplied) or the verbatim data (if it is not).

metadata_update(new_metadata=None)

No-op for resources which don’t explicitly override this method.

needs_replace(after_props)

Mandatory replace based on certain properties.

needs_replace_failed()

Needs replace if resource is in *_FAILED.

needs_replace_with_prop_diff(changed_properties_set, after_props, before_props)

Needs replace based on prop_diff.

needs_replace_with_tmpl_diff(tmpl_diff)

Needs replace based on tmpl_diff.

neutron()

no_signal_actions = ('SUSPEND', 'DELETE')

node_data(stk_defn=None, for_resources=True, for_outputs=False)

Return a NodeData object representing the resource.

The NodeData object returned contains basic data about the resource, including its name, ID and state, as well as its reference ID and any attribute values that are used.

By default, those attribute values that are referenced by other resources are included. These can be ignored by setting the for_resources parameter to False. If the for_outputs parameter is True, those attribute values that are referenced by stack outputs are included. If the for_outputs parameter is an iterable of output names, only those attribute values referenced by the specified stack outputs are included.

The set of referenced attributes is calculated from the StackDefinition object provided, or from the stack’s current definition if none is passed.

After calling this method, the resource’s attribute cache is populated with any cacheable attribute values referenced by stack outputs, even if they are not also referenced by other resources.

nova()

parse_live_resource_data(resource_properties, resource_data)

Default implementation; can be overridden by resources.

Parse resource data for using it in updating properties with live state. :param resource_properties: properties of stored resource plugin. :param resource_data: data from current live state of a resource.

static pause()

physical_resource_name()

physical_resource_name_limit = 255

physical_resource_name_or_FnGetRefId()

prepare_abandon()

prepare_for_replace()

Prepare resource for replacing.

Some resources requires additional actions before replace them. If resource need to be changed before replacing, this method should be implemented in resource class.

preview()

Default implementation of Resource.preview.

This method should be overridden by child classes for specific behavior.

preview_update(after, before, after_props, before_props, prev_resource, check_init_complete=False)

Simulates update without actually updating the resource.

Raises UpdateReplace, if replacement is required or returns True, if in-place update is required.

static reduce_physical_resource_name(name, limit)

Reduce length of physical resource name to a limit.

The reduced name will consist of the following:

• the first 2 characters of the name

• a hyphen

• the end of the name, truncated on the left to bring the name length within the limit

Parameters

• name – The name to reduce the length of

• limit – The max length limit

Returns

A name whose length is less than or equal to the limit

referenced_attrs(stk_defn=None, in_resources=True, in_outputs=True, load_all=False)

Return the set of all attributes referenced in the template.

This enables the resource to calculate which of its attributes will be used. By default, attributes referenced in either other resources or outputs will be included. Either can be excluded by setting the in_resources or in_outputs parameters to False. To limit to a subset of outputs, pass an iterable of the output names to examine for the in_outputs parameter.

The set of referenced attributes is calculated from the StackDefinition object provided, or from the stack’s current definition if none is passed.

regenerate_info_schema(definition)

Default implementation; should be overridden by resources.

Should be overridden by resources that would require schema refresh during update, ex. TemplateResource.

Definition

Resource Definition

reparse(client_resolve=True)

Reparse the resource properties.

Optional translate flag for property translation and client_resolve flag for resolving properties by doing client lookup.

required_by()

List of resources that require this one as a dependency.

Returns a list of names of resources that depend on this resource directly.

required_service_extension = None

requires_deferred_auth = False

resource_id_set(inst)

classmethod resource_to_template(resource_type, template_type='cfn')

Generate a provider template that mirrors the resource.

Parameters

• resource_type – The resource type to be displayed in the template

• template_type – the template type to generate, cfn or hot.

Returns

A template where the resource’s properties_schema is mapped as parameters, and the resource’s attributes_schema is mapped as outputs

restore_prev_rsrc(convergence=False)

Restore resource after rollback.

Some resources requires additional actions after rollback. If resource need to be changed during rollback, this method should be implemented in resource class.

resume()

Return a task to resume the resource.

Subclasses should provide a handle_resume() method to implement resume.

rpc_client()

Return a client for making engine RPC calls.

signal(details=None, need_check=True)

Signal the resource.

Returns True if the metadata for all resources in the stack needs to be regenerated as a result of the signal, False if it should not be.

Subclasses should provide a handle_signal() method to implement the signal. The base-class raise an exception if no handler is implemented.

signal_needs_metadata_updates = True

snapshot()

Snapshot the resource and return the created data, if any.

property stack

property state

Returns state, tuple of action, status.

state_reset()

Reset state to (INIT, COMPLETE).

state_set(action, status, reason='state changed', lock=None)

store(set_metadata=False, lock=None)

Create the resource in the database.

If self.id is set, we update the existing stack.

store_attributes()

strict_dependency = True

support_status = <heat.engine.support.SupportStatus object>

suspend()

Return a task to suspend the resource.

Subclasses should provide a handle_suspend() method to implement suspend.

swift()

translate_properties(properties, client_resolve=True, ignore_resolve_error=False)

Set resource specific rules for properties translation.

The properties parameter is a properties object and the optional client_resolve flag is to specify whether to do ‘RESOLVE’ translation with client lookup.

translation_rules(properties)

Return specified rules for resource.

trigger_hook(hook)

trove()

type()

update(after, before=None, prev_resource=None, new_template_id=None, new_requires=None)

Return a task to update the resource.

Subclasses should provide a handle_update() method to customise update, the base-class handle_update will fail by default.

update_allowed_properties = ()

update_convergence(template_id, new_requires, engine_id, timeout, new_stack, progress_callback=None)

Update the resource synchronously.

Persist the resource’s current_template_id to template_id and resource’s requires to list of the required resource ids from the given resource_data and existing resource’s requires, then updates the resource by invoking the scheduler TaskRunner.

update_policy_schema = {}

update_template_diff(after, before)

Returns the difference between the before and after json snippets.

If something has been removed in after which exists in before we set it to None.

update_template_diff_properties(after_props, before_props)

Return changed Properties between the before and after properties.

If any property having immutable as True is updated, raises NotSupported error. If any properties have changed which are not in update_allowed_properties, raises UpdateReplace.

validate()

Validate the resource.

This may be overridden by resource plugins to add extra validation logic specific to the resource implementation.

classmethod validate_deletion_policy(policy)

validate_external()

validate_template()

Validate structural/syntax aspects of the resource definition.

Resource plugins should not override this, because this interface is expected to be called pre-create so things normally valid in an overridden validate() such as accessing properties may not work.