Skip to content
troposphere - Python library to create AWS CloudFormation descriptions
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
docs Add new AWS::RAM and AWS::RoboMaker resources Feb 22, 2019
examples Add SSM Example for patch baselines and filter groups (#1274) Jan 8, 2019
scripts Generate class stubs necessary for autocompletion (#1079) Jul 30, 2018
tests Exclude OpenStack modules within the template generator (#1319) Feb 18, 2019
troposphere Update the instance types in constants. (#1353) Mar 22, 2019
.editorconfig
.gitignore Sphinx docs (#1311) Feb 10, 2019
.travis.yml Discourage usage of Python 3.4 (#1326) Feb 20, 2019
CHANGELOG.rst
CODE_OF_CONDUCT.rst
CONTRIBUTE.rst Discourage usage of Python 3.4 (#1326) Feb 20, 2019
LICENSE Release 1.9.3 Apr 14, 2017
MANIFEST.in
Makefile
README.rst Add new AWS::RAM and AWS::RoboMaker resources Feb 22, 2019
RELEASE.rst Add "pip install" step for source dist file before a release (#1318) Feb 19, 2019
requirements-dev.txt
requirements.txt Remove awacs as a hard dependency; ensure awacs>=0.8 otherwise (#1325) Feb 19, 2019
setup.py Discourage usage of Python 3.4 (#1326) Feb 20, 2019
tox.ini Setup tox (#1187) Nov 18, 2018

README.rst

troposphere

PyPI Version Build Status license: New BSD license Documentation Status

About

troposphere - library to create AWS CloudFormation descriptions

The troposphere library allows for easier creation of the AWS CloudFormation JSON by writing Python code to describe the AWS resources. troposphere also includes some basic support for OpenStack resources via Heat.

To facilitate catching CloudFormation or JSON errors early the library has property and type checking built into the classes.

Installation

troposphere can be installed using the pip distribution system for Python by issuing:

$ pip install troposphere

To install troposphere with awacs (recommended soft dependency):

$ pip install troposphere[policy]

Alternatively, you can run use setup.py to install by cloning this repository and issuing:

$ python setup.py install  # you may need sudo depending on your python installation

Examples

A simple example to create an instance would look like this:

>>> from troposphere import Ref, Template
>>> import troposphere.ec2 as ec2
>>> t = Template()
>>> instance = ec2.Instance("myinstance")
>>> instance.ImageId = "ami-951945d0"
>>> instance.InstanceType = "t1.micro"
>>> t.add_resource(instance)
<troposphere.ec2.Instance object at 0x101bf3390>
>>> print(t.to_json())
{
    "Resources": {
        "myinstance": {
            "Properties": {
                "ImageId": "ami-951945d0",
                "InstanceType": "t1.micro"
            },
            "Type": "AWS::EC2::Instance"
        }
    }
}

A simple example to create an instance (YAML) would look like this:

>>> from troposphere import Ref, Template
>>> import troposphere.ec2 as ec2
>>> t = Template()
>>> instance = ec2.Instance("myinstance")
>>> instance.ImageId = "ami-951945d0"
>>> instance.InstanceType = "t1.micro"
>>> t.add_resource(instance)
<troposphere.ec2.Instance object at 0x101bf3390>
>>> print(t.to_yaml())

Resources:
    myinstance:
        Properties:
            ImageId: ami-951945d0
            InstanceType: t1.micro
        Type: AWS::EC2::Instance

Alternatively, parameters can be used instead of properties:

>>> instance = ec2.Instance("myinstance", ImageId="ami-951945d0", InstanceType="t1.micro")
>>> t.add_resource(instance)
<troposphere.ec2.Instance object at 0x101bf3550>

And add_resource() returns the object to make it easy to use with Ref():

>>> instance = t.add_resource(ec2.Instance("myinstance", ImageId="ami-951945d0", InstanceType="t1.micro"))
>>> Ref(instance)
<troposphere.Ref object at 0x101bf3490>

Examples of the error checking (full tracebacks removed for clarity):

Incorrect property being set on AWS resource:

>>> import troposphere.ec2 as ec2
>>> ec2.Instance("ec2instance", image="i-XXXX")
Traceback (most recent call last):
...
AttributeError: AWS::EC2::Instance object does not support attribute image

Incorrect type for AWS resource property:

>>> ec2.Instance("ec2instance", ImageId=1)
Traceback (most recent call last):
...
TypeError: ImageId is <type 'int'>, expected <type 'basestring'>

Missing required property for the AWS resource:

>>> from troposphere import Template
>>> import troposphere.ec2 as ec2
>>> t = Template()
>>> t.add_resource(ec2.Instance("ec2instance", InstanceType="m3.medium"))
<troposphere.ec2.Instance object at 0x109ee2e50>
>>> print(t.to_json())
Traceback (most recent call last):
...
ValueError: Resource ImageId required in type AWS::EC2::Instance

Currently supported AWS resource types

  • AWS::AmazonMQ
  • AWS::ApiGateway
  • AWS::ApiGatewayV2
  • AWS::AppStream
  • AWS::AppSync
  • AWS::ApplicationAutoScaling
  • AWS::Athena
  • AWS::AutoScaling
  • AWS::AutoScalingPlans
  • AWS::Batch
  • AWS::Budgets
  • AWS::CertificateManager
  • AWS::Cloud9
  • AWS::CloudFormation
  • AWS::CloudFront
  • AWS::CloudTrail
  • AWS::CloudWatch
  • AWS::CodeBuild
  • AWS::CodeCommit
  • AWS::CodeDeploy
  • AWS::CodePipeline
  • AWS::Cognito
  • AWS::Config
  • AWS::DAX
  • AWS::DLM
  • AWS::DMS
  • AWS::DataPipeline
  • AWS::DirectoryService
  • AWS::DocDB
  • AWS::DynamoDB
  • AWS::EC2
  • AWS::ECR
  • AWS::ECS
  • AWS::EFS
  • AWS::EKS
  • AWS::EMR
  • AWS::ElastiCache
  • AWS::ElasticBeanstalk
  • AWS::ElasticLoadBalancing
  • AWS::ElasticLoadBalancingV2
  • AWS::Elasticsearch
  • AWS::Events
  • AWS::FSx
  • AWS::Glue
  • AWS::GuardDuty
  • AWS::IAM
  • AWS::Inspector
  • AWS::IoT
  • AWS::IoT1Click
  • AWS::IoTAnalytics
  • AWS::KMS
  • AWS::Kinesis
  • AWS::KinesisAnalytics
  • AWS::KinesisAnalyticsV2
  • AWS::KinesisFirehose
  • AWS::Lambda
  • AWS::Logs
  • AWS::Neptune
  • AWS::OpsWorks
  • AWS::OpsWorksCM
  • AWS::RAM
  • AWS::RDS
  • AWS::Redshift
  • AWS::RoboMaker
  • AWS::Route53
  • AWS::Route53Resolver
  • AWS::S3
  • AWS::SDB
  • AWS::SES
  • AWS::SNS
  • AWS::SQS
  • AWS::SSM
  • AWS::SageMaker
  • AWS::SecretsManager
  • AWS::Serverless
  • AWS::ServiceCatalog
  • AWS::ServiceDiscovery
  • AWS::StepFunctions
  • AWS::WAF
  • AWS::WAFRegional
  • AWS::WorkSpaces

Currently supported OpenStack resource types

  • OS::Neutron::Firewall
  • OS::Neutron::FirewallPolicy
  • OS::Neutron::FirewallRule
  • OS::Neutron::FloatingIP
  • OS::Neutron::FloatingIPAssociation
  • OS::Neutron::HealthMonitor
  • OS::Neutron::Pool
  • OS::Neutron::LoadBalancer
  • OS::Neutron::Net
  • OS::Neutron::PoolMember
  • OS::Neutron::Port
  • OS::Neutron::SecurityGroup
  • OS::Nova::FloatingIP
  • OS::Nova::FloatingIPAssociation
  • OS::Nova::KeyPair
  • OS::Nova::Server

Todo:

  • Add additional validity checks

Duplicating a single instance sample would look like this

# Converted from EC2InstanceSample.template located at:
# http://aws.amazon.com/cloudformation/aws-cloudformation-templates/

from troposphere import Base64, FindInMap, GetAtt
from troposphere import Parameter, Output, Ref, Template
import troposphere.ec2 as ec2


template = Template()

keyname_param = template.add_parameter(Parameter(
    "KeyName",
    Description="Name of an existing EC2 KeyPair to enable SSH "
                "access to the instance",
    Type="String",
))

template.add_mapping('RegionMap', {
    "us-east-1":      {"AMI": "ami-7f418316"},
    "us-west-1":      {"AMI": "ami-951945d0"},
    "us-west-2":      {"AMI": "ami-16fd7026"},
    "eu-west-1":      {"AMI": "ami-24506250"},
    "sa-east-1":      {"AMI": "ami-3e3be423"},
    "ap-southeast-1": {"AMI": "ami-74dda626"},
    "ap-northeast-1": {"AMI": "ami-dcfa4edd"}
})

ec2_instance = template.add_resource(ec2.Instance(
    "Ec2Instance",
    ImageId=FindInMap("RegionMap", Ref("AWS::Region"), "AMI"),
    InstanceType="t1.micro",
    KeyName=Ref(keyname_param),
    SecurityGroups=["default"],
    UserData=Base64("80")
))

template.add_output([
    Output(
        "InstanceId",
        Description="InstanceId of the newly created EC2 instance",
        Value=Ref(ec2_instance),
    ),
    Output(
        "AZ",
        Description="Availability Zone of the newly created EC2 instance",
        Value=GetAtt(ec2_instance, "AvailabilityZone"),
    ),
    Output(
        "PublicIP",
        Description="Public IP address of the newly created EC2 instance",
        Value=GetAtt(ec2_instance, "PublicIp"),
    ),
    Output(
        "PrivateIP",
        Description="Private IP address of the newly created EC2 instance",
        Value=GetAtt(ec2_instance, "PrivateIp"),
    ),
    Output(
        "PublicDNS",
        Description="Public DNSName of the newly created EC2 instance",
        Value=GetAtt(ec2_instance, "PublicDnsName"),
    ),
    Output(
        "PrivateDNS",
        Description="Private DNSName of the newly created EC2 instance",
        Value=GetAtt(ec2_instance, "PrivateDnsName"),
    ),
])

print(template.to_json())

Community

We have a Google Group, cloudtools-dev, where you can ask questions and engage with the troposphere community. Issues and pull requests are always welcome!

Licensing

troposphere is licensed under the BSD 2-Clause license. See LICENSE for the troposphere full license text.

You can’t perform that action at this time.