API Reference¶
cfn_pyplates¶
pyplates: CloudFormation templates, generated with python
See also:
- https://aws.amazon.com/cloudformation/
- https://cfn-pyplates.readthedocs.org/ (you might already be here)
- https://github.com/seandst/cfn-pyplates/
cfn_pyplates.cli¶
CLI Entry points for handy bins
Documentation for CLI methods defined in this file will be that method’s usage information as seen on the command-line.
- cfn_pyplates.cli.generate()[source]¶
Generate CloudFormation JSON Template based on a Pyplate
Usage:
cfn_py_generate <pyplate> [<outfile>] [-o/--options=<options_mapping>] cfn_py_generate (-h|--help) cfn_py_generate --version
- Arguments:
- pyplate
- Input pyplate file name
- outfile
- File in which to place the compiled JSON template (if omitted or ‘-‘, outputs to stdout)
- Options:
- -o –options=<options_mapping>
- Input JSON or YAML file for options mapping exposed in the pyplate as “options_mapping” (if ‘-‘, accepts input from stdin)
- -h –help
- This usage information
WARNING!
Do not use pyplates that you haven’t personally examined!
A pyplate is a crazy hybrid of JSON-looking python. exec is used to read the pyplate, so any code in there is going to run, even potentailly harmful things.
Be careful.
cfn_pyplates.core¶
Core functionality and all required components of a working CFN template.
These are all available without preamble in a pyplate’s global namespace.
- class cfn_pyplates.core.JSONableDict(update_dict=None, name=None)[source]¶
A dictionary that knows how to turn itself into JSON
Parameters: - update_dict – A dictionary of values for prepopulating the JSONableDict at instantiation
- name – An optional name. If left out, the class’s (or subclass’s) name will be used.
The most common use-case of any JSON entry in a CFN Template is the {"Name": {"Key1": "Value1", "Key2": Value2"} } pattern. The significance of a JSONableDict’s subclass name, or explicitly passing a ‘name’ argument is accomodating this pattern. All JSONableDicts have names.
To create the pyplate equivalent of the above JSON, contruct a JSONableDict accordingly:
JSONableDict({'Key1': 'Value1', 'Key2', 'Value2'}, 'Name'})
Based on ordereddict.OrderedDict, the order of keys is significant.
- name¶
Accessor to the name internals;
Allows getting, settings, and deleting the name
- add(child)[source]¶
Add a child node
Parameters: child – An instance of JSONableDict Raises: AddRemoveError - cfn_pyplates.exceptions.AddRemoveError
- remove(child)[source]¶
Remove a child node
Parameters: child – An instance of JSONableDict Raises: AddRemoveError - cfn_pyplates.exceptions.AddRemoveError
- class cfn_pyplates.core.CloudFormationTemplate(description=None, options=None)[source]¶
The root element of a CloudFormation template
Takes an option description string in the constructor Comes pre-loaded with all the subelements CloudFormation can stand:
- Parameters
- Mappings
- Resources
- Outputs
- Conditions
For more information, see the AWS docs
- class cfn_pyplates.core.Parameters(update_dict=None, name=None)[source]¶
The base Container for parameters used at stack creation
Attached to a cfn_pyplates.core.CloudFormationTemplate
For more information, see the AWS docs
- class cfn_pyplates.core.Mappings(update_dict=None, name=None)[source]¶
The base Container for stack option mappings
Note
Since most lookups can be done inside a pyplate using python, this is normally unused.
Attached to a cfn_pyplates.core.CloudFormationTemplate
For more information, see the AWS docs
- class cfn_pyplates.core.Resources(update_dict=None, name=None)[source]¶
The base Container for stack resources
Attached to a cfn_pyplates.core.CloudFormationTemplate
For more information, see the AWS docs
- class cfn_pyplates.core.Outputs(update_dict=None, name=None)[source]¶
The base Container for stack outputs
Attached to a cfn_pyplates.core.CloudFormationTemplate
For more information, see the AWS docs
- class cfn_pyplates.core.Conditions(update_dict=None, name=None)[source]¶
The base Container for stack conditions used at stack creation
Attached to a cfn_pyplates.core.CloudFormationTemplate
For more information, see the AWS docs
- class cfn_pyplates.core.Properties(update_dict=None, name=None)[source]¶
A properties mapping, used by various CFN declarations
Can be found in:
Properties will be most commonly found in Resources
For more information, see the AWS docs
- class cfn_pyplates.core.Resource(name, type, properties=None, attributes=[])[source]¶
A generic CFN Resource
Used in the cfn_pyplates.core.Resources container.
All resources have a name, and most have a ‘Type’ and ‘Properties’ dict. Thus, this class takes those as arguments and makes a generic resource.
The ‘name’ parameter must follow CFN’s guidelines for naming The ‘type’ parameter must be one of these
The optional ‘properties’ parameter is a dictionary of properties as defined by the resource type, see documentation related to each resource type
Parameters: - name – The unique name of the resource to add
- type – The type of this resource
- properties – Optional properties mapping to apply to this resource, can be an instance of JSONableDict or just plain old dict
- attributes – Optional (one of ‘Condition’, ‘DependsOn’, ‘DeletionPolicy’, ‘Metadata’, ‘UpdatePolicy’ or a list of 2 or more)
For more information, see the AWS docs
- class cfn_pyplates.core.Parameter(name, type, properties=None)[source]¶
A CFN Parameter
Used in the cfn_pyplates.core.Parameters container, a Parameter will be used when the template is processed by CloudFormation to prompt the user for any additional input.
For more information, see the AWS docs
Parameters: - name – The unique name of the parameter to add
- type – The type of this parameter
- properties – Optional properties mapping to apply to this parameter
- class cfn_pyplates.core.Mapping(name, mappings=None)[source]¶
A CFN Mapping
Used in the cfn_pyplates.core.Mappings container, a Mapping defines mappings used within the Cloudformation template and is not the same as a PyPlates options mapping.
For more information, see the AWS docs
Parameters: - name – The unique name of the mapping to add
- mappings – The dictionary of mappings
- class cfn_pyplates.core.Output(name, value, description=None)[source]¶
A CFN Output
Used in the cfn_pyplates.core.Outputs, an Output entry describes a value to be shown when describe this stack using CFN API tools.
For more information, see the AWS docs
Parameters: - name – The unique name of the output
- value – The value the output should return
- description – An optional description of this output
- class cfn_pyplates.core.Metadata(metadata)[source]¶
CFN Resource Metadata
Used in the cfn_pyplates.core.Resource,The Metadata attribute enables you to associate structured data with a resource. By adding a Metadata attribute to a resource, you can add data in JSON format to the resource declaration. In addition, you can use intrinsic functions (such as GetAtt and Ref), parameters, and pseudo parameters within the Metadata attribute to add those interpreted values.
For more information, see the AWS docs
Parameters: properties – The unique name of the output
- class cfn_pyplates.core.DependsOn(policy=None)[source]¶
A CFN Resource Dependency
Used in the cfn_pyplates.core.Resource, The DependsOn attribute enables you to specify that the creation of a specific resource follows another
For more information, see the AWS docs
Parameters: properties – The unique name of the output
- class cfn_pyplates.core.DeletionPolicy(policy=None)[source]¶
A CFN Resource Deletion Policy
Used in the cfn_pyplates.core.Resource, The DeletionPolicy attribute enables you to specify how AWS CloudFormation handles the resource deletion.
For more information, see the AWS docs
Parameters: properties – The unique name of the output
- class cfn_pyplates.core.UpdatePolicy(properties=None)[source]¶
A CFN Resource Update Policy
Used in the cfn_pyplates.core.Resource, The UpdatePolicy attribute enables you to specify how AWS CloudFormation handles rolling updates for a particular resource.
For more information, see the AWS docs
Parameters: properties – The unique name of the output
- class cfn_pyplates.core.Condition(name, condition)[source]¶
A CFN Condition Item
Used in the cfn_pyplates.core.Condition container, a ConditionItem will be used when the template is processed by CloudFormation so you can define which resources are created and how they’re configured for each environment type.
Conditions are made up of instrinsic functions for conditions found in cfn_pyplates.functions, or a ref to a Parameter or Mapping.
For more information, see the AWS docs
Parameters: - name – The unique name of the ConditionItem to add
- type – The type of this parameter
- properties – The Intrinsic Conditional function
A container for Tags on EC2 Instances
Tags are declared really verbosely in CFN templates, but we have opportunites in the land of python to keep things a little more sane.
So we can turn the AWS EC2 Tags example from this:
"Tags": [ { "Key" : "Role", "Value": "Test Instance" }, { "Key" : "Application", "Value" : { "Ref" : "AWS::StackName"} } ]
Into this:
ec2_tags({ 'Role': 'Test Instance', 'Application': ref('StackName'), })
For more information, see the AWS docs
Parameters: tags – A dictionary of tags to apply to an EC2 instance
cfn_pyplates.exceptions¶
- exception cfn_pyplates.exceptions.Error(message=None, *args)[source]¶
Base exception class for cfn_pyplates
A namespaced Exception subclass with explicit ‘message’ support. Will be handled at template generation, with the message being delivered to the user.
Parameters: - message – An optional message to package with the Error
- args – Any number of optional arguments, to be used as subclasses see fit.
cfn_pyplates.functions¶
Python wrappers for CloudFormation intrinsic functions
These are all available without preamble in a pyplate’s global namespace.
These help make the pyplate look a little more like python than JSON, and can be ignored if you want to write the raw JSON directly. (But you don’t want that, right? After all, that’s why you’re using pyplates.)
Notes:
- All “Return” values are a little midleading, in that what really gets returned is the JSON-ified CFN intrinsic function. When using these in pyplates, though, it’s probably easiest to forget that and only be concerned with how CFN will handle this, hence the Return values.
- To avoid the issue of using the wrong types with functions that take sequences as input (join, select), argument unpacking is used. Therefore, pass the sequence elements one at a time, rather than the sequence itself, after passing the separator (for join) or index (for select).
- Using CloudFormation’s Join function versus a pythonic ‘string’.join allows you to use CFN’s intrinsic functions inside a join statement. The pythonic string join method may literally interpret a call to an intrinsic function, causing the resulting JSON to be interpreted as a string and ignored by the CloudFormation template parser
- Functions related to conditions tend to overlap with python keywords, so they are prefixed with c_ to differentiate them (so, Fn::And become c_and)
- cfn_pyplates.functions.base64(value)[source]¶
The intrinsic function Fn::Base64 returns the Base64 representation of the input string.
This function is typically used to pass encoded data to Amazon EC2 instances by way of the UserData property.
Parameters: value – The string value you want to convert to Base64 Returns: The original string, in Base64 representation
- cfn_pyplates.functions.find_in_map(map_name, key, value)[source]¶
The intrinsic function Fn::FindInMap returns the value of a key from a mapping declared in the Mappings section.
Parameters: - map_name – The logical name of the mapping declared in the Mappings section that contains the key-value pair.
- key – The name of the mapping key whose value you want.
- value – The value for the named mapping key.
Returns: The map value.
- cfn_pyplates.functions.get_att(logical_name, attribute)[source]¶
The intrinsic function Fn:GetAtt returns the value of an attribute from a resource in the template.
param logical_name: The logical name of the resource that contains the attribute you want. param attribute: The name of the resource-specific attribute whose value you want. See the resource’s reference - page
- [#cfn-resources] for details about the attributes available for that resource type.
returns: The attribute value.
- cfn_pyplates.functions.get_azs(region='')[source]¶
The intrinsic function Fn::GetAZs returns an array that lists all Availability Zones for the specified region.
Because customers have access to different Availability Zones, the intrinsic function Fn::GetAZs enables template authors to write templates that adapt to the calling user’s access. This frees you from having to hard-code a full list of Availability Zones for a specified region.
Parameters: region – The name of the region for which you want to get the Availability Zones. You can use the AWS::Region pseudo parameter to specify the region in which the stack is created. Specifying an empty string is equivalent to specifying AWS::Region. Returns: The list of Availability Zones for the region.
- cfn_pyplates.functions.join(sep, *args)[source]¶
The intrinsic function Fn::Join appends a set of values into a single value, separated by the specified delimiter.
If a delimiter is the empty string, the set of values are concatenated with no delimiter.
Parameters: - delimiter – The value you want to occur between fragments. The delimiter will occur between fragments only. It will not terminate the final value.
- *args – Any number of values you want combined, passed as positional arguments
Returns: The combined string.
- cfn_pyplates.functions.select(index, *args)[source]¶
The intrinsic function Fn::Select returns a single object from a list of objects by index.
Warning
Important Fn::Select does not check for null values or if the index is out of bounds of the array. Both conditions will result in a stack error, so you should be certain that the index you choose is valid, and that the list contains non-null values.
Parameters: - index – The index of the object to retrieve. This must be a value from zero to N-1, where N represents the number of elements in the array.
- *args – Any number of objects to select from, passed as positional arguments. None of the arguments can be None
Returns: The selected object.
- cfn_pyplates.functions.ref(logical_name)[source]¶
The intrinsic function Ref returns the value of the specified parameter or resource.
When you are declaring a resource in a template and you need to specify another template resource by name, you can use the Ref to refer to that other resource. In general, Ref returns the name of the resource. For example, a reference to an AWS::AutoScaling::AutoScalingGroup returns the name of that Auto Scaling group resource.
For some resources, an identifier is returned that has another significant meaning in the context of the resource. An AWS::EC2::EIP resource, for instance, returns the IP address, and an AWS::EC2::Instance returns the instance ID.
Parameters: logical_name – The logical name of the resource or parameter you want to dereference. Returns: - When you specify a parameter’s logical name, it returns the value
- of the parameter.
- When you specify a resource’s logical name, it returns a value
- that you can typically use to refer to that resource.
Note
You can also use Ref to add values to Output messages.
- cfn_pyplates.functions.c_ref(condition_name)[source]¶
The intrinsic function Condition used to reference a named condition
When you refer to a condition in another condition or associate the condition with a resource, you use the Condition: key. For the Fn::If function, you only need to specify the condition name.
Parameters: condition_name – The name of the condition you want to reference. Returns: - A reference to the named condition
- cfn_pyplates.functions.c_and(*conditions)[source]¶
The intrinsic conditional function Fn::And
Returns true (for the pruposes of the cfn template) if all the specified conditions evaluate to true, or returns false if any one of the conditions evaluates to false.
Fn::And acts as an AND operator.
The minimum number of conditions that you can include is 2, and the maximum is 10.
Parameters: *conditions – The conditions to evaluate
- cfn_pyplates.functions.c_or(*conditions)[source]¶
The intrinsic conditional function Fn::Or
Returns true (for the pruposes of the cfn template) if any one of the specified conditions evaluate to true, or returns false if all of the conditions evaluates to false.
Fn::Or acts as an OR operator.
The minimum number of conditions that you can include is 2, and the maximum is 10.
Parameters: *conditions – The conditions to evaluate
- cfn_pyplates.functions.c_not(condition)[source]¶
The intrinsic conditional function Fn::Not
Returns true for a condition that evaluates to false or returns false for a condition that evaluates to true.
Fn::Not acts as a NOT operator.
- cfn_pyplates.functions.c_equals(value_1, value_2)[source]¶
The intrinsic conditional function Fn::Equals
Compares if two values are equal.
Returns true if the two values are equal or false if they aren’t.
- cfn_pyplates.functions.c_if(condition_name, value_if_true, value_if_false)[source]¶
The intrinsic conditional function Fn::If representsa a ternary conditional operator
Returns one value if the specified condition evaluates to true and another value if the specified condition evaluates to false.
Currently, AWS CloudFormation supports the Fn::If intrinsic function in the metadata attribute, update policy attribute, and property values in the Resources section and Outputs sections of a template.
You can use the AWS::NoValue pseudo parameter as a return value to remove the corresponding property.