pterradactyl 1.3.1

hiera-inspired terraform wrapper

Pterradactyl

Pterradactyl is a library developed to abstract TF configuration from the TF environment setup. Pterradactyl allows to create a hierarchy of TF environments/stacks, hallows an unconstrained number of cloud accounts and stacks to share inherited configuration.

Currently, multiple TF stacks are managed through different TF environments and var files. But this becomes especially tricky to manage when the stacks are vastly different from one another, or even in the case of slightly different stacks, one could question the DRY principal looking at all the repeat vars in the var file! When stacks deviate from one another, by using just the var files, the TF code quickly becomes unreadable with all the conditionals. Using just environments based TF, there is always room of accidental apply of one stack to the other. You can use bash files to safegaurd against that but then there is always the old faithful way of doing by just completely skipping the bash file ! (#fun-stuff)

Pterradactyl takes care of all the pain points described above.

Table of content

• Some of the Pterradactyl features
• Installation
• Usage
• Unit Tests
• Examples of creating new projects/prodcuts
• Pterradactyl Directory Structure
• Comparison of other well-known Terraform wrappers:

Some of the Pterradactyl features:

• Programatically generated Terraform code using hierarchical YAML files structure. Override only what you have to in your stack file and keep the rest in common YAML.
• Because Pterradactyl uses hierarchy, it becomes simple to provide standard structure to common attributes like tags in a uniform manner.
• Secrets support using sops and AWS KMS.
• Keeps Terraform versions consistent between stacks.
• As the Terraform file is generated through Pterradactyl, there is no room for the fun override :)

Pterradactyl uses Phiera, to manage the YAML hierarchy configuration for a terraform code base.

Integration of terraform with Phiera is achieved through Pterradactyl.

A primer on Hiera.

Installation:

From PyPi:

pip install pterradactyl

From GitHub:

pip install git+https://github.com/Nike-Inc/pterradactyl#egg=pterradactyl

From source

You can always install it from wheel, by running the following commands:

Build package and wheel.

poetry install
poetry build

Install

python3 -m pip install dist/*.whl

Of course, you can always deploy the package to your corporate Artifactory.

Usage:

Pterradyctal supports all of the terraform commands.

basic cli

apply `pt apply <stack-name>`
plan `pt plan <stack-name>`
destroy `pt destroy <stack-name>`
graph `pt graph <stack-name>`
show `pt show <stack-name>`

Manipulating state

Pterradyctal supports all state commands and they follow the same argument patter as in TF, here are some examples

state list `pt state list <stack-name>`
state show `pt state show <stack-name> -state <target>`
state rm `pt state rm <stack-name> -state <statefile>`

Tests:

Run unit tests

poetry run pytest

Run unit tests with coverage report in HTML format.

poetry run pytest --cov-report=html --cov=pterradactyl --cov-fail-under=80 tests/

Examples of creating new projects/prodcuts:

Basic Example here

• Module setup
• Attribute overriding

Advanced Example here

• Create infrastructure for a new AWS account
• Common tag setup
• KMS encryption
• Remote backend
• Module setup
• Attribute overriding

Pterradactyl Directory Structure:

After running pt apply pterradactyl will create below directory structure, containing downloaded given Terraform version with all required plugins, and workspace containing all metadata for your stack, e.g.:

.pterradactyl
├── terraform
│     └── 0.13.1
│         ├── terraform
│         └── terraform-provider-kubectl_v1.13.1
└── workspace
    └── bt-projectc0-na-useast1
        ├── facts.json
        └── main.tf.json

• terraform - directory containing downloaded Terraform given version with downloaded plugins defined in pterra.yaml file.
• workspace - directory containing metadata information for you stack. Each stack has a separate workspace.
• facts.json - JSON file with facts generated by Pterradactyl (e.g. deploy_user, state_prefix, aws_account_alias)
• main.tf.json - metadata information file regarding providers (e.g. aws, kubernetes, helm), moduls (e.g. vpc, kms, eks)and terraform backend information.

Comparison of other well-known Terraform wrappers:

Terragrunt:

Some of the key Terragrunt features:

• Execute Terraform commands on multiple modules at once
• Keep your Terraform configuration DRY
• Inputs set as env variables.
• Call custom actions using Before and After Hooks
• Work with multiple AWS accounts
• Lock File Handling
• AWS Auth support
• Caching folder where commands are being executed.
• Auto-retry e.g. when installing provider failed due to connection error.

More info here

Terraspace:

Some of the key Terraspace features:

• Build-in generators
• Multiple environments
• Deploy Multiple Stacks with a single command
• Build-in secrets support for AWS Secret Manager, AWS SSM Parameter Store, Azure Key
• Configurable CLI Hooks and CLI Args.
• Allows you to create test harness.
• Terraform Cloud and Terraform Enterprise support.

More info here

Comparison between Pterradactyl vs Terragrunt vs Terraspace

Feature	Pterradactyl	Terragrunt	Terraspace	Comment
Organized Structure	✓	✓	✓
Multiple environments	✓	✓	✓
Execute Terraform commands on multiple modules at once	✓	✓	✓
Secrets support	✓	✓	✓
CLI Hooks	✓	✓	✓	More details
Automated Backend Creation	✓	✓	✓
Built-in Test Framework	✗	✗	✓	More details
Native Terraform HCL	✗	✗	✓	More details

Summary

It's hard to compare Pterradactyl, Terragrunt and Terraspace on the same level.
Overall all those tools have some major differences. However above gives you a gist of what you can expect in each tool.
If you are thinking what is more proper for you, simply deep into the details of each tool. Terragrut and Pterradactyl are rather thin wrappers for Terraform, whereas Terraspace is rather a huge framework.