env¶

AWS Environment and Deployment component.

cottonformation.core.env.md5_of_text(text: str) → str[source]¶: Return md5 of text.

cottonformation.core.env.detect_template_type(template: str) → str[source]¶

Detect whether CloudFormation template is JSON or YAML.

Returns: “json” or “yaml”

class cottonformation.core.env.Env(bsm: BotoSesManager = None, is_us_gov_cloud: bool = False)[source]¶

Environment is simply an abstraction layer with a boto3 session object connected to AWS, allowing you to perform AWS API call.

You are responsible to create you own boto session manager object. You can find more information about BotoSesManager at https://github.com/MacHu-GWU/boto_session_manager-project

Local laptop environment, using default AWS credential based on the
environment variable https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html, or based on the default profile in ~/.aws/credentials:

import boto3

bsm = BotoSesManager()

Local laptop environment, using named profile. You have to configure the
~/.aws/credentials and ~/.aws/config file. Here’s how https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-profiles.html:

bsm = BotoSesManager(profile_name="your_aws_profile")

EC2 or AWS Lambda environment, using IAM role. It is exactly same to #1
Load credential in a secure way, manually pass in credential to the session:

bsm = BotoSesManager(
    aws_access_key_id="your_access_key",
    aws_secret_access_key="your_secret_access_key",
    region_name="us-east-1",
)

New in version 1.0.1.

upload_template(template: cottonformation.core.template.Template, bucket: str, prefix: str = 'cloudformation/template') → Tuple[str, str][source]¶

Upload cloudformation template to s3 bucket and returns template url. It is a format like this https://s3.amazonaws.com/<s3-bucket-name>/<s3-key>

Returns: s3 url of the template file

New in version 1.0.1.

package(template: cottonformation.core.template.Template, bucket: str, prefix: str = 'cloudformation/template', verbose: bool = True, _is_master: bool = True)[source]¶

Automatically upload nested stack template and update template url in your CloudFormation code.

It’s a depth-first-search.

deploy(stack_name: str, template: cottonformation.core.template.Template, use_previous_template: Optional[bool] = Sentinel('NOTHING'), bucket: Optional[str] = Sentinel('NOTHING'), prefix: Optional[str] = 'cloudformation/template', parameters: Optional[List[aws_cloudformation.stack.Parameter]] = Sentinel('NOTHING'), tags: Optional[Dict[str, str]] = Sentinel('NOTHING'), execution_role_arn: Optional[str] = Sentinel('NOTHING'), include_iam: Optional[bool] = Sentinel('NOTHING'), include_named_iam: Optional[bool] = Sentinel('NOTHING'), include_macro: Optional[bool] = Sentinel('NOTHING'), stack_policy: Optional[str] = Sentinel('NOTHING'), prefix_stack_policy: Optional[str] = 'cloudformation/policy', resource_types: Optional[List[str]] = Sentinel('NOTHING'), client_request_token: Optional[str] = Sentinel('NOTHING'), enable_termination_protection: Optional[bool] = Sentinel('NOTHING'), disable_rollback: Optional[bool] = Sentinel('NOTHING'), rollback_configuration: Optional[dict] = Sentinel('NOTHING'), notification_arns: Optional[List[str]] = Sentinel('NOTHING'), on_failure_do_nothing: Optional[bool] = Sentinel('NOTHING'), on_failure_rollback: Optional[bool] = Sentinel('NOTHING'), on_failure_delete: Optional[bool] = Sentinel('NOTHING'), wait: bool = True, delays: Union[int, float] = 5, timeout: Union[int, float] = 60, wait_until_exec_stopped_on_failure: bool = False, plan_nested_stack: bool = True, skip_plan: bool = False, skip_prompt: bool = False, change_set_delays: Union[int, float] = 5, change_set_timeout: Union[int, float] = 60, verbose: bool = True)[source]¶

Deploy (create or update) an AWS CloudFormation stack. But way more powerful than the original boto3 API.

Reference:

Create Stack Boto3 API: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudformation.html#CloudFormation.Client.create_stack
Update Stack Boto3 API: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudformation.html#CloudFormation.Client.update_stack

Parameters

stack_name – the stack name or unique stack id
template – Template object
use_previous_template – see “Update Stack Boto3 API” link
bucket – default None; if given, automatically upload template to S3 before deployment. see upload_template_to_s3() for more details.
prefix – the s3 prefix where you want to upload the template to
parameters – see “Update Stack Boto3 API” link
tags – see “Update Stack Boto3 API” link
execution_role_arn – see “Update Stack Boto3 API” link
include_iam – see “Capacities” part in “Update Stack Boto3 API” link
include_named_iam – see “Capacities” part in “Update Stack Boto3 API” link
include_macro – see “Capacities” part in “Update Stack Boto3 API” link
stack_policy – Stack Policy JSON or Yaml body in text, or the s3 uri pointing to a Stack Policy JSON template file.
prefix_stack_policy – see “Update Stack Boto3 API” link
resource_types – see “Update Stack Boto3 API” link
client_request_token – see “Update Stack Boto3 API” link
enable_termination_protection – see “Create Stack Boto3 API” link
disable_rollback – see “Create Stack Boto3 API” link
rollback_configuration – see “Create Stack Boto3 API” link
notification_arns – see “Create Stack Boto3 API” link
on_failure_do_nothing – only used when you create stack directly, not using change set. If you set skip_plan = True, then this parameter will be ignored.
on_failure_rollback – only used when you create stack directly, not using change set.
on_failure_delete – only used when you create stack directly, this arg will be ignored if it is an update, or using change set.
wait – default True; if True, then wait the create / update action to success or fail; if False, then it is an async call and return immediately; note that if you have skip_plan is False (using change set), you always have to wait the change set creation to finish.
delays – how long it waits (in seconds) between two “describe_stacks” api call to get the stack status
timeout – how long it will raise timeout error
wait_until_exec_stopped_on_failure – if False, it will raise an DeployStackFailedError exception immediately when there is an error and the stack starting to roll back. Note that the stack will take some time to reach stopped status after it failed, you may not to run another deploy immediately. if True, it will raise the exception after the stack reaching stopped status.
plan_nested_stack – do you want to plan change set for nested stack?
skip_plan – default False; if False, force to use change set to create / update; if True, then do create / update without change set.
skip_prompt – default False; if False, you have to enter “Yes” in prompt to do deployment; if True, then execute the deployment directly.
change_set_delays – how long it waits (in seconds) between two “describe_change_set” api call to get the change set status
change_set_timeout – how long it will raise timeout error
verbose – whether you want to log information to console

Returns

Nothing

New in version 1.0.1.

delete(stack_name: str, retain_resources: Optional[List[str]] = Sentinel('NOTHING'), role_arn: Optional[bool] = Sentinel('NOTHING'), client_request_token: Optional[str] = Sentinel('NOTHING'), wait: bool = True, delays: Union[int, float] = 5, timeout: Union[int, float] = 60, wait_until_exec_stopped_on_failure: bool = False, skip_prompt: bool = False, verbose: bool = True)[source]¶

Delete an AWS CloudFormation Stack.

Reference:

Delete Stack Boto3 API: https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/cloudformation.html#CloudFormation.Client.delete_stack

Parameters

stack_name – the stack name or unique stack id
retain_resources – see “Delete Stack Boto3 API” link
role_arn – see “Delete Stack Boto3 API” link
client_request_token – see “Delete Stack Boto3 API” link
wait – default True; if True, then wait the delete action to success or fail; if False, then it is an async call and return immediately.
delays – how long it waits (in seconds) between two “describe_stacks” api call to get the stack status
timeout – how long it will raise timeout error
wait_until_exec_stopped_on_failure – if False, it will raise an DeleteStackFailedError exception immediately when there is an error and the stack starting to roll back. Note that the stack will take some time to reach stopped status after it failed, you may not to run another deploy immediately. if True, it will raise the exception after the stack reaching stopped status.
skip_prompt – default False; if False, you have to enter “Yes” in prompt to do deletion; if True, then execute the deletion directly.
verbose – whether you want to log information to console

New in version 1.0.1.

validate(template: cottonformation.core.template.Template, bucket: Optional[str] = None, prefix: str = 'cloudformation/template') → dict[source]¶

Validate if a Template object is valid.

TODO: not a stable API

New in version 0.0.8.