0
# Troposphere
1

2
Troposphere is a Python library that facilitates creating AWS CloudFormation templates programmatically. It provides Python classes representing AWS resources and properties with built-in validation and type checking to catch errors early in development. The library supports generating both JSON and YAML CloudFormation templates and includes comprehensive coverage of AWS resource types.
3

4
## Package Information
5

6
- **Package Name**: troposphere
7
- **Language**: Python 3.8+
8
- **Installation**: `pip install troposphere`
9
- **License**: BSD-2-Clause
10
- **Documentation**: https://troposphere.readthedocs.io/en/latest/
11

12
## Core Imports
13

14
```python
15
import troposphere
16
from troposphere import Template, Parameter, Output, Ref, GetAtt
17
```
18

19
Common patterns for specific AWS services:
20

21
```python
22
from troposphere.ec2 import Instance, SecurityGroup, VPC
23
from troposphere.s3 import Bucket, BucketPolicy
24
from troposphere.awslambda import Function, Permission
25
```
26

27
For CloudFormation intrinsic functions:
28

29
```python
30
from troposphere import Join, Sub, FindInMap, If, Equals, Base64
31
```
32

33
For constants and validation:
34

35
```python
36
from troposphere.constants import T2_MICRO, US_EAST_1, HTTP_PORT
37
from troposphere.validators import positive_integer, network_port
38
```
39

40
## Basic Usage
41

42
```python
43
from troposphere import Template, Parameter, Output, Ref
44
from troposphere.ec2 import Instance, SecurityGroup
45
from troposphere.constants import T2_MICRO
46

47
# Create a new CloudFormation template
48
template = Template()
49
template.set_description("Example EC2 instance with security group")
50

51
# Add parameters
52
instance_type_param = template.add_parameter(Parameter(
53
    "InstanceType",
54
    Type="String",
55
    Default=T2_MICRO,
56
    Description="EC2 instance type"
57
))
58

59
# Create a security group
60
security_group = template.add_resource(SecurityGroup(
61
    "MySecurityGroup",
62
    GroupDescription="Security group for EC2 instance",
63
    SecurityGroupIngress=[
64
        {
65
            "IpProtocol": "tcp",
66
            "FromPort": 22,
67
            "ToPort": 22,
68
            "CidrIp": "0.0.0.0/0"
69
        }
70
    ]
71
))
72

73
# Create an EC2 instance
74
instance = template.add_resource(Instance(
75
    "MyInstance",
76
    InstanceType=Ref(instance_type_param),
77
    ImageId="ami-0abcdef1234567890",
78
    SecurityGroupIds=[Ref(security_group)]
79
))
80

81
# Add outputs
82
template.add_output(Output(
83
    "InstanceId",
84
    Value=Ref(instance),
85
    Description="Instance ID of the created EC2 instance"
86
))
87

88
# Generate CloudFormation template
89
print(template.to_json())
90
```
91

92
## Architecture
93

94
Troposphere uses a hierarchical object model that mirrors CloudFormation's structure:
95

96
- **Template**: Top-level container managing resources, parameters, outputs, mappings, and conditions
97
- **BaseAWSObject**: Abstract base class providing validation and property management for all AWS objects
98
- **AWSObject**: Base class for CloudFormation resources (EC2 instances, S3 buckets, etc.)
99
- **AWSProperty**: Base class for complex resource properties and nested configuration objects
100
- **AWSHelperFn**: Base class for CloudFormation intrinsic functions (Ref, GetAtt, Join, etc.)
101

102
This design ensures type safety through Python's class system while providing the flexibility to represent any CloudFormation construct. The library includes 1,472+ resource classes and 5,866+ property classes covering the complete AWS service catalog.
103

104
## Capabilities
105

106
### Template Management
107

108
Core functionality for creating and managing CloudFormation templates, including adding resources, parameters, outputs, and converting to JSON/YAML formats.
109

110
```python { .api }
111
class Template:
112
    def __init__(self, Description: Optional[str] = None, Metadata: Optional[Dict[str, Any]] = None): ...
113
    def add_resource(self, resource) -> resource: ...
114
    def add_parameter(self, parameter) -> parameter: ...
115
    def add_output(self, output) -> output: ...
116
    def add_mapping(self, name: str, mapping: Dict[str, Any]) -> None: ...
117
    def add_condition(self, name: str, condition) -> str: ...
118
    def to_json(self, indent: int = 1, sort_keys: bool = True) -> str: ...
119
    def to_yaml(self, clean_up: bool = False, long_form: bool = False) -> str: ...
120
```
121

122
[Template Management](./template-management.md)
123

124
### CloudFormation Resources
125

126
AWS resource classes representing all CloudFormation resource types across 257 AWS services. Each resource class inherits from AWSObject and includes built-in property validation.
127

128
```python { .api }
129
class AWSObject(BaseAWSObject):
130
    def __init__(self, title: str, template: Optional[Template] = None, **kwargs): ...
131
    def ref(self) -> Ref: ...
132
    def get_att(self, value: str) -> GetAtt: ...
133
```
134

135
Key resource examples:
136

137
```python { .api }
138
# EC2 Resources
139
class Instance(AWSObject):
140
    resource_type = "AWS::EC2::Instance": ...
141

142
class SecurityGroup(AWSObject):
143
    resource_type = "AWS::EC2::SecurityGroup": ...
144

145
# S3 Resources  
146
class Bucket(AWSObject):
147
    resource_type = "AWS::S3::Bucket": ...
148

149
# Lambda Resources
150
class Function(AWSObject):
151
    resource_type = "AWS::Lambda::Function": ...
152
```
153

154
[AWS Resources](./aws-resources.md)
155

156
### CloudFormation Intrinsic Functions
157

158
Complete implementation of CloudFormation intrinsic functions for references, string manipulation, conditionals, and data transformation within templates.
159

160
```python { .api }
161
class Ref(AWSHelperFn):
162
    def __init__(self, data: object): ...
163

164
class GetAtt(AWSHelperFn):
165
    def __init__(self, logicalName: object, attrName: object): ...
166

167
class Join(AWSHelperFn):
168
    def __init__(self, delimiter: object, values: object): ...
169

170
class Sub(AWSHelperFn):
171
    def __init__(self, input_str: object, dict_values: Optional[Dict[str, Any]] = None, **values): ...
172

173
class If(AWSHelperFn):
174
    def __init__(self, cond: object, true: object, false: object): ...
175
```
176

177
[Intrinsic Functions](./intrinsic-functions.md)
178

179
### Parameters and Outputs
180

181
CloudFormation template parameters for user inputs and outputs for exposing resource values, with comprehensive validation and cross-stack reference support.
182

183
```python { .api }
184
class Parameter(AWSDeclaration):
185
    def __init__(self, title: str, Type: str, Default=None, NoEcho: bool = False, 
186
                 AllowedValues: list = None, Description: str = None, **kwargs): ...
187

188
class Output(AWSDeclaration):
189
    def __init__(self, title: str, Value: str, Description: str = None, 
190
                 Export: Export = None, **kwargs): ...
191

192
class Export(AWSHelperFn):
193
    def __init__(self, name: Union[str, AWSHelperFn]): ...
194
```
195

196
[Parameters and Outputs](./parameters-outputs.md)
197

198
### Constants and Pseudo Parameters
199

200
Pre-defined constants for AWS regions, instance types, ports, and pseudo parameters for dynamic CloudFormation values.
201

202
```python { .api }
203
# Pseudo Parameters
204
AWS_ACCOUNT_ID: str = "AWS::AccountId"
205
AWS_REGION: str = "AWS::Region"
206
AWS_STACK_NAME: str = "AWS::StackName"
207

208
# Pseudo Parameter Refs
209
AccountId: Ref = Ref(AWS_ACCOUNT_ID)
210
Region: Ref = Ref(AWS_REGION)
211
StackName: Ref = Ref(AWS_STACK_NAME)
212

213
# Policy Constants
214
Delete: str = "Delete"
215
Retain: str = "Retain"
216
Snapshot: str = "Snapshot"
217
```
218

219
[Constants](./constants.md)
220

221
### Validation and Type Safety
222

223
Comprehensive validation system with built-in validators for AWS-specific constraints, data types, and custom validation functions.
224

225
```python { .api }
226
def positive_integer(x) -> int: ...
227
def network_port(x) -> int: ...
228
def s3_bucket_name(b) -> str: ...
229
def one_of(class_name, properties, property, conditionals): ...
230
def mutually_exclusive(class_name, properties, conditionals): ...
231
def exactly_one(class_name, properties, conditionals): ...
232
```
233

234
[Validation](./validation.md)
235

236
### Tags and Metadata
237

238
Tag management for AWS resource tagging with validation, sorting, and concatenation support.
239

240
```python { .api }
241
class Tag(AWSHelperFn):
242
    def __init__(self, k: object, v: object): ...
243

244
class Tags(AWSHelperFn):
245
    def __init__(self, *args: object, **kwargs): ...
246
    def __add__(self, newtags: Tags) -> Tags: ...
247
```
248

249
[Tags and Metadata](./tags-metadata.md)
250

251
### Helper Utilities
252

253
Additional utilities for user data, template conversion, and stack monitoring to enhance CloudFormation workflow integration.
254

255
```python { .api }
256
# UserData helpers
257
def from_file(filepath: str) -> str: ...
258
def from_file_sub(filepath: str) -> str: ...
259

260
# Template generator
261
class TemplateGenerator:
262
    def convert_template(self, template_data: dict) -> Template: ...
263

264
# Stack monitoring
265
def get_events(stackname: str, region: str = None, aws_profile: str = None): ...
266
def tail(stackname: str, region: str = None, aws_profile: str = None): ...
267
```
268

269
[Helper Utilities](./helper-utilities.md)
270

271
### OpenStack Support
272

273
Limited OpenStack Heat template support for organizations using hybrid cloud deployments with both AWS and OpenStack infrastructure.
274

275
```python { .api }
276
class HeatTemplate:
277
    def __init__(self, heat_template_version: str = None): ...
278
```
279

280
[OpenStack Support](./openstack-support.md)