runway.cfngin.blueprints.base module¶

CFNgin blueprint base classes.

class runway.cfngin.blueprints.base.Blueprint[source]¶

Bases: DelCachedPropMixin

Base implementation for rendering a troposphere template.

VARIABLES¶

Class variable that defines the values that can be passed from CFNgin to the template. These definition include metadata used to validate the provided value and to propagate the variable to the resulting CloudFormation template.

Type:: ClassVar[dict[str, BlueprintVariableTypeDef]]

context¶

CFNgin context object.

Type:: CfnginContext

description¶

The description of the CloudFormation template that will be generated by this Blueprint.

Type:: str | None

mappings¶

CloudFormation Mappings to be added to the template during the rendering process.

Type:: dict[str, dict[str, Any]] | None

name¶

Name of the Stack that will be created by the Blueprint.

Type:: str

template¶

Troposphere template.

Type:: Template

__init__(name: str, context: runway.context.CfnginContext, *, description: str | None = None, mappings: dict[str, dict[str, Any]] | None = None, template: Template | None = None, **_: Any) → None[source]¶

Instantiate class.

Parameters:

name – A name for the blueprint.
context – Context the blueprint is being executed under.
description – The description of the CloudFormation template that will be generated by this blueprint.
mappings – CloudFormation Mappings to be used in the template during the rendering process.
template – Optionally, provide a preexisting Template.

Changed in version 2.0.0: Added template.

Changed in version 2.0.0: Class only takes 2 positional arguments. The rest are now keyword arguments.

add_output(name: str, value: Any) → None[source]¶

Add an output to the template.

Wrapper for self.template.add_output(Output(name, Value=value)).

Parameters:

name – The name of the output to create.
value – The value to put in the output.

property cfn_parameters: dict[str, list[Any] | str]¶

Return a dict of variables with type CFNType.

Added in version 2.0.0.

Returns:: Variables that need to be submitted as CloudFormation Parameters.

create_template() → None[source]¶: Abstract method called to create a template from the blueprint.

property defined_variables: dict[str, BlueprintVariableTypeDef]¶: Return a copy of VARIABLES to avoid accidental modification of the ClassVar.

Changed in version 2.0.0: Changed from a method to a property.

get_cfn_parameters() → dict[str, list[Any] | str][source]¶

Return a dictionary of variables with type CFNType.

Deprecated since version 2.0.0: Replaced by cfn_parameters.

Returns:: Variables that need to be submitted as CloudFormation Parameters.

get_output_definitions() → dict[str, dict[str, Any]][source]¶

Get the output definitions.

Deprecated since version 2.0.0: Replaced by output_definitions.

Returns:: Output definitions. Keys are output names, the values are dicts containing key/values for various output properties.

get_parameter_definitions() → dict[str, BlueprintVariableTypeDef][source]¶

Get the parameter definitions to submit to CloudFormation.

Any variable definition whose type is an instance of CFNType will be returned as a CloudFormation Parameter.

Deprecated since version 2.0.0: Replaced by parameter_definitions.

Returns:: Parameter definitions. Keys are parameter names, the values are dicts containing key/values for various parameter properties.

get_parameter_values() → dict[str, list[Any] | str][source]¶

Return a dict of variables with type CFNType.

Deprecated since version 2.0.0: Replaced by parameter_values.

Returns:: Variables that need to be submitted as CloudFormation Parameters. Will be a dictionary of <parameter name>: <parameter value>.

get_required_parameter_definitions() → dict[str, BlueprintVariableTypeDef][source]¶

Return all template parameters that do not have a default value.

Deprecated since version 2.0.0: Replaced by required_parameter_definitions.

Returns:: Dict of required CloudFormation Parameters for the blueprint. Will be a dictionary of <parameter name>: <parameter attributes>.

get_variables() → dict[str, Any][source]¶

Return a dictionary of variables available to the template.

These variables will have been defined within VARIABLES or self.defined_variables. Any variable value that contains a lookup will have been resolved.

Deprecated since version 2.0.0: Replaced by variables.

Returns:: Variables available to the template.
Raises:: UnresolvedBlueprintVariables – If variables are unresolved.

import_mappings() → None[source]¶: Import mappings from CFNgin config to the blueprint.

property output_definitions: dict[str, dict[str, Any]]¶

Get the output definitions.

Added in version 2.0.0.

Returns:: Output definitions. Keys are output names, the values are dicts containing key/values for various output properties.

property parameter_definitions: dict[str, BlueprintVariableTypeDef]¶

Get the parameter definitions to submit to CloudFormation.

Any variable definition whose type is an instance of CFNType will be returned as a CloudFormation Parameter.

Added in version 2.0.0.

Returns:: Parameter definitions. Keys are parameter names, the values are dicts containing key/values for various parameter properties.

property parameter_values: dict[str, list[Any] | str]¶

Return a dict of variables with type CFNType.

Added in version 2.0.0.

Returns:: Variables that need to be submitted as CloudFormation Parameters. Will be a dictionary of <parameter name>: <parameter value>.

read_user_data(user_data_path: str) → str[source]¶

Read and parse a user_data file.

Parameters:: user_data_path – Path to the userdata file.

render_template() → tuple[str, str][source]¶: Render the Blueprint to a CloudFormation template.

property rendered: str¶: Return rendered blueprint.

property required_parameter_definitions: dict[str, BlueprintVariableTypeDef]¶

Return all template parameters that do not have a default value.

Added in version 2.0.0.

Returns:: Dict of required CloudFormation Parameters for the blueprint. Will be a dictionary of <parameter name>: <parameter attributes>.

property requires_change_set: bool¶: Return true if the underlying template has transforms.

reset_template() → None[source]¶: Reset template.

resolve_variables(provided_variables: list[Variable]) → None[source]¶

Resolve the values of the blueprint variables.

This will resolve the values of the VARIABLES with values from the env file, the config, and any lookups resolved.

Parameters:: provided_variables – List of provided variables.

set_template_description(description: str) → None[source]¶

Add a description to the Template.

Parameters:: description – A description to be added to the resulting template.

setup_parameters() → None[source]¶: Add any CloudFormation parameters to the template.

to_json(variables: dict[str, Any] | None = None) → str[source]¶

Render the blueprint and return the template in json form.

Parameters:: variables – Dictionary providing/overriding variable values.

property variables: dict[str, Any]¶

Return a Dict of variables available to the Template.

These variables will have been defined within VARIABLES or defined_variables. Any variable value that contains a Lookup will have been resolved.

Added in version 2.0.0.

Returns:: Variables available to the Template.
Raises:: UnresolvedBlueprintVariables – If variables are unresolved.

property version: str¶: Template version.

class runway.cfngin.blueprints.base.CFNParameter[source]¶

Bases: object

Wrapper around a value to indicate a CloudFormation Parameter.

__init__(name: str, value: bool | float | list[Any] | str | Any) → None[source]¶

Instantiate class.

Parameters:

name – The name of the CloudFormation Parameter.
value – The value we’re going to submit as a CloudFormation Parameter.

__repr__() → str[source]¶: Object represented as a string.

property ref: Ref¶: Ref the value of a parameter.

to_parameter_value() → list[Any] | str[source]¶: Return the value to be submitted to CloudFormation.

runway.cfngin.blueprints.base.build_parameter(name: str, properties: BlueprintVariableTypeDef) → Parameter[source]¶

Build a troposphere Parameter with the given properties.

Parameters:

name – The name of the parameter.
properties – Contains the properties that will be applied to the parameter. See: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/parameters-section-structure.html

Returns:

The created parameter object.

runway.cfngin.blueprints.base.parse_user_data(variables: dict[str, Any], raw_user_data: str, blueprint_name: str) → str[source]¶

Parse the given user data and renders it as a template.

It supports referencing template variables to create userdata that’s supplemented with information from the stack, as commonly required when creating EC2 userdata files.

Example

Given a raw_user_data string: 'open file ${file}' And a variables dictionary with: {'file': 'test.txt'} parse_user_data would output: open file test.txt

Parameters:

variables – Variables available to the template.
raw_user_data – The user_data to be parsed.
blueprint_name – The name of the blueprint.

Returns:

The parsed user data, with all the variables values and refs replaced with their resolved values.

Raises:

InvalidUserdataPlaceholder – Raised when a placeholder name in raw_user_data is not valid. E.g ${100} would raise this.
MissingVariable – Raised when a variable is in the raw_user_data that is not given in the blueprint

runway.cfngin.blueprints.base.resolve_variable(var_name: str, var_def: BlueprintVariableTypeDef, provided_variable: Variable | None, blueprint_name: str) → Any[source]¶

Resolve a provided variable value against the variable definition.

Parameters:

var_name – The name of the defined variable on a blueprint.
var_def – A dictionary representing the defined variables attributes.
provided_variable – The variable value provided to the blueprint.
blueprint_name – The name of the blueprint that the variable is being applied to.

Returns:

The resolved variable value, could be any python object.

Raises:

MissingVariable – Raised when a variable with no default is not provided a value.
UnresolvedBlueprintVariable – Raised when the provided variable is not already resolved.
ValueError – Raised when the value is not the right type and cannot be cast as the correct type. Raised by runway.cfngin.blueprints.base.validate_variable_type()
ValidatorError – Raised when a validator raises an exception. Wraps the original exception.

runway.cfngin.blueprints.base.validate_allowed_values(allowed_values: list[Any] | None, value: Any) → bool[source]¶

Support a variable defining which values it allows.

Parameters:

allowed_values – A list of allowed values from the variable definition.
value – The object representing the value provided for the variable.

Returns:

Boolean for whether or not the value is valid.

runway.cfngin.blueprints.base.validate_variable_type(var_name: str, var_type: type[CFNType] | TroposphereType[Any] | type, value: Any) → Any[source]¶

Ensure the value is the correct variable type.

Parameters:

var_name – The name of the defined variable on a blueprint.
var_type – The type that the value should be.
value – The object representing the value provided for the variable

Returns:

The appropriate value object. If the original value was of CFNType, the returned value will be wrapped in CFNParameter.

Raises:

ValueError – If the value isn’t of var_type and can’t be cast as that type, this is raised.