marshall-brown / python-terrascript

Create Terraform files using Python scripts.

python-terrascript

Looking for more contributors

IF you feel that this project is useful to you, please consider contributing some of your time towards improving it! For more details on contributions, please have a look at CONTRIBUTORS.md and DEVELOPMENT.md.

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.

Installing Terrascript

Terrascript is available from the Python Package Repository PyPi or alternatively from its Github repository.

Installing Terrascript from PyPi

It is easiest to install Terrascript directly from the Python Package Index.

$ python3 -m pip install terrascript

Installing Terrascript from Github

Terrascript can also be installed from its Github repository.

$ 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.

$ 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.

$ git checkout develop
$ python3 setup.py install

Compatibility

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	Terrascript	Notes
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 release 0.8.0 changed the location of modules. Providers, resources and data sources are now all available through just three modules.

import terrascript
import terrascript.provider     # aws, google, ...
import terrascript.resource     # aws_instance, google_compute_instance, ...
import terrascript.data         # aws_ami, google_compute_image, ...

The legacy layout is still available but should not be used for new projects.

import terrascript
import terrascript.aws          # aws
import terrascript.aws.r        # aws_instance, ...
import terrascript.aws.d        # aws_ami, ...

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.

The original Terraform HCL format.

provider "aws" {
  version = "~> 2.0"
  region  = "us-east-1"
}

resource "aws_vpc" "example" {
  cidr_block = "10.0.0.0/16"
}

The Terrascript code would look like this.

import terrascript
import terrascript.provider as provider
import terrascript.resource as resource

config = terrascript.Terrascript()

config += provider.aws(version='~> 2.0', region='us-east-1')
config += resource.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.

{
  "provider": {
    "aws": [
      {
        "version": "~> 2.0",
        "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)

Links

• Terraform for Terraform.
• Documentation for Python-Terrascript.
• Github page of Python-Terrascript.
• Terraform JSON syntax.