Upgrade Hyperswitch

GitOps-Based Deployment using ArgoCD (App-of-Apps Pattern)

Using a GitOps orchestration platform such as Argo CD allows Hyperswitch deployments to be managed declaratively via Git.

Benefits include:

• Version-controlled deployments
• Automated reconciliation and drift detection
• Reproducible environments
• Simplified rollbacks
• Centralized multi-cluster management

Instead of manually executing Helm commands such as:

helm upgrade --install hyperswitch ...

the desired deployment state is defined in Git and continuously reconciled by ArgoCD.

This guide uses ArgoCD, but similar GitOps tools can be used.

Target Architecture

A blue/green cluster upgrade model is recommended.

This strategy involves provisioning a parallel environment (green) where the upgraded version of Hyperswitch is deployed and validated before production traffic is switched over.

The existing environment (blue) continues serving live traffic during this process, allowing controlled cutover and providing a straightforward rollback mechanism if any issues arise after the upgrade.

During upgrade:

Stateful infrastructure such as databases should not be recreated during cluster upgrades.

ArgoCD App-of-Apps Pattern

The diagram illustrates how Hyperswitch deployments are managed using the App-of-Apps pattern in Argo CD.

In this model, a single “Root Application” manages multiple child applications, allowing complex systems to be deployed and maintained in a structured and scalable way.

1. Git Repository All deployment configurations are stored in a Git repository. This includes the ArgoCD application definitions and Helm chart references that describe the desired state of the system.
2. ArgoCD ArgoCD continuously monitors the Git repository and ensures that the Kubernetes cluster matches the configuration defined in Git. Any changes committed to the repository are automatically synchronized to the cluster.
3. Root Application (App-of-Apps) The Root Application acts as the entry point for the deployment. Instead of directly deploying services, it references multiple child applications. This structure is known as the App-of-Apps pattern, where one parent application manages a collection of related applications.
4. Environment Applications The Root Application deploys environment-level applications (for example: Dev, Staging, Production). Each environment application contains configuration specific to that environment.
5. Helm Applications Each environment application then deploys individual Helm-based applications, which package and deploy specific components of the system.
6. Hyperswitch + Platform Components These Helm applications ultimately deploy Hyperswitch services and supporting platform components into the Kubernetes cluster.

Using the App-of-Apps pattern allows teams to manage large deployments in a modular, hierarchical structure, making it easier to organize environments, promote changes across stages, and maintain consistency across clusters.

1. Prepare the GitOps Repository Structure

The App-of-Apps pattern organizes deployments hierarchically.

Example repository layout:

infra-gitops/

applications/
  root-app.yaml

environments/
  production/
    hyperswitch-v1.yaml
    hyperswitch-v2.yaml

apps/
  hyperswitch/
    application.yaml
    values-prod.yaml

  platform/
    ingress.yaml
    cert-manager.yaml
    monitoring.yaml

Structure overview:

This structure enables environment isolation and reusable application definitions.

2. Provision the New Kubernetes Cluster

Provision a new cluster for the upgraded deployment.

Supported platforms include:

• managed Kubernetes services
• self-managed Kubernetes clusters
• on-prem Kubernetes environments

Verify cluster connectivity:

kubectl get nodes

Recommended cluster baseline:

3. Install ArgoCD

Install ArgoCD on a management cluster or a designated platform cluster.

Installation example:

kubectl create namespace argocd

kubectl apply -n argocd \
-f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

Verify installation:

kubectl get pods -n argocd

Access the UI:

kubectl port-forward svc/argocd-server -n argocd 8080:443

Production deployments should expose ArgoCD through:

• secure ingress
• TLS certificates
• SSO authentication

4. Register Clusters in ArgoCD

Register target clusters so ArgoCD can deploy applications.

argocd cluster add <cluster-context>

Example clusters:

ArgoCD can then deploy applications to multiple clusters.

5. Deploy the Root Application (App-of-Apps)

The root application manages all other applications.

Example:

applications/root-app.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hyperswitch-root
spec:
  project: default

  source:
    repoURL: https://github.com/your-org/infra-gitops
    targetRevision: main
    path: environments/production

  destination:
    server: https://kubernetes.default.svc
    namespace: argocd

  syncPolicy:
    automated:
      prune: true
      selfHeal: true

Apply:

kubectl apply -f applications/root-app.yaml

ArgoCD will now automatically deploy all applications defined in the repository.

6. Define Cluster Applications

Environment files define which applications are deployed to each cluster.

Example:

environments/production/hyperswitch-v2.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hyperswitch-v2
spec:
  project: default

  source:
    repoURL: https://github.com/your-org/infra-gitops
    targetRevision: main
    path: apps/hyperswitch

  destination:
    server: https://kubernetes.default.svc
    namespace: hyperswitch

Each environment can deploy different versions or configurations.

7. Deploy Hyperswitch via Helm

The Hyperswitch application definition references the Helm chart.

Example:

apps/hyperswitch/application.yaml

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: hyperswitch
spec:
  project: default

  source:
    repoURL: https://github.com/juspay/hyperswitch
    chart: hyperswitch-stack
    targetRevision: <chart-version>

    helm:
      valueFiles:
        - values-prod.yaml

  destination:
    server: https://kubernetes.default.svc
    namespace: hyperswitch

  syncPolicy:
    automated:
      prune: true
      selfHeal: true

ArgoCD will automatically:

• pull the Helm chart
• apply configuration
• maintain cluster state

8. Plan Database Migration

Database schema changes must be handled carefully.

Disable automatic migrations during upgrade:

hyperswitch-app:
  migrations:
    enabled: false

Recommended process:

1. Deploy new Hyperswitch version.
2. Ensure application pods are not receiving production traffic.
3. Create database backup or snapshot.
4. Run migration job.
5. Validate schema changes.
6. scale application replicas.

Example:

kubectl scale deployment hyperswitch --replicas=3

9. Gradually Shift Traffic

Traffic should be migrated progressively to the new cluster.

Traffic management options:

Example rollout plan:

10. Validate System Health

Monitor the deployment during rollout.

Key metrics include:

Observability dashboards should be available before rollout.

11. Decommission the Previous Cluster

After the rollout stabilizes:

1. confirm that all traffic flows to the new cluster.
2. monitor system stability.
3. retain the old cluster for a rollback window.
4. decommission the cluster once the upgrade is confirmed.

Typical retention window: 24–72 hours.

Rollback Strategy

Traffic rollback

Redirect traffic back to the previous cluster.

Application rollback

Update the Git configuration to the previous version:

targetRevision: <previous-chart-version>

Commit the change and ArgoCD will automatically synchronize.

Enterprise Best Practices