runway.cfngin.providers.aws.default module

Default AWS Provider.

class runway.cfngin.providers.aws.default.Provider

Bases: BaseProvider

AWS CloudFormation Provider.

__init__(session: boto3.Session, *, interactive: bool = False, recreate_failed: bool = False, region: str | None = None, replacements_only: bool = False, service_role: str | None = None) → None

Instantiate class.

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

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.

• **kwargs – Arbitrary keyword arguments.

deal_with_changeset_stack_policy(fqn: str, stack_policy: Template | None = None) → None

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.

default_update_stack(fqn: str, template: Template, old_parameters: list[ParameterTypeDef], parameters: list[ParameterTypeDef], tags: list[TagTypeDef], stack_policy: Template | None = None) → None

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.

destroy_stack(stack: StackTypeDef, *, action: str = 'destroy', approval: str | None = None, force_interactive: bool = False, **kwargs: Any) → None

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.

• **kwargs – Arbitrary keyword arguments.

get_delete_failed_status_reason(stack_name: str) → str | None

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) → StackEventTypeDef | None

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]

Get the events in batches and return in chronological order.

static get_output_dict(stack: StackTypeDef) → dict[str, str]

Get stack outputs dict.

get_outputs(stack_name: str, *_args: Any, **_kwargs: Any) → dict[str, str]

Get stack outputs.

get_rollback_status_reason(stack_name: str) → str | None

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.

get_stack(stack_name: str, *_args: Any, **_kwargs: Any) → StackTypeDef

Get stack.

get_stack_changes(stack: Stack, template: Template, parameters: list[ParameterTypeDef], tags: list[TagTypeDef]) → dict[str, str]

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.

get_stack_info(stack: StackTypeDef) → tuple[str, dict[str, list[str] | str]]

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

static get_stack_name(stack: StackTypeDef) → str

Get stack name.

static get_stack_status(stack: StackTypeDef, *_args: Any, **_kwargs: Any) → str

Get stack status.

static get_stack_status_reason(stack: StackTypeDef) → str | None

Get stack status reason.

static get_stack_tags(stack: StackTypeDef) → list[TagTypeDef]

Get stack tags.

interactive_destroy_stack(fqn: str, approval: str | None = None, **kwargs: Any) → None

Delete a CloudFormation stack in interactive mode.

Parameters:

• fqn – A fully qualified stack name.

• approval – Response to approval prompt.

• **kwargs – Arbitrary keyword arguments.

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

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.

is_stack_being_destroyed(stack: StackTypeDef) → bool

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

is_stack_completed(stack: StackTypeDef) → bool

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

is_stack_destroy_possible(stack: StackTypeDef) → bool

Whether the status of the stack is able to be cleanly deleted.

is_stack_destroyed(stack: StackTypeDef) → bool

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

is_stack_failed(stack: StackTypeDef) → bool

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

is_stack_in_progress(stack: StackTypeDef) → bool

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

is_stack_in_review(stack: StackTypeDef) → bool

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

is_stack_recreatable(stack: StackTypeDef) → bool

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

is_stack_rolling_back(stack: StackTypeDef) → bool

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

noninteractive_changeset_update(fqn: str, template: Template, old_parameters: list[ParameterTypeDef], parameters: list[ParameterTypeDef], stack_policy: Template | None, tags: list[TagTypeDef]) → None

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.

noninteractive_destroy_stack(fqn: str, *, allow_disable_termination_protection: bool = True, **_kwargs: Any) → None

Delete a CloudFormation stack without interaction.

Parameters:

• fqn – A fully qualified stack name.

• allow_disable_termination_protection – Whether to disable termination protection if deletion fails do to it being enable. Termination protection will only be disable if the Stack’s state would typically allow for recreation.

static params_as_dict(parameters_list: list[ParameterTypeDef]) → dict[str, list[str] | str]

Parameters as dict.

prepare_stack_for_update(stack: StackTypeDef, tags: list[TagTypeDef]) → bool

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

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

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.

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

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

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

Show and then tail the event log.

tail_stack(stack: Stack, cancel: threading.Event, action: str | None = None, log_func: Callable[[StackEventTypeDef], None] | None = None, retries: int | None = None) → None

Tail the events of a stack.

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: Template | None = None, termination_protection: bool = False, **kwargs: Any) → None

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.

• **kwargs – Arbitrary keyword arguments.

update_termination_protection(fqn: str, termination_protection: bool) → None

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.

class runway.cfngin.providers.aws.default.ProviderBuilder

Bases: object

Implements a Memorized ProviderBuilder for the AWS provider.

__init__(*, region: str | None = None, **kwargs: Any) → None

Instantiate class.

build(*, profile: str | None = None, region: str | None = None) → Provider

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

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

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.check_tags_contain(actual: list[TagTypeDef], expected: list[TagTypeDef]) → bool

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.create_change_set(cfn_client: CloudFormationClient, fqn: str, template: Template, parameters: list[ParameterTypeDef], tags: list[TagTypeDef], change_set_type: str = 'UPDATE', service_role: str | None = None) → tuple[list[ChangeTypeDef], str]

Create CloudFormation change set.

runway.cfngin.providers.aws.default.format_params_diff(params_diff: list[DictValue[Any, Any]]) → str

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

runway.cfngin.providers.aws.default.generate_cloudformation_args(stack_name: str, parameters: list[ParameterTypeDef], tags: list[TagTypeDef], template: Template, capabilities: list[str] | None = None, change_set_type: str | None = None, service_role: str | None = None, stack_policy: Template | None = None, change_set_name: str | None = None) → dict[str, Any]

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: Template | None = None) → dict[str, str]

Convert a stack policy object into keyword args.

Parameters:

stack_policy – A template object representing a stack policy.

runway.cfngin.providers.aws.default.get_change_set_name() → str

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.get_cloudformation_client(session: boto3.Session) → CloudFormationClient

Get CloudFormation boto3 client.

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

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.output_full_changeset(full_changeset: list[ChangeTypeDef] | None = None, params_diff: list[DictValue[Any, Any]] | None = None, answer: str | None = None, fqn: str | None = None) → None

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.output_summary(fqn: str, action: str, changeset: list[ChangeTypeDef], params_diff: list[DictValue[Any, Any]], replacements_only: bool = False) → None

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.requires_replacement(changeset: list[ChangeTypeDef]) → list[ChangeTypeDef]

Return the changes within the changeset that require replacement.

Parameters:

changeset – List of changes

runway.cfngin.providers.aws.default.s3_fallback(fqn: str, template: Template, parameters: list[ParameterTypeDef], tags: list[TagTypeDef], method: Callable[..., Any], change_set_name: str | None = None, service_role: str | None = None) → Any

Falling back to legacy CFNgin S3 bucket region for templates.

runway.cfngin.providers.aws.default.summarize_params_diff(params_diff: list[DictValue[Any, Any]]) → str

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

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