runway.cfngin.providers.aws.default module

Default AWS Provider.

runway.cfngin.providers.aws.default.get_cloudformation_client(session)[source]

Get CloudFormaiton boto3 client.

runway.cfngin.providers.aws.default.get_output_dict(stack)[source]

Return a dict of key/values for the outputs for a given CF stack.

Parameters

stack (Dict[str, Any]) – The stack object to get outputs from.

Returns

A dictionary with key/values for each output on the stack.

Return type

Dict[str, Any]

runway.cfngin.providers.aws.default.s3_fallback(fqn, template, parameters, tags, method, change_set_name=None, service_role=None)[source]

Falling back to legacy stacker S3 bucket region for templates.

runway.cfngin.providers.aws.default.get_change_set_name()[source]

Return a valid Change Set Name.

The name has to satisfy the following regex:

[a-zA-Z][-a-zA-Z0-9]*

And must be unique across all change sets.

runway.cfngin.providers.aws.default.requires_replacement(changeset)[source]

Return the changes within the changeset that require replacement.

Parameters

changeset (list) – List of changes

Returns

A list of changes that require replacement, if any.

Return type

list

runway.cfngin.providers.aws.default.output_full_changeset(full_changeset=None, params_diff=None, answer=None, fqn=None)[source]

Optionally output full changeset.

Parameters
  • full_changeset (Optional[List[Dict[str, Any]]]) – A list of the full changeset that will be output if the user specifies verbose.

  • params_diff (Optional[List[runway.cfngin.actions.diff.DictValue) – A list of DictValue detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries().

  • answer (Optional[str]) – predetermined answer to the prompt if it has already been answered or inferred.

  • fqn (Optional[str]) – fully qualified name of the stack.

runway.cfngin.providers.aws.default.ask_for_approval(full_changeset=None, params_diff=None, include_verbose=False, fqn=None)[source]

Prompt the user for approval to execute a change set.

Parameters
  • full_changeset (Optional[List[Dict[str, Any]]]) – A list of the full changeset that will be output if the user specifies verbose.

  • params_diff (Optional[List[runway.cfngin.actions.diff]]) – A list of DictValue detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries()

  • include_verbose (bool) – Boolean for whether or not to include the verbose option.

  • fqn (str) – fully qualified name of the stack.

Raises

CancelExecution – If approval no given.

runway.cfngin.providers.aws.default.output_summary(fqn, action, changeset, params_diff, replacements_only=False)[source]

Log a summary of the changeset.

Parameters
  • fqn (string) – fully qualified name of the stack

  • action (string) – action to include in the log message

  • changeset (list) – AWS changeset

  • params_diff (list) – A list of dictionaries detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries()

  • replacements_only (bool, optional) – boolean for whether or not we only want to list replacements

runway.cfngin.providers.aws.default.format_params_diff(params_diff)[source]

Wrap runway.cfngin.actions.diff.format_params_diff() for testing.

runway.cfngin.providers.aws.default.summarize_params_diff(params_diff)[source]

Summarize parameter diff.

runway.cfngin.providers.aws.default.wait_till_change_set_complete(cfn_client, change_set_id, try_count=25, sleep_time=0.5, max_sleep=3)[source]

Check state of a changeset, returning when it is in a complete state.

Since changesets can take a little bit of time to get into a complete state, we need to poll it until it does so. This will try to get the state try_count times, waiting sleep_time * 2 seconds between each try up to the max_sleep number of seconds. If, after that time, the changeset is not in a complete state it fails. These default settings will wait a little over one minute.

Parameters
  • cfn_client (botocore.client.Client) – Used to query CloudFormation.

  • change_set_id (str) – The unique changeset id to wait for.

  • try_count (int) – Number of times to try the call.

  • sleep_time (int) – Time to sleep between attempts.

  • max_sleep (int) – Max time to sleep during backoff

Returns

The response from CloudFormation for the describe_change_set call.

Return type

Dict[str, Any]

runway.cfngin.providers.aws.default.create_change_set(cfn_client, fqn, template, parameters, tags, change_set_type='UPDATE', service_role=None)[source]

Create CloudFormation change set.

runway.cfngin.providers.aws.default.check_tags_contain(actual, expected)[source]

Check if a set of AWS resource tags is contained in another.

Every tag key in expected must be present in actual, and have the same value. Extra keys in actual but not in expected are ignored.

Parameters
  • actual (List[Dict[str, str]]) – Set of tags to be verified, usually from the description of a resource. Each item must be a dict containing Key and Value items.

  • expected (List[Dict[str, str]]) – Set of tags that must be present in actual (in the same format).

runway.cfngin.providers.aws.default.generate_cloudformation_args(stack_name, parameters, tags, template, capabilities=None, change_set_type=None, service_role=None, stack_policy=None, change_set_name=None)[source]

Generate the args for common CloudFormation API interactions.

This is used for create_stack/update_stack/create_change_set calls in CloudFormation.

Parameters
  • stack_name (str) – The fully qualified stack name in Cloudformation.

  • parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

  • template (runway.cfngin.provider.base.Template) – The template object.

  • capabilities (Optional[List[str]]) – A list of capabilities to use when updating Cloudformation.

  • change_set_type (Optional[str]) – An optional change set type to use with create_change_set.

  • service_role (Optional[str]) – An optional service role to use when interacting with Cloudformation.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

  • change_set_name (Optional[str]) – An optional change set name to use with create_change_set.

Returns

A dictionary of arguments to be used in the Cloudformation API call.

Return type

Dict[str, Any]

runway.cfngin.providers.aws.default.generate_stack_policy_args(stack_policy=None)[source]

Convert a stack policy object into keyword args.

Parameters

stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

Returns

A dictionary of keyword arguments to be used elsewhere.

Return type

dict

class runway.cfngin.providers.aws.default.ProviderBuilder(region=None, **kwargs)[source]

Bases: object

Implements a Memorized ProviderBuilder for the AWS provider.

Instantiate class.

build(region=None, profile=None)[source]

Get or create the provider for the given region and profile.

class runway.cfngin.providers.aws.default.Provider(session, region=None, interactive=False, replacements_only=False, recreate_failed=False, service_role=None)[source]

Bases: runway.cfngin.providers.base.BaseProvider

AWS CloudFormation Provider.

Instantiate class.

DELETING_STATUS = 'DELETE_IN_PROGRESS'
DELETED_STATUS = 'DELETE_COMPLETE'
IN_PROGRESS_STATUSES = ('CREATE_IN_PROGRESS', 'IMPORT_IN_PROGRESS', 'UPDATE_IN_PROGRESS', 'DELETE_IN_PROGRESS', 'UPDATE_COMPLETE_CLEANUP_IN_PROGRESS')
ROLLING_BACK_STATUSES = ('ROLLBACK_IN_PROGRESS', 'IMPORT_ROLLBACK_IN_PROGRESS', 'UPDATE_ROLLBACK_IN_PROGRESS')
FAILED_STATUSES = ('CREATE_FAILED', 'ROLLBACK_FAILED', 'ROLLBACK_COMPLETE', 'DELETE_FAILED', 'IMPORT_ROLLBACK_FAILED', 'UPDATE_ROLLBACK_FAILED', 'UPDATE_ROLLBACK_COMPLETE')
COMPLETE_STATUSES = ('CREATE_COMPLETE', 'DELETE_COMPLETE', 'IMPORT_COMPLETE', 'UPDATE_COMPLETE', 'IMPORT_ROLLBACK_COMPLETE', 'UPDATE_ROLLBACK_COMPLETE')
RECREATION_STATUSES = ('CREATE_FAILED', 'ROLLBACK_FAILED', 'ROLLBACK_COMPLETE')
REVIEW_STATUS = 'REVIEW_IN_PROGRESS'
get_stack(stack_name, *args, **kwargs)[source]

Get stack.

get_stack_status(stack, *args, **kwargs)[source]

Get stack status.

is_stack_being_destroyed(stack, **kwargs)[source]

Whether the status of the stack indicates it is ‘being destroyed’.

is_stack_completed(stack)[source]

Whether the status of the stack indicates it is ‘complete’.

is_stack_in_progress(stack)[source]

Whether the status of the stack indicates it is ‘in progress’.

is_stack_destroyed(stack)[source]

Whether the status of the stack indicates it is ‘deleted’.

is_stack_recreatable(stack)[source]

Whether the status of the stack indicates it is ‘recreating’.

is_stack_rolling_back(stack)[source]

Whether the status of the stack indicates it is ‘rolling back’.

is_stack_failed(stack)[source]

Whether the status of the stack indicates it is ‘failed’.

is_stack_in_review(stack)[source]

Whether the status of the stack indicates if ‘review in progress’.

tail_stack(stack, cancel, action=None, log_func=None, retries=None)[source]

Tail the events of a stack.

get_events(stack_name, chronological=True)[source]

Get the events in batches and return in chronological order.

get_rollback_status_reason(stack_name)[source]

Process events and returns latest roll back reason.

tail(stack_name, cancel, log_func=<staticmethod object>, sleep_time=5, include_initial=True)[source]

Show and then tail the event log.

destroy_stack(stack, *args, **kwargs)[source]

Destroy a CloudFormation Stack.

Parameters

stack (stacker.stack.Stack) – Stack to be destroyed.

Keyword Arguments
  • action (str) – Name of the action being executed. This impacts the log message used.

  • approval (Optional[str]) – Response to approval prompt.

  • force_interactive (bool) – Always ask for approval.

create_stack(fqn, template, parameters, tags, force_change_set=False, stack_policy=None, termination_protection=False, **kwargs)[source]

Create a new Cloudformation stack.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • template (runway.cfngin.providers.base.Template) – A Template object to use when creating the stack.

  • parameters (list) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • tags (list) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

  • force_change_set (bool) – Whether or not to force change set use.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

  • termination_protection (bool) – End state of the stack’s termination protection.

select_update_method(force_interactive, force_change_set)[source]

Select the correct update method when updating a stack.

Parameters
  • force_interactive (str) – Whether or not to force interactive mode no matter what mode the provider is in.

  • force_change_set (bool) – Whether or not to force change set use.

Returns

The correct object method to use when updating.

Return type

function

prepare_stack_for_update(stack, tags)[source]

Prepare a stack for updating.

It may involve deleting the stack if is has failed it’s initial creation. The deletion is only allowed if:

  • The stack contains all the tags configured in the current context;

  • The stack is in one of the statuses considered safe to re-create

  • recreate_failed is enabled, due to either being explicitly enabled by the user, or because interactive mode is on.

Parameters
  • stack (dict) – a stack object returned from get_stack

  • tags (list) – list of expected tags that must be present in the stack if it must be re-created

Returns

True if the stack can be updated, False if it must be re-created

Return type

bool

update_stack(fqn, template, old_parameters, parameters, tags, force_interactive=False, force_change_set=False, stack_policy=None, termination_protection=False, **kwargs)[source]

Update a Cloudformation stack.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • template (runway.cfngin.providers.base.Template) – A Template object to use when updating the stack.

  • old_parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.

  • parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

  • force_interactive (bool) – A flag that indicates whether the update should be interactive. If set to True, interactive mode will be used no matter if the provider is in interactive mode or not. False will follow the behavior of the provider.

  • force_change_set (bool) – A flag that indicates whether the update must be executed with a change set.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

  • termination_protection (bool) – End state of the stack’s termination protection.

update_termination_protection(fqn, termination_protection)[source]

Update a Stack’s termination protection if needed.

Runs before the normal stack update process.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • termination_protection (bool) – End state of the stack’s termination protection.

deal_with_changeset_stack_policy(fqn, stack_policy)[source]

Set a stack policy when using changesets.

ChangeSets don’t allow you to set stack policies in the same call to update them. This sets it before executing the changeset if the stack policy is passed in.

Parameters
interactive_destroy_stack(fqn, approval=None, **kwargs)[source]

Delete a CloudFormation stack in interactive mode.

Parameters
  • fqn (str) – A fully qualified stack name.

  • approval (Optional[str]) – Response to approval prompt.

interactive_update_stack(fqn, template, old_parameters, parameters, stack_policy, tags)[source]

Update a Cloudformation stack in interactive mode.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • template (runway.cfngin.providers.base.Template) – A Template object to use when updating the stack.

  • old_parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.

  • parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

  • tags (List[Dict[str, str]]) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

noninteractive_destroy_stack(fqn, **kwargs)[source]

Delete a CloudFormation stack without interaction.

Parameters

fqn (str) – A fully qualified stack name.

noninteractive_changeset_update(fqn, template, old_parameters, parameters, stack_policy, tags)[source]

Update a Cloudformation stack using a change set.

This is required for stacks with a defined Transform (i.e. SAM), as the default update_stack API cannot be used with them.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • template (runway.cfngin.providers.base.Template) – A Template object to use when updating the stack.

  • old_parameters (list) – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.

  • parameters (list) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

  • tags (list) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

select_destroy_method(force_interactive)[source]

Select the correct destroy method for destroying a stack.

Parameters

force_interactive (bool) – Always ask for approval.

Returns

Interactive or non-interactive method to be invoked.

default_update_stack(fqn, template, old_parameters, parameters, tags, stack_policy=None)[source]

Update a Cloudformation stack in default mode.

Parameters
  • fqn (str) – The fully qualified name of the Cloudformation stack.

  • template (runway.cfngin.providers.base.Template) – A Template object to use when updating the stack.

  • old_parameters (list) – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.

  • parameters (list) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • tags (list) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

  • stack_policy (runway.cfngin.providers.base.Template) – A template object representing a stack policy.

static get_stack_name(stack)[source]

Get stack name.

static get_stack_tags(stack)[source]

Get stack tags.

get_outputs(stack_name, *args, **kwargs)[source]

Get stack outputs.

static get_output_dict(stack)[source]

Get stack outputs dict.

get_stack_info(stack)[source]

Get the template and parameters of the stack currently in AWS.

Returns

Tuple[str, Dict[str, Any]]

get_stack_changes(stack, template, parameters, tags)[source]

Get the changes from a ChangeSet.

Parameters
  • stack (runway.cfngin.stack.Stack) – The stack to get changes.

  • template (runway.cfngin.providers.base.Template) – A Template object to compaired to.

  • parameters (List[Dict[str, Any]]) – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.

  • tags (List[Dict[str, Any]]) – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

Returns

Stack outputs with inferred changes.

Return type

Dict[str, Any]

static params_as_dict(parameters_list)[source]

Parameters as dict.