runway.cfngin.blueprints.base module

CFNgin blueprint base classes.

class runway.cfngin.blueprints.base.CFNParameter(name, value)

Bases: object

Wrapper around a value to indicate a CloudFormation Parameter.

Instantiate class.

Parameters

• name (str) – The name of the CloudFormation Parameter.

• value (Any) – The value we’re going to submit as a CloudFormation Parameter.

to_parameter_value()

Return the value to be submitted to CloudFormation.

property ref

Ref the value of a parameter.

Returns

Ref for the parameter.

Return type

troposphere.Ref

runway.cfngin.blueprints.base.build_parameter(name, properties)

Build a troposphere Parameter with the given properties.

Parameters

• name (str) – The name of the parameter.

• properties (Dict[str, Any]) – 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.

Return type

troposphere.Parameter

runway.cfngin.blueprints.base.validate_variable_type(var_name, var_type, value)

Ensure the value is the correct variable type.

Parameters

• var_name (str) – The name of the defined variable on a blueprint.

• var_type (type) – The type that the value should be.

• value (Any) – 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.

Return type

Any

Raises

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

runway.cfngin.blueprints.base.validate_allowed_values(allowed_values, value)

Support a variable defining which values it allows.

Parameters

• allowed_values (Optional[List[Any]]) – A list of allowed values from the variable definition.

• value (Any) – The object representing the value provided for the variable.

Returns

Boolean for whether or not the value is valid.

Return type

bool

runway.cfngin.blueprints.base.resolve_variable(var_name, var_def, provided_variable, blueprint_name)

Resolve a provided variable value against the variable definition.

Parameters

• var_name (str) – The name of the defined variable on a blueprint.

• var_def (Dict[str, Any]) – A dictionary representing the defined variables attributes.

• provided_variable (runway.cfngin.variables.Variable) – The variable value provided to the blueprint.

• blueprint_name (str) – The name of the blueprint that the variable is being applied to.

Returns

The resolved variable value, could be any python object.

Return type

Any

Raises

• MissingVariable – Raised when a variable with no default is not provided a value.

• UnresolvedVariable – 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.parse_user_data(variables, raw_user_data, blueprint_name)

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 (Dict[str, Any]) – Variables available to the template.

• raw_user_data (str) – The user_data to be parsed.

• blueprint_name (str) – The name of the blueprint.

Returns

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

Return type

str

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

class runway.cfngin.blueprints.base.Blueprint(name, context, mappings=None, description=None)

Bases: object

Base implementation for rendering a troposphere template.

Instantiate class.

Parameters

• name (str) – A name for the blueprint.

• context (runway.cfngin.context.Context) – Context the blueprint is being executed under.

• mappings (dict, optional) – CloudFormation Mappings to be used in the template.

• description (str) – Used to describe the resulting CloudFormation template.

get_parameter_definitions()

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.

Returns

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

Return type

Dict[str, Dict[str, str]]

get_output_definitions()

Get the output definitions.

Returns

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

Return type

Dict[str, Dict[str, str]]

get_required_parameter_definitions()

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

Returns

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

Return type

Dict[str, Dict[str, str]]

get_parameter_values()

Return a dictionary of variables with type CFNType.

Returns

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

Return type

Dict[str, str]

setup_parameters()

Add any CloudFormation parameters to the template.

defined_variables()

Return a dictionary of variables defined by the blueprint.

By default, this will just return the values from VARIABLES, but this makes it easy for subclasses to add variables.

Returns

Variables defined by the blueprint.

Return type

Dict[str, Any]

get_variables()

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.

Returns

Variables available to the template.

Return type

Dict[str, Variable]

Raises

UnresolvedVariables – If variables are unresolved.

get_cfn_parameters()

Return a dictionary of variables with type CFNType.

Returns

variables that need to be submitted as CloudFormation Parameters.

Return type

Dict[str, Any]

resolve_variables(provided_variables)

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[runway.cfngin.variables.Variable]) – List of provided variables.

import_mappings()

Import mappings from CFNgin config to the blueprint.

reset_template()

Reset template.

render_template()

Render the Blueprint to a CloudFormation template.

to_json(variables=None)

Render the blueprint and return the template in json form.

Parameters

variables (Optional[Dict[str, Any]]) – Dictionary providing/overriding variable values.

Returns

Rhe rendered CFN JSON template.

Return type

str

read_user_data(user_data_path)

Read and parse a user_data file.

Parameters

user_data_path (str) – Path to the userdata file.

Returns

The parsed user data file.

Return type

str

set_template_description(description)

Add a description to the Template.

Parameters

description (str) – A description to be added to the resulting template.

add_output(name, value)

Add an output to the template.

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

Parameters

• name (str) – The name of the output to create.

• value (str) – The value to put in the output.

property requires_change_set

Return true if the underlying template has transforms.

property rendered

Return rendered blueprint.

property version

Template version.

create_template()

Abstract method called to create a template from the blueprint..