Tyk Self-Managed (Non-MDCB) Rollback Guide

This guide outlines the standard procedures, component ordering, database considerations, and traffic guarantees when upgrading or rolling back a self-managed Tyk deployment (Gateway, Dashboard, Pump, Redis, and SQL/MongoDB) in a single-datacenter (non-MDCB) environment.


Summary of the Rollback Order

In a non-MDCB architecture, all components communicate directly via shared Redis and internal REST APIs. Rollback is the exact reverse of the upgrade sequence:

**Upgrade Sequence** : Tyk Dashboard → Tyk Gateway → Tyk Pump
**Rollback Sequence** : Tyk Pump → Tyk Gateway → Tyk Dashboard


Frequently Asked Questions

Q1: What is the proper rollback sequence for non-MDCB components?

When rolling back a non-MDCB stack, follow this sequence:

1. Pause / Disable Tyk Operator (if deployed):
Scale down or pause Tyk Operator reconciliations to prevent the operator from pushing configuration reloads during the rollback window.
2. Roll back Tyk Pump:
Scale down or revert Tyk Pump to the previous version. Since Pump processes analytics asynchronously from Redis out-of-band, pausing or downgrading it first prevents it from writing to a database undergoing restoration.
3. Roll back Tyk Gateway instances:

• Roll back Tyk Gateway nodes cluster-by-cluster (or via Kubernetes rolling updates with maxSurge: 1, maxUnavailable: 0).
• Running Gateways hold API configurations entirely in memory, ensuring active client traffic continues without drops.
• If custom Go plugins were recompiled for the newer version, deploy plugins compiled against the target rollback version alongside the Gateway pods.

4. Roll back Tyk Dashboard:

• Stop or scale down the Tyk Dashboard.
• If schema-altering configurations, new OAS endpoints, or database changes were introduced, restore the persistent database backup (PostgreSQL or MongoDB) before starting the prior Dashboard version.
• Start the previous version of the Tyk Dashboard and verify connectivity.

5. Re-enable Tyk Operator:
Re-enable the operator on the version compatible with the restored Dashboard.

Why this order?
Tyk Dashboard is the system of record. Reverting Gateways before the Dashboard prevents newer Gateway versions from requesting endpoints or schemas that an older Dashboard may not support.

Q2: Do we need to restore the Database (MongoDB/PostgreSQL) and Redis during rollback?

Persistent Database (MongoDB / PostgreSQL):

• Automated migrations run forward only: The Tyk Dashboard automatically executes forward migrations on boot (AutoMigrate for SQL/PostgreSQL and migrateSchemas on MongoDB). **The Dashboard does not execute downward/reverse migrations.**
• Patch releases (e.g., v5.13.4 to v5.13.1): Patch releases within the same minor LTS version do not introduce breaking database schema modifications. If no new APIs, policies, or schema extensions were added during the upgrade window, the older Dashboard version can safely read the existing database without requiring a database restore.
• Minor / Major releases or after creating new configurations: If you created new APIs/policies or upgraded across minor versions, you must restore your pre-upgrade database backup (mongorestore or pg_restore) while the Dashboard is stopped, prior to starting the older Dashboard version.

Redis:
DO NOT restore or wipe Redis during a rollback.
  - Redis stores active runtime state: live session tokens, OAuth authorization states, HMAC nonces, and sliding-window rate-limit counters.
  - Restoring an older Redis backup invalidates live tokens and resets active rate limits.
  - Older Tyk Gateways handle session objects written by newer patch releases gracefully by ignoring unfamiliar fields.

Important Note on Multi-Dashboard License Keys:
  - If performing rolling or blue-green updates where multiple Dashboard versions share the same Redis instance, **all Dashboards must share the exact same license key**. Different license keys cause node allocation pool mismatches (GetSpareNode returned node not allowed by this dashboard's license), blocking Gateway registration.

Q3: Will live API traffic be impacted while the Dashboard or Pump is being rolled back?
No. Live client API traffic is not interrupted when the Dashboard or Pump is undergoing rollback or maintenance:

1. In-Memory APISpec Cache:
   - Tyk Gateway loads and compiles all API definitions, middleware chains, certificates, and routing rules directly into memory (*APISpec).
   - Incoming proxy requests are executed entirely against memory. The Gateway never queries the Dashboard or persistent DB to evaluate an active client request.
2. Dashboard Outage Independence:
   - While the Dashboard is offline, Gateways continue serving traffic normally. The only temporary impact is management plane downtime: new APIs cannot be created and existing configurations cannot be updated.
   - If a Gateway pod restarts while the Dashboard is down, it uses its connection retry loop (executeDashboardRequestWithRecovery) and reconnects as soon as the Dashboard is available.
3. Decoupled Analytics via Pump & Redis:
   - Gateways write telemetry records into Redis queues (tyk.analytics).
   - Tyk Pump consumes these queues asynchronously in batches. If Pump is offline or rolling back, analytics records remain queued in Redis and are drained automatically as soon as Pump restarts, with zero impact on proxy throughput.