Provision infrastructure using Terraform

How a production grade Hyperswitch stack is provisioned using Terraform? An explanation of steps involved and infra automation coverage across cloud providers.

---

Deploy with Terraform

This page covers Milestone III of the production certification process. The approach is same across every cloud: how the code is organized, the steps to reach a working production stack, and how much of each layer is automated. The per-cloud pages cover the detailed devops installation engineering steps to be done on specific cloud provider.

Approach

Terraform provisions cloud infrastructure. It builds the cloud resources Hyperswitch needs, including the workload identities and encryption keys the pods assume

ArgoCD acts application management layer. It installs Hyperswitch related applications using the helm charts. It provides the release management tooling like staggered rollouts, A/B during and rollback to ensure reliability during the change management process.

Terragrunt to manage multiple environments or stacks. It runs Terraform underneath and adds the things Terraform lacks once you have more than one environment. It include composing whole environments, passing output from one state to another, keeping the modules external and pinned.

Layer	Owns	Tool	Lives in
Infrastructure	Network, Kubernetes cluster, databases, cache, identity, keys, load balancers	Terraform via Terragrunt	Your infrastructure repo
Applications	Router, payment methods, connector service, card vault, Control Center, Superposition, monitoring	Helm charts reconciled by ArgoCD	Your GitOps repo

The reference Terraform lives in the public juspay/hyperswitch-suite repo. Your infrastructure repo shall not copy it. Instead it shall reference each unit references it by pinned tag:

terraform {
  source = "git::https://github.com/juspay/hyperswitch-suite.git//terraform/<cloud>/modules/<module>?ref=<pinned-tag>"
}

Terragrunt composes those modules. You do not write Terraform. The layout will be identical on every cloud:

terraform/
├── catalog/
│   ├── units/<name>/     Reusable building blocks
│   └── stacks/<name>/    Compose units into a full environment, in order
└── <cloud>/
    ├── modules/          A few internal-only application modules
    └── live/<env>/<region>/<component>/
                          Real deployments — thin configs pointing at a unit

A new region or environment means adding a live/<env>/<region>/ directory following the existing pattern.

Primary regions are hand-authored unit by unit.

DR regions are generated from a stack with terragrunt stack generate.

Terragrunt is required, and tags are not optional. If your team standardized on plain Terraform, raise it before you start. And never change ?ref=<tag> to a branch — that means your infrastructure changes on someone else's merge, with no pull request in your repo.

Greenfield or Brownfield?

Lets revisit Decision III. The choice, will impact how much work steps 6 and 7 below involve.

	Greenfield Installation (Path A1)	Brownfield Installation (Path A2)
Starting point	A fresh cloud account	An existing landing zone inside your existing cloud account
Network, routing, keys	Provisioned for you	You supply them as inputs
Customization step	Everything is pre-configured for production.	Required, and external resources must be wired into the IaC

Most organizations deploying Hyperswitch already have a landing zone, an account hierarchy and network standards. The units are built to attach to what you already run rather than duplicate it.

---

Steps to install production-grade stack

The production installation to health verification take approximately 12 hours of hands-on work.

It involves 12 steps across 4 phases to install hyperswitch and test a payment flow working end-to-end.

The stated time assumes that the Milestones I and II of the production certification process are already completed; and prerequisites stated in

is a working estimates including a buffer for misconfiguration and debugging.

The stated time does not include additional time for your own infra change approval cycles.

Phase 1: Prepare

#	Step	Time	What it does?
1	Arrange the prerequisites	—	Cloud account and organization permissions, domain and TLS certificate, at least one payment processor credential is arranged On brownfield installation your network and subnet identifiers are arranged. See prerequisites below for complete list.
2	Install and verify local tooling	0.5 h	Helm, kubectl, Terraform, Terragrunt and your cloud provider CLI on the operator's work device. All verified before proceeding

Phase 2: Provision the infrastructure

#	Step	Time	What it does?
3	Bring up the cloud infrastructure with Terragrunt	4.0 h	This cover bulk of the infra automation. Network, Kubernetes cluster, databases, cache, card vault infrastructure, workload identity, keys and load balancers, object storage resources - all applied in dependency order.
4	Verify the infrastructure components	0.5 h	Confirm the cluster is reachable and nodes are spread across zones, the databases and cache are reachable from the cluster and only from the cluster, and state is remote, encrypted and lock-protected.
5	Install the application management layer — ArgoCD	0.5 h	Installs the GitOps controller and the platform components it depends on: the cloud ingress controller, External Secrets Operator, and the ArgoCD app-of-apps that will manage everything else.
6	Set up External Secrets Operator	0.5 h	Points the cluster at your managed secret store and declares which secrets to sync. Credentials never enter Helm values or Git; ESO pulls them at runtime and materializes them as ordinary Kubernetes secrets

Phase 3: Deploy and verify the applications

#	Step	Time	What it does?
7	Apply customizations for your infra landing zone	2.0 h	Brownfield only. Wire externally created resources into the application values: ingress and egress paths, database and cache URLs, payment connector URLs, domain mapping and SMTP. This could be the step requiring more iterations in the sequence, since it is manual, and it touches every component. Greenfield deployments typically skip it.
8	Deploy all Hyperswitch components using ArgoCD	2.0 h	ArgoCD applications pointing at the public Helm charts bring up the router, payment methods, connector service, card vault, Control Center, Superposition, encryption service and monitoring.
9	Verify with deep health checks	0.5 h	Confirm Helm releases and pod status across every component. This checks that the installation is healthy, not that the product works.
10	Test the backend application with APIs	0.1 h	Generate an API key and call the payment-create API. First proof that the stack processes a request end to end.

Phase 4: Configure and test the production stack

#	Step	Time	What it does?
11	Update Control Center and SDK environment configuration	0.1 h	Applied through ArgoCD so the change is declared in Git rather than made by hand.
12	Configure the payment stack and test end to end	0.5 h	Configure connectors, routing and payment methods through the Control Center, then test both the APIs and the SDK checkout flow.

After step 12 you have a working deployment and Milestone III, is completed.

Completion of Milestone III, does not result in a production-grade setup. Complete Milestone IV to be completed for hardening — proving recovery, proving capacity, closing PCI items.

---

Prerequisites

Milestone I and II artifacts

• A signed-off blueprint with no open architectural decisions.

• Custom Terraform chart and Helm values for your production deployments.

Tooling

Tool	Version
Terraform	1.12.1
Terragrunt	1.1.1
kubectl	1.33+
Helm	3.0+
Kubernetes	1.34+
Cloud provider CLI	AWS CLI: v2.35.x Google Cloud CLI: 583.0.0 Oracle OCI CLI: v3.91.0

Access & credentials

• Cloud access — an apply identity able to create network, Kubernetes, database, cache, identity and key management resources. Not an administrator role. For CI, use workload identity federation rather than long-lived credentials.

• Network and DNS — a domain you control with DNS management access, and TLS certificates or the ability to issue them.

• In case of brownfield installation

  • Network and subnet identifiers,

  • routing model,

  • permissions boundary,

  • existing key identifiers,

  • logging destinations, and

  • Egress or proxy restrictions.

• Payment processor credentials — at least one processor account with production credentials, will be needed at Step 12.

People

• This could take the longest lead time, and critical as much as any tool:

  • Key custodians — named individuals to generate and hold custodian keys, and to unlock the vault

  • A change approver, if production applies require sign-off

  • A security reviewer, if account access needs approval

  • A single technical SPOC, to work with Juspay team and co-ordinate across the above owners