starhawking/python-terrascript

python-terrascript

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

starhawking / python-terrascript

readme

python-terrascript