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.

▶ See also: Heroku Common Runtime version of this architecture

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.

Challenges & Caveats

• 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

Requirements

• 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

Usage

Ensure the requirements are met, then,

1. Clone this repo:

   git clone [email protected]:heroku-examples/terraform-heroku-kong-microservices.git
   cd terraform-heroku-kong-microservices/

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

3. Set Heroku API key

   1. heroku authorizations:create -d terraform-heroku-kong-microservices
   2. export HEROKU_API_KEY=<"Token" value from the authorization>

4. Setup DNS

   1. locate the account ID & API token (help)
   2. export DNSIMPLE_ACCOUNT=xxxxx DNSIMPLE_TOKEN=yyyyy

5. terraform init

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

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