Infrastructure

Overview

Terraform configuration for deploying this application to a cloud provider.

Structure

environments/ - Environment-specific configurations (preview, staging, prod)
modules/ - Reusable Terraform modules for database connectivity

Modules

Hyperdrive (`modules/hyperdrive`)

Creates Cloudflare Hyperdrive configurations for Neon PostgreSQL connectivity
Provides connection pooling and edge optimization for database access
Configurations: direct (no-cache) and cached (60s TTL) variants

Environments

Each environment includes:

main.tf - Module instantiation
variables.tf - Input variables
outputs.tf - Output values
provider.tf - Provider configuration
backend.tf - Remote state configuration
terraform.tfvars.example - Example variables
terraform.tfvars - Environment-specific variables

Usage

# Navigate to environment
cd environments/preview

# Copy and configure variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values

# Initialize and apply
terraform init
terraform plan
terraform apply

Requirements

Terraform >= 1.12
Cloudflare account with API token
Required variables: project_name (lowercase, hyphens only), cloudflare_account_id

Development Setup

For the best development experience with Terraform files:

VS Code: Install the HashiCorp Terraform extension (included in project recommendations)
Formatting: Run terraform fmt -recursive to format all .tf files
Validation: Use terraform validate to check syntax before applying

Security

API Token Permissions

Your Cloudflare API token needs the following permissions:

Zone:Zone:Read (for domain management)
Zone:Zone Settings:Edit (for configuration)
Account:Cloudflare Hyperdrive:Edit (for database connection pooling)

Secrets Management

Keep terraform.tfvars files secure and never commit them to version control
The .gitignore should include *.tfvars (except .example files)
Store sensitive values in environment variables when possible

State Management

This configuration uses remote state storage for team collaboration:

State files are stored in Cloudflare R2 (configured in backend.tf)
Each environment maintains separate state files
Initialize with terraform init to download remote state
State locking prevents concurrent modifications

Outputs

After successful deployment, use outputs to configure your application:

# Get Hyperdrive configuration IDs for wrangler.jsonc
terraform output hyperdrive_direct_id
terraform output hyperdrive_cached_id

Add these values to your application's environment configuration.

Troubleshooting

Common Issues

Authentication Error

Error: Authentication error (10000)

Verify your Cloudflare API token has correct permissions
Check CLOUDFLARE_API_TOKEN environment variable is set

Resource Already Exists

Error: resource already exists

Check if resources exist in Cloudflare dashboard
Import existing resources: terraform import <resource> <id>

State Lock Error

Error: state locked

Another user may be running terraform
Force unlock (use carefully): terraform force-unlock <lock-id>

Invalid Project Name

Error: invalid project name

Use only lowercase letters, numbers, and hyphens
Must start with a letter, max 63 characters

TODO

Postgres k8 TODO

FastAPI + PostgreSQL Compose Example

Bank UI Postgres Kubernetes YAML

Fastfood Spring Boot Data StatefulSet YAML

use: kustomize and terraform

On this page