254 lines
8.2 KiB
ReStructuredText
254 lines
8.2 KiB
ReStructuredText
python-terrascript
|
|
------------------
|
|
|
|
.. image:: https://img.shields.io/github/license/mjuenema/python-terrascript
|
|
:target: https://opensource.org/licenses/BSD-2-Clause
|
|
|
|
.. image:: https://img.shields.io/travis/mjuenema/python-terrascript
|
|
:target: https://www.travis-ci.org/mjuenema/python-terrascript/builds
|
|
|
|
.. image:: https://img.shields.io/pypi/v/terrascript
|
|
:target: https://pypi.org/project/terrascript/
|
|
|
|
.. image:: https://img.shields.io/pypi/pyversions/terrascript
|
|
:target: https://pypi.org/project/terrascript/
|
|
|
|
.. image:: https://img.shields.io/pypi/dm/terrascript
|
|
:target: https://pypi.org/project/terrascript/
|
|
|
|
.. image:: https://img.shields.io/github/issues/mjuenema/python-terrascript
|
|
:target: https://github.com/mjuenema/python-terrascript/issues
|
|
|
|
.. image:: https://img.shields.io/github/stars/mjuenema/python-terrascript
|
|
:target: https://github.com/mjuenema/python-terrascript/stargazers
|
|
|
|
|
|
About
|
|
~~~~~
|
|
|
|
Python-Terrascript is a Python package for generating Terraform configurations in JSON format.
|
|
|
|
Creating Terraform through a Python script offers a degree of flexibility
|
|
superior to writing Terraform configurations by hand.
|
|
|
|
* Control structures like ``if``/``else``, ``for``/``continue``/``break`` or ``try``/``except``/``finally``.
|
|
* More string methods.
|
|
* Python functions may be used as an alternative to Terraform_ Modules.
|
|
* Access to the Python Standard Library and third-party packages.
|
|
|
|
The file PROVIDERS.md_ lists all currently supported Terraform providers.
|
|
|
|
.. _PROVIDERS.md: PROVIDERS.md
|
|
|
|
Installing Terrascript
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Terrascript is available from the Python Package Repository PyPi_ or
|
|
alternatively from its Github_ repository.
|
|
|
|
.. _PyPi: https://pypi.org/project/terrascript/#history
|
|
.. _Github: https://github.com/mjuenema/python-terrascript
|
|
|
|
|
|
Installing Terrascript from PyPi
|
|
..................
|
|
|
|
It is easiest to install Terrascript directly from the Python Package Index.
|
|
|
|
.. code-block:: console
|
|
|
|
$ python3 -m pip install terrascript
|
|
|
|
Installing Terrascript from Github
|
|
...................................
|
|
|
|
Terrascript can also be installed from its Github_ repository.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git clone https://github.com/mjuenema/python-terrascript.git
|
|
$ cd python-terrascript/
|
|
$ git fetch
|
|
$ git fetch --tags
|
|
|
|
The ``master`` branch should be identical to the version on PyPi.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git checkout master
|
|
$ python3 setup.py install
|
|
|
|
The ``develop`` branch includes the latest changes but may not always
|
|
be in a stable state. Do not use the ``develop`` branch unless you want
|
|
to submit a merge request on github.
|
|
|
|
.. code-block:: console
|
|
|
|
$ git checkout develop
|
|
$ python3 setup.py install
|
|
|
|
Compatibility
|
|
~~~~~~~~~~~~~
|
|
|
|
Terraform releases
|
|
..................
|
|
|
|
`Terraform 0.13`_ added the `required providers`_ block together with tighter
|
|
integration with the `Terraform Provider Registry`_. Terrascript 0.10.x
|
|
reflects this change and is *not backwards compatible* with earlier Terraform
|
|
releases.
|
|
|
|
`Terraform 0.12`_ introduced some changes to how it deals with configuration
|
|
files in JSON format. This is reflected in Terrascript by currently having
|
|
separate releases for Terraform 0.12 and Terraform 0.11. Earlier releases of
|
|
Terraform are not supported.
|
|
|
|
.. _`Terraform 0.12`: https://www.hashicorp.com/blog/announcing-terraform-0-12
|
|
.. _`Terraform 0.13`: https://www.hashicorp.com/blog/announcing-hashicorp-terraform-0-13
|
|
.. _`required_providers`: https://www.terraform.io/upgrade-guides/0-13.html
|
|
.. _`Terraform Provider Registry`: https://registry.terraform.io/browse/providers
|
|
|
|
========== ============ ============================================================================================
|
|
Terraform Terrascript Notes
|
|
========== ============ ============================================================================================
|
|
0.13.x 0.10.x Introduced namespaces, many more providers, suppports Terraform 0.13 only
|
|
0.13.x 0.9.x Cleanup efforts and bug fixes, dropping support for Python <3.6, supporting Terraform 0.13.x
|
|
0.12.x 0.8.x Terrascript 0.8 are a (almost) complete rewrite
|
|
0.12.x 0.7.x Never released
|
|
0.11.x 0.6.x Last releases to support Terraform 0.11 and earlier
|
|
========== ============ ============================================================================================
|
|
|
|
Terrascript supports Python 3.6 and later.
|
|
|
|
Module layout
|
|
.............
|
|
|
|
Python-Terrascript's top-level directory layout is structured into providers,
|
|
resources and data sources.
|
|
|
|
::
|
|
|
|
import terrascript
|
|
import terrascript.provider
|
|
import terrascript.resource
|
|
import terrascript.data
|
|
|
|
This is then further structured into *namespaces* to reflect the changes in
|
|
_`Terraform 0.13`. Below are examples for importing the modules for the
|
|
`Amazon Web Services Provider`_ which is maintained by Hashicorp.
|
|
|
|
.. _`Amazon Web Services Provider`: https://registry.terraform.io/providers/hashicorp/aws/latest
|
|
|
|
::
|
|
|
|
import terrascript.provider.hashicorp.aws
|
|
import terrascript.resource.hashicorp.aws
|
|
import terrascript.data.hashicorp.aws
|
|
|
|
A first example
|
|
~~~~~~~~~~~~~~~
|
|
|
|
The following example has been taken from the official Terraform documentation
|
|
for the `AWS Provider`_ and then converted into a Python script that generates
|
|
the equivalent configuration in JSON syntax.
|
|
|
|
.. _`AWS Provider`: https://www.terraform.io/docs/providers/aws/index.html
|
|
|
|
First the original Terraform HCL format, which since Terraform 0.13 must include
|
|
a ``required_providers`` block inside the ``terraform`` block.
|
|
|
|
::
|
|
|
|
terraform {
|
|
required_providers {
|
|
aws = {
|
|
source = "hashicorp/aws"
|
|
version = "3.36.0"
|
|
}
|
|
}
|
|
}
|
|
|
|
provider "aws" {
|
|
region = "us-east-1"
|
|
}
|
|
|
|
resource "aws_vpc" "example" {
|
|
cidr_block = "10.0.0.0/16"
|
|
}
|
|
|
|
|
|
The Terrascript code would look like this. The ``required_providers`` argument
|
|
is supplied as a nested dictionary. In this example only the
|
|
`Amazon Web Services Provider`_ is used, which is maintained by Hashicorp.
|
|
|
|
::
|
|
|
|
import terrascript
|
|
import terrascript.provider.hashicorp.aws
|
|
import terrascript.resource.hashicorp.aws
|
|
|
|
config = terrascript.Terrascript()
|
|
|
|
# The ``required_providers`` argument is supplied as a nested dictionary.
|
|
config += terrascript.Terraform(required_providers={'aws': {'source': 'hashicorp/aws',
|
|
'version': '3.36.0' }
|
|
})
|
|
|
|
# The provider is a module and a class: ***.***
|
|
config += terrascript.provider.hashicorp.aws.aws(region='us-east-1')
|
|
config += terrascript.resource.hashicorp.aws.aws_vpc('example', cidr_block='10.0.0.0/16')
|
|
|
|
with open('config.tf.json', 'wt') as fp:
|
|
fp.write(str(config))
|
|
|
|
|
|
The content of ``config.tf.json`` is shown below. It is equivalent to the
|
|
original HCL format.
|
|
|
|
::
|
|
|
|
{
|
|
"terraform": {
|
|
"required_providers": {
|
|
"aws": {
|
|
"source": "hashicorp/aws",
|
|
"version": "3.36.0"
|
|
}
|
|
}
|
|
},
|
|
"provider": {
|
|
"aws": [
|
|
{
|
|
"region": "us-east-1"
|
|
}
|
|
]
|
|
},
|
|
"resource": {
|
|
"aws_vpc": {
|
|
"example": {
|
|
"cidr_block": "10.0.0.0/16"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
**Terrascript does not verify that the generated JSON code is a valid Terraform configuration.**
|
|
**This is a deliberate design decision and is explained in the** `Frequently Asked Questions (FAQ) <https://python-terrascript.readthedocs.io/en/develop/faq.html>`_
|
|
|
|
.. _Frequently Asked Questions (FAQ): https://python-terrascript.readthedocs.io/en/develop/faq.html
|
|
|
|
Links
|
|
~~~~~
|
|
|
|
* Terraform_.
|
|
* `Terraform Provider Registry`_.
|
|
* Documentation_ for Python-Terrascript.
|
|
* Github_ page of Python-Terrascript.
|
|
* `Terraform JSON`_ syntax.
|
|
|
|
.. _Terraform: https://www.terraform.io
|
|
.. _Documentation: https://python-terrascript.readthedocs.io/en/develop/
|
|
.. _Github: https://github.com/mjuenema/python-terrascript
|
|
.. _`Terraform JSON`: https://www.terraform.io/docs/configuration/syntax-json.html
|
|
.. _`Terraform Provider Registry`: https://registry.terraform.io/browse/providers
|