Heroku Enterprise microservices with a unified gateway using Terraform

A Heroku Private Space provides a container for internally routed apps that are only accessible within its private network.

Each microservice (internal app) is exposed to the internet through a Kong service & route with a custom domain name, secured via automated certificate management.

A single Terraform config embodies the complete system, enabling high-level collaboration, repeatability, test-ability, and change management.

Primary components

Heroku provides the primatives: Private Spaces, Apps, and Add-ons
Kong CE on Heroku provides a high-performance HTTP proxy/gateway with plugins supporting access control, flow control, logging, circuit-breaking, and more including custom plugins
Terraform provides declarative, unified systems configuration with support for over 120 providers, a human-friendly configuration as code format, and a deterministic provisioning engine
DNSimple provides API-driven domain name configuration.

Config drift when using Heroku Dashboard or CLI. Once the config is applied, if changes are made to the resources outside of Terraform, such as scaling dynos, setting config vars, changing add-ons, etc, then the Terraform state will no longer match its configuration, making it impossible to apply or destroy further until the drifting values are imported (for new resources) or manually updated in terraform.tfstate.
Connecting the Terraform config with Heroku slugs. This proof-of-concept contains slug archives that were manually extracted with the Heroku API from pre-existing apps. While there's a higher-level conceptual challenge with the design of this interconnection between Heroku DX & Terraform, there are use-cases this proof-of-concept still serves, such as using Heroku Pipelines purely as a build & QA system (example), and with an external CI/build system creating slug archives for Terraform.
Renaming Terraform-provisioned Heroku apps. If apps are renamed, Terraform can no longer access various resources without first manually editing, revising terraform.tfstate with the new names. See terraform-provider-heroku issues #124 & #93

Heroku
- install command-line tools (CLI)
- an account (must be a member of an Enterprise account for access to Private Spaces)
DNSimple
- at least a personal account ($5/month)
- a domain name added to that account
install git
install git-lfs (efficiently supports checking Heroku app slugs into version control)
install Terraform

Ensure the requirements are met, then,

Clone this repo:

git clone git@github.com:heroku-examples/terraform-heroku-kong-microservices.git
cd terraform-heroku-kong-microservices/

Install terraform-provider-kong 1.9.1
- download the .zip asset for your computer's architecture
- unzip it into terraform.d/plugins/$ARCH/
- where $ARCH is the computer's architecture, like darwin_amd64
Set Heroku API key
1. heroku authorizations:create -d terraform-heroku-kong-microservices
2. export HEROKU_API_KEY=<"Token" value from the authorization>
Setup DNS
1. locate the account ID & API token (help)
2. export DNSIMPLE_ACCOUNT=xxxxx DNSIMPLE_TOKEN=yyyyy
terraform init

Then, apply the config with your own top-level config values:

terraform apply \
  -var name=kong-micro \
  -var dns_zone=example.com \
  -var heroku_enterprise_team=example-team

Visit the output URLs in a web browser to demonstrate the secure backend & public gateway:
- ❌ terraform output wasabi_backend_url not directly accessible
- ✅ terraform output wasabi_public_url

🔬 This is a community proof-of-concept, MIT license, provided "as is", without warranty of any kind.