juspay/hyperswitch-suite

Purpose and Entry Points

This repository is the AWS infrastructure-as-code layer for deploying Hyperswitch, the open-source payments switch. It does not contain the Rust app server itself; it provisions its hosting platform, supporting services, Kubernetes add-ons, edge delivery, and operational tooling.

Primary operational entry points are environment-specific Terraform stacks under terraform/aws/live, beginning with the populated dev region:

• terraform/aws/live/dev/eu-central-1

• terraform/aws/live/dev/eu-central-1/eks/main.tf

• terraform/aws/live/dev/eu-central-1/apps/hyperswitch-app/main.tf

Bootstrap stacks establish Terraform backend/foundation resources per environment:

• terraform/aws/bootstrap/dev/main.tf

• terraform/aws/modules/composition/terraform-backend/main.tf

Terraform Layering and Environment Boundary

Infrastructure is organized into reusable base primitives, higher-level AWS compositions, and deployable live stacks. Live stacks supply environment/region inputs and state backends; they invoke modules rather than directly defining most infrastructure.

• Base AWS abstractions: terraform/aws/modules/base/vpc/main.tf, terraform/aws/modules/base/eks/main.tf, terraform/aws/modules/base/s3-bucket/main.tf

• Service compositions: terraform/aws/modules/composition/vpc-network/main.tf, terraform/aws/modules/composition/eks/main.tf, terraform/aws/modules/composition/database/main.tf

• Dev deployment instances: terraform/aws/live/dev/eu-central-1/vpc-network/main.tf, terraform/aws/live/dev/eu-central-1/database/main.tf

dev, integ, prod, and sandbox are explicit deployment boundaries. Only dev has a detailed regional implementation in this tree; the others primarily provide scaffolding/readmes.

Network, Access, and Compute Foundation

The platform establishes a VPC-oriented private network, routing/ACLs/endpoints, security rules, an EKS cluster, and controlled administrative/proxy access. This is the foundational dependency chain for workloads and data stores.

• Network topology and endpoints: terraform/aws/modules/composition/vpc-network/main.tf, terraform/aws/modules/composition/vpc-network/vpc-endpoints.tf

• EKS cluster, node groups, add-ons, and IAM: terraform/aws/modules/composition/eks/main.tf, terraform/aws/modules/composition/eks/node-group.tf, terraform/aws/live/dev/eu-central-1/eks/main.tf

• Network-security deployment: terraform/aws/live/dev/eu-central-1/security-rules/main.tf

• Administrative jump host and outbound Squid proxy: terraform/aws/live/dev/eu-central-1/jump-host/main.tf, terraform/aws/live/dev/eu-central-1/squid-proxy/main.tf

AWS is the material runtime; Kubernetes/EKS hosts the application plane.

Application Delivery and Kubernetes Control Plane

EKS add-ons are provisioned separately from cluster creation, then application-level stacks configure Kubernetes resources and supporting controllers. Argo CD is present for GitOps-style deployment management; AWS Load Balancer Controller and Istio provide ingress/load-balancing and service-mesh capabilities.

• Kubernetes shared resources: terraform/aws/live/dev/eu-central-1/eks-kubernetes-resources/main.tf

• Argo CD: terraform/aws/live/dev/eu-central-1/apps/argocd/main.tf, terraform/aws/modules/application-resources/argocd/main.tf

• AWS Load Balancer Controller: terraform/aws/live/dev/eu-central-1/apps/alb-controller/main.tf

• Istio: terraform/aws/live/dev/eu-central-1/apps/istio/main.tf

• Hyperswitch workload integration: terraform/aws/live/dev/eu-central-1/apps/hyperswitch-app/main.tf, terraform/aws/modules/application-resources/hyperswitch/main.tf

The intended flow is edge/load-balancer traffic into EKS-hosted Hyperswitch services, with workload credentials and infrastructure dependencies assembled through Terraform.

Data, Secrets, and Application Dependencies

The deployment supports several persistence and caching/search systems, provisioned as independent stacks. This separation makes lifecycle, scaling, and access control distinct from the application workload.

• Relational database composition and dev stack: terraform/aws/modules/composition/database/main.tf, terraform/aws/live/dev/eu-central-1/database/main.tf

• Cassandra: terraform/aws/modules/composition/cassandra/main.tf, terraform/aws/live/dev/eu-central-1/cassandra/main.tf

• ElastiCache: terraform/aws/modules/composition/elasticache/main.tf, terraform/aws/live/dev/eu-central-1/elasticache/main.tf

• OpenSearch: terraform/aws/modules/composition/opensearch/main.tf, terraform/aws/live/dev/eu-central-1/opensearch/main.tf

• External Secrets Operator and Hyperswitch-specific secret integration: terraform/aws/live/dev/eu-central-1/apps/external-secrets-operator/main.tf, terraform/aws/live/dev/eu-central-1/apps/eso-hyperswitch/main.tf

KMS and S3 resources are integrated into the Hyperswitch application module:

• terraform/aws/modules/application-resources/hyperswitch/kms.tf

• terraform/aws/modules/application-resources/hyperswitch/s3.tf

Edge, Observability, and Validation

CloudFront is configured declaratively from distribution, policy, function, and origin configuration files, forming the public edge boundary for API, media, and web-app routes. Observability is Kubernetes-oriented: Vector collects logs, Loki stores them, and Grafana exposes visualization.

• CDN configuration: terraform/aws/live/dev/eu-central-1/cloudfront/main.tf, terraform/aws/live/dev/eu-central-1/cloudfront/config/distributions/api-cdn.yaml

• Envoy proxy configuration: terraform/aws/live/dev/eu-central-1/envoy-proxy/config/envoy.yaml

• Logging/visualization stacks: terraform/aws/live/dev/eu-central-1/apps/vector/main.tf, terraform/aws/live/dev/eu-central-1/apps/loki/main.tf, terraform/aws/live/dev/eu-central-1/apps/grafana/main.tf

• Load testing uses Python/Locust: load-test/locustfile.py, load-test/requirements.txt

GitHub Actions validate Terraform and generate module documentation:

• .github/workflows/terraform-validate.yml

• .github/workflows/terraform-docs.yml