===========
troposphere
===========
.. image:: https://img.shields.io/pypi/v/troposphere.svg
:target: https://pypi.python.org/pypi/troposphere
:alt: PyPI Version
.. image:: https://github.com/cloudtools/troposphere/actions/workflows/tests.yml/badge.svg
:target: https://github.com/cloudtools/troposphere/actions?query=branch%3Amain
: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 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.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
======================================
- `AWS Resource Types`_
- `OpenStack Resource Types`_
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
.. _`AWS Resource Types`: https://github.com/cloudtools/troposphere/blob/master/resources_aws.md
.. _`OpenStack Resource Types`: https://github.com/cloudtools/troposphere/blob/master/resources_openstack.md
Raw data
{
"_id": null,
"home_page": "https://github.com/cloudtools/troposphere",
"name": "troposphere",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Mark Peek",
"author_email": "mark@peek.org",
"download_url": "https://files.pythonhosted.org/packages/8a/ab/99197febf40e643ef52f7826402ac5c841656567e58a5a121855212df15f/troposphere-4.9.0.tar.gz",
"platform": null,
"description": "===========\ntroposphere\n===========\n\n.. image:: https://img.shields.io/pypi/v/troposphere.svg\n :target: https://pypi.python.org/pypi/troposphere\n :alt: PyPI Version\n\n.. image:: https://github.com/cloudtools/troposphere/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/cloudtools/troposphere/actions?query=branch%3Amain\n :alt: Build Status\n\n.. image:: https://img.shields.io/pypi/l/troposphere.svg\n :target: https://opensource.org/licenses/BSD-2-Clause\n :alt: license: New BSD license\n\n.. image:: https://readthedocs.org/projects/troposphere/badge/?version=latest\n :target: https://troposphere.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\nAbout\n=====\n\ntroposphere - library to create `AWS CloudFormation`_ descriptions\n\nThe troposphere library allows for easier creation of the `AWS CloudFormation\nJSON`_ by writing Python code to describe the AWS resources. troposphere also\nincludes some basic support for `OpenStack resources`_ via Heat.\n\nTo facilitate catching CloudFormation or JSON errors early the library has\nproperty and type checking built into the classes.\n\nInstallation\n============\n\ntroposphere can be installed using the pip distribution system for Python by\nissuing:\n\n.. code:: sh\n\n $ pip install troposphere\n\nTo install troposphere with `awacs <https://github.com/cloudtools/awacs>`_\n(recommended soft dependency):\n\n.. code:: sh\n\n $ pip install troposphere[policy]\n\nAlternatively, you can use `setup.py` to install by cloning this repository\nand issuing:\n\n.. code:: sh\n\n $ python setup.py install # you may need sudo depending on your python installation\n\nExamples\n========\n\nA simple example to create an instance would look like this:\n\n.. code:: python\n\n >>> from troposphere import Ref, Template\n >>> import troposphere.ec2 as ec2\n >>> t = Template()\n >>> instance = ec2.Instance(\"myinstance\")\n >>> instance.ImageId = \"ami-951945d0\"\n >>> instance.InstanceType = \"t1.micro\"\n >>> t.add_resource(instance)\n <troposphere.ec2.Instance object at 0x101bf3390>\n >>> print(t.to_json())\n {\n \"Resources\": {\n \"myinstance\": {\n \"Properties\": {\n \"ImageId\": \"ami-951945d0\",\n \"InstanceType\": \"t1.micro\"\n },\n \"Type\": \"AWS::EC2::Instance\"\n }\n }\n }\n >>> print(t.to_yaml())\n Resources:\n myinstance:\n Properties:\n ImageId: ami-951945d0\n InstanceType: t1.micro\n Type: AWS::EC2::Instance\n\nAlternatively, parameters can be used instead of properties:\n\n.. code:: python\n\n >>> instance = ec2.Instance(\"myinstance\", ImageId=\"ami-951945d0\", InstanceType=\"t1.micro\")\n >>> t.add_resource(instance)\n <troposphere.ec2.Instance object at 0x101bf3550>\n\nAnd ``add_resource()`` returns the object to make it easy to use with ``Ref()``:\n\n.. code:: python\n\n >>> instance = t.add_resource(ec2.Instance(\"myinstance\", ImageId=\"ami-951945d0\", InstanceType=\"t1.micro\"))\n >>> Ref(instance)\n <troposphere.Ref object at 0x101bf3490>\n\n---------------------------------------------------------------------\nExamples of the error checking (full tracebacks removed for clarity):\n---------------------------------------------------------------------\n\nIncorrect property being set on AWS resource:\n\n.. code:: python\n\n >>> import troposphere.ec2 as ec2\n >>> ec2.Instance(\"ec2instance\", image=\"i-XXXX\")\n Traceback (most recent call last):\n ...\n AttributeError: AWS::EC2::Instance object does not support attribute image\n\nIncorrect type for AWS resource property:\n\n.. code:: python\n\n >>> ec2.Instance(\"ec2instance\", ImageId=1)\n Traceback (most recent call last):\n ...\n TypeError: ImageId is <type 'int'>, expected <type 'basestring'>\n\nMissing required property for the AWS resource:\n\n.. code:: python\n\n >>> from troposphere import Template\n >>> import troposphere.ec2 as ec2\n >>> t = Template()\n >>> t.add_resource(ec2.Subnet(\"ec2subnet\", VpcId=\"vpcid\"))\n <troposphere.ec2.Subnet object at 0x100830ed0>\n >>> print(t.to_json())\n Traceback (most recent call last):\n ...\n ValueError: Resource CidrBlock required in type AWS::EC2::Subnet (title: ec2subnet)\n\nCurrently supported resource types\n======================================\n\n- `AWS Resource Types`_\n- `OpenStack Resource Types`_\n\nDuplicating a single instance sample would look like this\n=========================================================\n\n.. code:: python\n\n # Converted from EC2InstanceSample.template located at:\n # http://aws.amazon.com/cloudformation/aws-cloudformation-templates/\n\n from troposphere import Base64, FindInMap, GetAtt\n from troposphere import Parameter, Output, Ref, Template\n import troposphere.ec2 as ec2\n\n\n template = Template()\n\n keyname_param = template.add_parameter(Parameter(\n \"KeyName\",\n Description=\"Name of an existing EC2 KeyPair to enable SSH \"\n \"access to the instance\",\n Type=\"String\",\n ))\n\n template.add_mapping('RegionMap', {\n \"us-east-1\": {\"AMI\": \"ami-7f418316\"},\n \"us-west-1\": {\"AMI\": \"ami-951945d0\"},\n \"us-west-2\": {\"AMI\": \"ami-16fd7026\"},\n \"eu-west-1\": {\"AMI\": \"ami-24506250\"},\n \"sa-east-1\": {\"AMI\": \"ami-3e3be423\"},\n \"ap-southeast-1\": {\"AMI\": \"ami-74dda626\"},\n \"ap-northeast-1\": {\"AMI\": \"ami-dcfa4edd\"}\n })\n\n ec2_instance = template.add_resource(ec2.Instance(\n \"Ec2Instance\",\n ImageId=FindInMap(\"RegionMap\", Ref(\"AWS::Region\"), \"AMI\"),\n InstanceType=\"t1.micro\",\n KeyName=Ref(keyname_param),\n SecurityGroups=[\"default\"],\n UserData=Base64(\"80\")\n ))\n\n template.add_output([\n Output(\n \"InstanceId\",\n Description=\"InstanceId of the newly created EC2 instance\",\n Value=Ref(ec2_instance),\n ),\n Output(\n \"AZ\",\n Description=\"Availability Zone of the newly created EC2 instance\",\n Value=GetAtt(ec2_instance, \"AvailabilityZone\"),\n ),\n Output(\n \"PublicIP\",\n Description=\"Public IP address of the newly created EC2 instance\",\n Value=GetAtt(ec2_instance, \"PublicIp\"),\n ),\n Output(\n \"PrivateIP\",\n Description=\"Private IP address of the newly created EC2 instance\",\n Value=GetAtt(ec2_instance, \"PrivateIp\"),\n ),\n Output(\n \"PublicDNS\",\n Description=\"Public DNSName of the newly created EC2 instance\",\n Value=GetAtt(ec2_instance, \"PublicDnsName\"),\n ),\n Output(\n \"PrivateDNS\",\n Description=\"Private DNSName of the newly created EC2 instance\",\n Value=GetAtt(ec2_instance, \"PrivateDnsName\"),\n ),\n ])\n\n print(template.to_json())\n\nCommunity\n=========\n\nWe have a Google Group, cloudtools-dev_, where you can ask questions and\nengage with the troposphere community. Issues and pull requests are always\nwelcome!\n\nLicensing\n=========\n\ntroposphere is licensed under the `BSD 2-Clause license`_.\nSee `LICENSE`_ for the troposphere full license text.\n\n\n.. _`AWS CloudFormation`: http://aws.amazon.com/cloudformation\n.. _`AWS CloudFormation JSON`: http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html\n.. _`OpenStack resources`: http://docs.openstack.org/developer/heat/template_guide/openstack.html\n.. _cloudtools-dev: https://groups.google.com/forum/#!forum/cloudtools-dev\n.. _`LICENSE`: https://github.com/cloudtools/troposphere/blob/master/LICENSE\n.. _`BSD 2-Clause license`: http://opensource.org/licenses/BSD-2-Clause\n.. _`AWS Resource Types`: https://github.com/cloudtools/troposphere/blob/master/resources_aws.md\n.. _`OpenStack Resource Types`: https://github.com/cloudtools/troposphere/blob/master/resources_openstack.md\n",
"bugtrack_url": null,
"license": "New BSD license",
"summary": "AWS CloudFormation creation library",
"version": "4.9.0",
"project_urls": {
"Changelog": "https://github.com/cloudtools/troposphere/blob/master/CHANGELOG.md",
"Homepage": "https://github.com/cloudtools/troposphere",
"Source": "https://github.com/cloudtools/troposphere",
"Tracker": "https://github.com/cloudtools/troposphere/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a070c0d9de1e5c3e2dc42d5443d5e29d065859ece93d390245da8be0daadfb81",
"md5": "1639db520d3ec148ec2697038db7f8a4",
"sha256": "a5550eccb2b4fb4fd861af54d01bcea1704845b00e45376a7fe87a0aa6f0646d"
},
"downloads": -1,
"filename": "troposphere-4.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1639db520d3ec148ec2697038db7f8a4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 552342,
"upload_time": "2025-01-15T00:04:02",
"upload_time_iso_8601": "2025-01-15T00:04:02.599483Z",
"url": "https://files.pythonhosted.org/packages/a0/70/c0d9de1e5c3e2dc42d5443d5e29d065859ece93d390245da8be0daadfb81/troposphere-4.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8aab99197febf40e643ef52f7826402ac5c841656567e58a5a121855212df15f",
"md5": "bf90b025743a3ef48333e6bdc9220787",
"sha256": "c0eab90c3723f70a04ece651fc648e5c9b8afbb80ce2dadb87cc22404b2fc884"
},
"downloads": -1,
"filename": "troposphere-4.9.0.tar.gz",
"has_sig": false,
"md5_digest": "bf90b025743a3ef48333e6bdc9220787",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 476041,
"upload_time": "2025-01-15T00:04:05",
"upload_time_iso_8601": "2025-01-15T00:04:05.603243Z",
"url": "https://files.pythonhosted.org/packages/8a/ab/99197febf40e643ef52f7826402ac5c841656567e58a5a121855212df15f/troposphere-4.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 00:04:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cloudtools",
"github_project": "troposphere",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "cfn_flip",
"specs": [
[
">=",
"1.0.2"
]
]
}
],
"tox": true,
"lcname": "troposphere"
}
JSON
