Skip to main content

AWS CloudFormation creation library

Project description

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 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"
        }
    }
}
>>> 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.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 resource types

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

troposphere-4.9.3.tar.gz (492.9 kB view details)

Uploaded Source

Built Distribution

troposphere-4.9.3-py3-none-any.whl (569.0 kB view details)

Uploaded Python 3

File details

Details for the file troposphere-4.9.3.tar.gz.

File metadata

  • Download URL: troposphere-4.9.3.tar.gz
  • Upload date:
  • Size: 492.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for troposphere-4.9.3.tar.gz
Algorithm Hash digest
SHA256 b295ffdb7ac9d7cdabc271ceffe996df36902ee9481098e0bab8cd06bcb0be10
MD5 eeaecd175ab08d53dc64e798ef0dfd30
BLAKE2b-256 00eea6368284619b509140735f44e23823db18ac67c438dd20ccf16a945c52d9

See more details on using hashes here.

File details

Details for the file troposphere-4.9.3-py3-none-any.whl.

File metadata

  • Download URL: troposphere-4.9.3-py3-none-any.whl
  • Upload date:
  • Size: 569.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.13.2

File hashes

Hashes for troposphere-4.9.3-py3-none-any.whl
Algorithm Hash digest
SHA256 97d990d9123f75f85fed60aefa71519421e66384d11af769660e77ee77fdc610
MD5 55270e88248852bbdb2c46c96d90d3d4
BLAKE2b-256 9b91eb9fe07b50edb4731d6722b1190209f3b6c21bfc98ca0d67137ab65ef8a2

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page