runway.cfngin.providers.aws.default module

Default AWS Provider.

runway.cfngin.providers.aws.default.get_cloudformation_client(session: boto3.Session) → CloudFormationClient[source]: Get CloudFormation boto3 client.

runway.cfngin.providers.aws.default.get_output_dict(stack: StackTypeDef) → Dict[str, str][source]

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

Parameters: stack – The stack object to get outputs from.
Returns: A dictionary with key/values for each output on the stack.

runway.cfngin.providers.aws.default.s3_fallback(fqn: str, template: Template, parameters: List[ParameterTypeDef], tags: List[TagTypeDef], method: Callable[..., Any], change_set_name: Optional[str] = None, service_role: Optional[str] = None) → Any[source]: Falling back to legacy CFNgin S3 bucket region for templates.

runway.cfngin.providers.aws.default.get_change_set_name() → str[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: List[ChangeTypeDef]) → List[ChangeTypeDef][source]

Return the changes within the changeset that require replacement.

Parameters: changeset – List of changes

runway.cfngin.providers.aws.default.output_full_changeset(full_changeset: Optional[List[ChangeTypeDef]] = None, params_diff: Optional[List[DictValue[Any, Any]]] = None, answer: Optional[str] = None, fqn: Optional[str] = None) → None[source]

Optionally output full changeset.

Parameters

full_changeset – A list of the full changeset that will be output if the user specifies verbose.
params_diff – A list of DictValue detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries().
answer – Predetermined answer to the prompt if it has already been answered or inferred.
fqn – Fully qualified name of the stack.

runway.cfngin.providers.aws.default.ask_for_approval(full_changeset: Optional[List[ChangeTypeDef]] = None, params_diff: Optional[List[DictValue[Any, Any]]] = None, include_verbose: bool = False, fqn: Optional[str] = None) → None[source]

Prompt the user for approval to execute a change set.

Parameters

full_changeset – A list of the full changeset that will be output if the user specifies verbose.
params_diff – A list of DictValue detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries()
include_verbose – Boolean for whether or not to include the verbose option.
fqn – fully qualified name of the stack.

Raises

CancelExecution – If approval no given.

runway.cfngin.providers.aws.default.output_summary(fqn: str, action: str, changeset: List[ChangeTypeDef], params_diff: List[DictValue[Any, Any]], replacements_only: bool = False) → None[source]

Log a summary of the changeset.

Parameters

fqn – Fully qualified name of the stack.
action – Action to include in the log message.
changeset – AWS changeset.
params_diff – A list of dictionaries detailing the differences between two parameters returned by runway.cfngin.actions.diff.diff_dictionaries()
replacements_only – Boolean for whether or not we only want to list replacements.

runway.cfngin.providers.aws.default.format_params_diff(params_diff: List[runway.cfngin.actions.diff.DictValue[Any, Any]]) → str[source]: Wrap runway.cfngin.actions.diff.format_params_diff() for testing.

runway.cfngin.providers.aws.default.summarize_params_diff(params_diff: List[runway.cfngin.actions.diff.DictValue[Any, Any]]) → str[source]: Summarize parameter diff.

runway.cfngin.providers.aws.default.wait_till_change_set_complete(cfn_client: CloudFormationClient, change_set_id: str, try_count: int = 25, sleep_time: float = 0.5, max_sleep: float = 3) → DescribeChangeSetOutputTypeDef[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 – Used to query CloudFormation.
change_set_id – The unique changeset id to wait for.
try_count – Number of times to try the call.
sleep_time – Time to sleep between attempts.
max_sleep – Max time to sleep during backoff

runway.cfngin.providers.aws.default.create_change_set(cfn_client: CloudFormationClient, fqn: str, template: Template, parameters: List[ParameterTypeDef], tags: List[TagTypeDef], change_set_type: str = 'UPDATE', service_role: Optional[str] = None) → Tuple[List[ChangeTypeDef], str][source]: Create CloudFormation change set.

runway.cfngin.providers.aws.default.check_tags_contain(actual: List[TagTypeDef], expected: List[TagTypeDef]) → bool[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 – 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 – Set of tags that must be present in actual (in the same format).

runway.cfngin.providers.aws.default.generate_cloudformation_args(stack_name: str, parameters: List[ParameterTypeDef], tags: List[TagTypeDef], template: Template, capabilities: Optional[List[str]] = None, change_set_type: Optional[str] = None, service_role: Optional[str] = None, stack_policy: Optional[Template] = None, change_set_name: Optional[str] = None) → Dict[str, Any][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 – The fully qualified stack name in Cloudformation.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.
template – The template object.
capabilities – A list of capabilities to use when updating Cloudformation.
change_set_type – An optional change set type to use with create_change_set.
service_role – An optional service role to use when interacting with Cloudformation.
stack_policy – A template object representing a stack policy.
change_set_name – An optional change set name to use with create_change_set.

runway.cfngin.providers.aws.default.generate_stack_policy_args(stack_policy: Optional[Template] = None) → Dict[str, str][source]

Convert a stack policy object into keyword args.

Parameters: stack_policy – A template object representing a stack policy.

class runway.cfngin.providers.aws.default.ProviderBuilder[source]

Bases: object

Implements a Memorized ProviderBuilder for the AWS provider.

__init__(*, region: Optional[str] = None, **kwargs: Any) → None[source]: Instantiate class.

build(*, profile: Optional[str] = None, region: Optional[str] = None) → runway.cfngin.providers.aws.default.Provider[source]: Get or create the provider for the given region and profile.

__new__(**kwargs)

class runway.cfngin.providers.aws.default.Provider[source]

Bases: runway.cfngin.providers.base.BaseProvider

AWS CloudFormation Provider.

__init__(session: boto3.Session, *, interactive: bool = False, recreate_failed: bool = False, region: Optional[str] = None, replacements_only: bool = False, service_role: Optional[str] = None)[source]: Instantiate class.

get_stack(stack_name: str, *_args: Any, **_kwargs: Any) → StackTypeDef[source]: Get stack.

static get_stack_status(stack: StackTypeDef, *_args: Any, **_kwargs: Any) → str[source]: Get stack status.

static get_stack_status_reason(stack: StackTypeDef) → Optional[str][source]: Get stack status reason.

is_stack_being_destroyed(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘being destroyed’.

is_stack_completed(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘complete’.

is_stack_destroy_possible(stack: StackTypeDef) → bool[source]: Whether the status of the stack is able to be cleanly deleted.

is_stack_in_progress(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘in progress’.

is_stack_destroyed(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘deleted’.

is_stack_recreatable(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘recreating’.

is_stack_rolling_back(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘rolling back’.

is_stack_failed(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates it is ‘failed’.

is_stack_in_review(stack: StackTypeDef) → bool[source]: Whether the status of the stack indicates if ‘review in progress’.

tail_stack(stack: Stack, cancel: threading.Event, action: Optional[str] = None, log_func: Optional[Callable[[StackEventTypeDef], None]] = None, retries: Optional[int] = None) → None[source]: Tail the events of a stack.

get_delete_failed_status_reason(stack_name: str) → Optional[str][source]

Process events and return latest delete failed reason.

Parameters: stack_name – Name of a CloudFormation Stack.
Returns: Reason for the Stack’s DELETE_FAILED status if one can be found.

get_event_by_resource_status(stack_name: str, status: str, *, chronological: bool = True) → Optional[StackEventTypeDef][source]

Get Stack Event of a given set of resource status.

Parameters

stack_name – Name of a CloudFormation Stack.
status – Resource status to look for.
chronological – Whether to sort events in chronological order before looking for the desired status.

Returns

The first Stack Event matching the given status.

get_events(stack_name: str, chronological: bool = True) → Iterable[StackEventTypeDef][source]: Get the events in batches and return in chronological order.

get_rollback_status_reason(stack_name: str) → Optional[str][source]

Process events and returns latest roll back reason.

Parameters: stack_name – Name of a CloudFormation Stack.
Returns: Reason for the Stack’s rollback status if one can be found.

tail(stack_name: str, cancel: threading.Event, log_func: Callable[[StackEventTypeDef], None] = <staticmethod(<function Provider._tail_print>)>, sleep_time: int = 5, include_initial: bool = True) → None[source]: Show and then tail the event log.

destroy_stack(stack: StackTypeDef, *, action: str = 'destroy', approval: Optional[str] = None, force_interactive: bool = False, **kwargs: Any) → None[source]

Destroy a CloudFormation Stack.

Parameters

stack – Stack to be destroyed.
action – Name of the action being executed. This impacts the log message used.
approval – Response to approval prompt.
force_interactive – Always ask for approval.

create_stack(fqn: str, template: Template, parameters: List[ParameterTypeDef], tags: List[TagTypeDef], *, force_change_set: bool = False, stack_policy: Optional[Template] = None, termination_protection: bool = False, timeout: Optional[int] = None, **kwargs: Any) → None[source]

Create a new Cloudformation stack.

Parameters

fqn – The fully qualified name of the Cloudformation stack.
template – A Template object to use when creating the stack.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.
force_change_set – Whether or not to force change set use.
stack_policy – A template object representing a stack policy.
termination_protection – End state of the stack’s termination protection.
timeout – The amount of time that can pass before the stack status becomes CREATE_FAILED.

select_update_method(force_interactive: bool, force_change_set: bool) → Callable[[...], None][source]

Select the correct update method when updating a stack.

Parameters

force_interactive – Whether or not to force interactive mode no matter what mode the provider is in.
force_change_set – 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: StackTypeDef, tags: List[TagTypeDef]) → bool[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 – A stack object returned from get_stack
tags – 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

update_stack(fqn: str, template: Template, old_parameters: List[ParameterTypeDef], parameters: List[ParameterTypeDef], tags: List[TagTypeDef], force_interactive: bool = False, force_change_set: bool = False, stack_policy: Optional[Template] = None, termination_protection: bool = False, **kwargs: Any) → None[source]

Update a Cloudformation stack.

Parameters

fqn – The fully qualified name of the Cloudformation stack.
template – A Template object to use when updating the stack.
old_parameters – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.
force_interactive – 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 – A flag that indicates whether the update must be executed with a change set.
stack_policy – A template object representing a stack policy.
termination_protection – End state of the stack’s termination protection.

update_termination_protection(fqn: str, termination_protection: bool) → None[source]

Update a Stack’s termination protection if needed.

Runs before the normal stack update process.

Parameters

fqn – The fully qualified name of the Cloudformation stack.
termination_protection – End state of the stack’s termination protection.

deal_with_changeset_stack_policy(fqn: str, stack_policy: Optional[Template] = None) → None[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

fqn – Fully qualified name of the stack.
stack_policy – A template object representing a stack policy.

interactive_destroy_stack(fqn: str, approval: Optional[str] = None, **kwargs: Any) → None[source]

Delete a CloudFormation stack in interactive mode.

Parameters

fqn – A fully qualified stack name.
approval – Response to approval prompt.

interactive_update_stack(fqn: str, template: Template, old_parameters: List[ParameterTypeDef], parameters: List[ParameterTypeDef], stack_policy: Template, tags: List[TagTypeDef]) → None[source]

Update a Cloudformation stack in interactive mode.

Parameters

fqn – The fully qualified name of the Cloudformation stack.
template – A Template object to use when updating the stack.
old_parameters – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
stack_policy – A template object representing a stack policy.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

noninteractive_destroy_stack(fqn: str, **_kwargs: Any) → None[source]

Delete a CloudFormation stack without interaction.

Parameters: fqn – A fully qualified stack name.

__new__(**kwargs)

get_output(stack: str, output: str) → str: Abstract method.

noninteractive_changeset_update(fqn: str, template: Template, old_parameters: List[ParameterTypeDef], parameters: List[ParameterTypeDef], stack_policy: Optional[Template], tags: List[TagTypeDef]) → None[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 – The fully qualified name of the Cloudformation stack.
template – A Template object to use when updating the stack.
old_parameters – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
stack_policy – A template object representing a stack policy.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

select_destroy_method(force_interactive: bool) → Callable[[...], None][source]

Select the correct destroy method for destroying a stack.

Parameters: force_interactive – Always ask for approval.
Returns: Interactive or non-interactive method to be invoked.

default_update_stack(fqn: str, template: Template, old_parameters: List[ParameterTypeDef], parameters: List[ParameterTypeDef], tags: List[TagTypeDef], stack_policy: Optional[Template] = None) → None[source]

Update a Cloudformation stack in default mode.

Parameters

fqn – The fully qualified name of the Cloudformation stack.
template – A Template object to use when updating the stack.
old_parameters – A list of dictionaries that defines the parameter list on the existing Cloudformation stack.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.
stack_policy – A template object representing a stack policy.

static get_stack_name(stack: StackTypeDef) → str[source]: Get stack name.

static get_stack_tags(stack: StackTypeDef) → List[TagTypeDef][source]: Get stack tags.

get_outputs(stack_name: str, *_args: Any, **_kwargs: Any) → Dict[str, str][source]: Get stack outputs.

static get_output_dict(stack: StackTypeDef) → Dict[str, str][source]: Get stack outputs dict.

get_stack_info(stack: StackTypeDef) → Tuple[str, Dict[str, Union[List[str], str]]][source]: Get the template and parameters of the stack currently in AWS.

get_stack_changes(stack: Stack, template: Template, parameters: List[ParameterTypeDef], tags: List[TagTypeDef]) → Dict[str, str][source]

Get the changes from a ChangeSet.

Parameters

stack – The stack to get changes.
template – A Template object to compared to.
parameters – A list of dictionaries that defines the parameter list to be applied to the Cloudformation stack.
tags – A list of dictionaries that defines the tags that should be applied to the Cloudformation stack.

Returns

Stack outputs with inferred changes.

static params_as_dict(parameters_list: List[ParameterTypeDef]) → Dict[str, Union[List[str], str]][source]: Parameters as dict.