===========
troposphere

.. image:: https://img.shields.io/pypi/v/troposphere.svg
:target: https://pypi.python.org/pypi/troposphere
:alt: PyPI Version

.. image:: https://travis-ci.org/cloudtools/troposphere.svg?branch=master
:target: https://travis-ci.org/cloudtools/troposphere
:alt: Build Status

.. image:: https://img.shields.io/pypi/l/troposphere.svg
:target: https://opensource.org/licenses/BSD-2-Clause
:alt: license: New BSD license

.. image:: https://readthedocs.org/projects/troposphere/badge/?version=latest
:target: https://troposphere.readthedocs.io/en/latest/?badge=latest
:alt: 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:

.. code:: sh

$ pip install troposphere

To install troposphere with awacs <https://github.com/cloudtools/awacs>_
(recommended soft dependency):

.. code:: sh

$ pip install troposphere[policy]

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

.. code:: sh

$ 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:

.. code:: python

>>> 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"
        }
    }
}
>>> 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:

.. code:: python

>>> 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():

.. code:: python

>>> 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:

.. code:: python

>>> 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:

.. code:: python

>>> 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:

.. code:: python

>>> 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::AccessAnalyzer_
AWS::AmazonMQ_
AWS::Amplify_
AWS::ApiGateway_
AWS::ApiGatewayV2_
AWS::AppMesh_
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::CodeStar_
AWS::CodeStarNotifications_
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::EventSchemas_
AWS::FSx_
AWS::GameLift_
AWS::Glue_
AWS::Greengrass_
AWS::GuardDuty_
AWS::IAM_
AWS::Inspector_
AWS::IoT_
AWS::IoT1Click_
AWS::IoTAnalytics_
AWS::IoTEvents_
AWS::KMS_
AWS::Kinesis_
AWS::KinesisAnalytics_
AWS::KinesisAnalyticsV2_
AWS::KinesisFirehose_
AWS::LakeFormation_
AWS::Lambda_
AWS::Logs_
AWS::ManagedBlockchain_
AWS::MediaConvert_
AWS::MediaLive_
AWS::MediaStore_
AWS::MSK_
AWS::Neptune_
AWS::OpsWorks_
AWS::OpsWorksCM_
AWS::Pinpoint_
AWS::PinpointEmail_
AWS::QLDB_
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::SecurityHub_
AWS::Serverless_
AWS::ServiceCatalog_
AWS::ServiceDiscovery_
AWS::StepFunctions_
AWS::Transfer_
AWS::WAF_
AWS::WAFRegional_
AWS::WAFv2_
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_

Duplicating a single instance sample would look like this

.. code:: python

# 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.

.. _AWS CloudFormation: http://aws.amazon.com/cloudformation
.. _AWS CloudFormation JSON: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html
.. _OpenStack resources: http://docs.openstack.org/developer/heat/template_guide/openstack.html
.. _cloudtools-dev: https://groups.google.com/forum/#!forum/cloudtools-dev
.. _LICENSE: https://github.com/cloudtools/troposphere/blob/master/LICENSE
.. _BSD 2-Clause license: http://opensource.org/licenses/BSD-2-Clause

Name With Owner	cloudtools/troposphere
Primary Language	Python
Program language	Python (Language Count: 3)
Platform
License:	BSD 2-Clause "Simplified" License

Created At	2012-12-12 21:19:46
Pushed At	2025-04-17 17:59:39
Last Commit At
Release Count	106
Last Release Name	4.9.2 (Posted on 2025-04-17 10:57:27)
First Release Name	0.1.2 (Posted on 2013-02-26 08:09:20)

Stargazers Count	4.9k
Watchers Count	165
Fork Count	1.4k
Commits Count	3.2k
Has Issues Enabled
Issues Count	927
Issue Open Count	144
Pull Requests Count	1110
Pull Requests Open Count	20
Pull Requests Close Count	239

Has Wiki Enabled
Is Archived
Is Fork
Is Locked
Is Mirror
Is Private

troposphere

Github stars Tracking Chart

===========
troposphere

About

Installation

Examples

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

Currently supported AWS resource types

Currently supported OpenStack resource types

Duplicating a single instance sample would look like this

Community

Licensing

Main metrics

troposphere

Github stars Tracking Chart

=========== troposphere

About

Installation

Examples

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

Currently supported AWS resource types

Currently supported OpenStack resource types

Duplicating a single instance sample would look like this

Community

Licensing

Main metrics

===========
troposphere