Terraform setup

Initialize, configure, and apply the PayPulse Cloud Terraform infrastructure.

Prerequisites

Before running any Terraform commands, make sure you have the following in place:

• Terraform >= 1.5.0 — required by the required_version constraint in main.tf
• AWS CLI configured with credentials that have sufficient permissions (see IAM roles)
• AWS region: eu-west-1 (default; overridable via terraform.tfvars)
• A terraform.tfvars file with all required sensitive variables (see below)

Module structure

The Terraform configuration lives in aws-infra-terraform/ and is organized into three layers:

aws-infra-terraform/
├── main.tf                    # Root module — orchestrates IAM and Lambda modules
├── variables.tf               # Global input variables
├── outputs.tf                 # Infrastructure outputs (table names, API URL, etc.)
├── terraform.tfvars           # Sensitive values — gitignored
├── moved.tf                   # State migration for refactored resources
├── s3.tf                      # S3 buckets and S3 event notifications
├── dynamodb.tf                # DynamoDB table definitions
├── dynamodb_autoscaling.tf    # Autoscaling for RentalInvoices table
├── cloudwatch.tf              # CloudWatch log groups
├── cognito.tf                 # Cognito identity pool (iOS push notifications)
├── eventbridge.tf             # Scheduled EventBridge triggers
├── api_gateway.tf             # API Gateway HTTP API and routes
├── sns.tf                     # SNS topic for invoice notifications
├── secrets.tf                 # AWS Secrets Manager resources
├── iam/                       # IAM module
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   ├── iam.tf                 # Users, groups, and shared roles
│   ├── iam_signup_lambda.tf
│   ├── iam_login_lambda.tf
│   ├── iam_delete_user_lambda.tf
│   ├── iam_get_rental_invoice_lambda.tf
│   ├── iam_get_rental_invoices_lambda.tf
│   ├── iam_get_user_profile_lambda.tf
│   └── iam_gmail_store_tokens_lambda.tf
└── lambdas/                   # Lambda module
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── lambda_*.tf             # One file per Lambda function
    └── lambda_layers.tf        # Lambda layers (utils, JWT, bcrypt, Google API)

The root module (main.tf) calls the iam and lambdas child modules and wires their inputs and outputs together. Resources that are not Lambda- or IAM-specific (DynamoDB, S3, CloudWatch, etc.) are defined directly in the root module.

Required providers

terraform {
  required_providers {
    klayers = {
      source  = "ldcorentin/klayer"
      version = "~> 1.0.0"
    }
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  required_version = ">=1.5.0"
}

provider "aws" {
  region = var.aws_region
}

The klayers provider is used to fetch the latest ARN of the community-maintained KLayers Lambda layer for bcrypt.

terraform.tfvars

Sensitive and environment-specific values are passed through terraform.tfvars. This file is not committed to version control.

terraform.tfvars is listed in .gitignore. Never commit this file — it contains secrets such as Gmail credentials, the Google OAuth client ID, and the Gemini API key.

The following variables must be set in terraform.tfvars:

Variable	Type	Description
gmail_secret_credentials	string (sensitive)	JSON credentials for Gmail API access
google_oauth_client_id	string (sensitive)	iOS OAuth client ID for Gmail API
gemini_api_key	string (sensitive)	API key for Gemini Flash (retail invoice parsing)

All other variables have defaults defined in variables.tf and can optionally be overridden here (e.g., aws_region, bucket names, table names).

Example structure (do not include real values):

gmail_secret_credentials = "{...}"
google_oauth_client_id   = "your-client-id.apps.googleusercontent.com"
gemini_api_key           = "your-gemini-key"

Deploying the infrastructure

1. Initialize Terraform

   Download providers and initialize the module registry.

   terraform init
   
2. Review the plan

   Preview all changes before applying them. Inspect the output carefully — especially for destructive actions (replacements or deletions).

   terraform plan
   
3. Apply the changes

   Apply the planned changes to your AWS account.

   terraform apply
   

   Terraform will prompt for confirmation before making any changes. Type yes to proceed.

   Running terraform apply in a production environment will modify live AWS resources. Always review the plan output before confirming, and consider using a separate workspace or state file for production.

State management and resource migrations

Terraform state is stored locally in aws-infra-terraform/terraform.tfstate. This file is not committed to version control.

When resources are refactored — for example, moved from the root module into the iam or lambdas child modules — their state addresses change. The moved.tf file records these address renames so Terraform can reconcile existing state without destroying and re-creating resources.

Example entry from moved.tf:

moved {
  from = aws_iam_role.wallenstam_lambda_role
  to   = module.iam.aws_iam_role.wallenstam_lambda_role
}

When Terraform encounters a moved block it updates the state in-place and plans no infrastructure changes. This makes module refactoring safe to apply.

To inspect current state or diagnose issues:

# List all resources tracked in state
terraform state list

# Show details for a specific resource
terraform state show module.iam.aws_iam_role.wallenstam_lambda_role