troposphere
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 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:
>> instance.ImageId = "ami-951945d0" >>> instance.InstanceType = "t1.micro" >>> t.add_resource(instance)
>>> 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 ">
>>> 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:
>> t.add_resource(instance)
">
>>> 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():
>> Ref(instance)
">
>>> 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:
, expected
">
>>> 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:
>>> print(t.to_json()) Traceback (most recent call last): ... ValueError: Resource CidrBlock required in type AWS::EC2::Subnet (title: ec2subnet) ">
>>> from troposphere import Template >>> import troposphere.ec2 as ec2 >>> t = Template() >>> t.add_resource(ec2.Subnet("ec2subnet", VpcId="vpcid")) <troposphere.ec2.Subnet object at 0x100830ed0> >>> print(t.to_json()) Traceback (most recent call last): ... ValueError: Resource CidrBlock required in type AWS::EC2::Subnet (title: ec2subnet)
Currently supported AWS resource types
- AWS::AccessAnalyzer
- AWS::ACMPCA
- AWS::AmazonMQ
- AWS::Amplify
- AWS::ApiGateway
- AWS::ApiGatewayV2
- AWS::AppConfig
- AWS::AppFlow
- AWS::AppIntegrations
- AWS::AppMesh
- AWS::AppRunner
- AWS::AppStream
- AWS::AppSync
- AWS::ApplicationAutoScaling
- AWS::ApplicationInsights
- AWS::Athena
- AWS::AuditManager
- AWS::AutoScaling
- AWS::AutoScalingPlans
- AWS::Batch
- AWS::Budgets
- AWS::Cassandra
- AWS::CE
- AWS::CUR
- AWS::CertificateManager
- AWS::Chatbot
- AWS::Cloud9
- AWS::CloudFormation
- AWS::CloudFront
- AWS::CloudTrail
- AWS::CloudWatch
- AWS::CodeArtifact
- AWS::CodeBuild
- AWS::CodeCommit
- AWS::CodeDeploy
- AWS::CodeGuruProfiler
- AWS::CodeGuruReviewer
- AWS::CodePipeline
- AWS::CodeStar
- AWS::CodeStarConnections
- AWS::CodeStarNotifications
- AWS::Cognito
- AWS::Config
- AWS::Connect
- AWS::CustomerProfiles
- AWS::DataBrew
- AWS::DAX
- AWS::Detective
- AWS::DLM
- AWS::DMS
- AWS::DataPipeline
- AWS::DataSync
- AWS::DirectoryService
- AWS::DocDB
- AWS::DevOpsGuru
- AWS::DynamoDB
- AWS::EC2
- AWS::ECR
- AWS::ECS
- AWS::EFS
- AWS::EKS
- AWS::EMR
- AWS::EMRContainers
- AWS::ElastiCache
- AWS::ElasticBeanstalk
- AWS::ElasticLoadBalancing
- AWS::ElasticLoadBalancingV2
- AWS::Elasticsearch
- AWS::Events
- AWS::EventSchemas
- AWS::FinSpace
- AWS::FraudDetector
- AWS::FIS
- AWS::FMS
- AWS::FSx
- AWS::GameLift
- AWS::GlobalAccelerator
- AWS::Glue
- AWS::Greengrass
- AWS::GreengrassV2
- AWS::GroundStation
- AWS::GuardDuty
- AWS::IAM
- AWS::ImageBuilder
- AWS::Inspector
- AWS::IoT
- AWS::IoT1Click
- AWS::IoTAnalytics
- AWS::IoTCoreDeviceAdvisor
- AWS::IoTEvents
- AWS::IoTFleetHub
- AWS::IoTSiteWise
- AWS::IoTWireless
- AWS::IVS
- AWS::KMS
- AWS::Kendra
- AWS::Kinesis
- AWS::KinesisAnalytics
- AWS::KinesisAnalyticsV2
- AWS::KinesisFirehose
- AWS::LakeFormation
- AWS::Lambda
- AWS::LicenseManager
- AWS::Location
- AWS::Logs
- AWS::LookoutEquipment
- AWS::LookoutMetrics
- AWS::LookoutVision
- AWS::Macie
- AWS::ManagedBlockchain
- AWS::MediaConnect
- AWS::MediaConvert
- AWS::MediaLive
- AWS::MediaPackage
- AWS::MediaStore
- AWS::MSK
- AWS::MWAA
- AWS::Neptune
- AWS::NetworkFirewall
- AWS::NetworkManager
- AWS::NimbleStudio
- AWS::OpsWorks
- AWS::OpsWorksCM
- AWS::Pinpoint
- AWS::PinpointEmail
- AWS::QLDB
- AWS::QuickSight
- AWS::RAM
- AWS::RDS
- AWS::Redshift
- AWS::ResourceGroups
- AWS::RoboMaker
- AWS::Route53
- AWS::Route53Resolver
- AWS::Route53RecoveryControl
- AWS::Route53RecoveryReadiness
- AWS::S3
- AWS::S3ObjectLambda
- AWS::S3Outposts
- AWS::SDB
- AWS::SES
- AWS::SNS
- AWS::SQS
- AWS::SSM
- AWS::SSMContacts
- AWS::SSMIncidents
- AWS::SSO
- AWS::SageMaker
- AWS::SecretsManager
- AWS::SecurityHub
- AWS::Serverless
- AWS::ServiceCatalog
- AWS::ServiceCatalogAppRegistry
- AWS::ServiceDiscovery
- AWS::Signer
- AWS::StepFunctions
- AWS::Synthetics
- AWS::Timestream
- AWS::Transfer
- AWS::WAF
- AWS::WAFRegional
- AWS::WAFv2
- AWS::WorkSpaces
- AWS::XRay
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
# 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.
4 Jan 06, 2023
52 Dec 05, 2022
2 Dec 01, 2021
14 Oct 20, 2021
1 Nov 06, 2021
97 Jan 06, 2023
1 Jan 31, 2022
13 Dec 08, 2022
1 Nov 29, 2021
2 Jun 19, 2022
1 Dec 31, 2021
57 Dec 12, 2022
202 Oct 04, 2022
48 Oct 13, 2022
1 Nov 01, 2021
2 May 18, 2022
8 Feb 08, 2022
1 Dec 17, 2021
3 Nov 28, 2021
3 Jan 11, 2022