Who this is for: Automation engineers, platform reliability leads, and DevOps teams tasked with retiring n8n while keeping live workflows running. We cover this in detail in the n8n Architectural Decisions Guide.
Quick Diagnosis
- Export every workflow and credential from n8n.
- Deploy a read‑only “shadow” instance and import the exports.
- Translate each workflow to the new platform with an automated script.
- Run both systems side‑by‑side for two full business cycles, monitoring success rates.
- After validation, pause the n8n workflow, then decommission the n8n container after a 14‑day rollback window.
In practice this sequence keeps the SLA intact and provides a clear safety net.
1. Build a Comprehensive Phase‑Out Inventory
If you encounter any n8n critical path decision framework resolve them before continuing with the setup.
Why: Knowing exactly what must be moved prevents surprises later.
*The first step is always inventory; skipping it is a common cause of hidden dependencies.*
1.1 Workflow & Credential Details
| Asset | Where to Find | Export Method | Owner |
|---|---|---|---|
| Workflow JSON | n8n UI → Settings → Export | n8n export:workflow --id <ID> (CLI) |
Automation Lead |
| Credentials (API keys, OAuth) | Settings → Credentials | n8n export:credentials |
Security Officer |
1.2 Custom Code & Environment
| Asset | Where to Find | Export Method | Owner |
|---|---|---|---|
| Custom Nodes / npm packages | ~/.n8n/custom | tar -czf custom_nodes.tar.gz ~/.n8n/custom |
DevOps |
| Environment Variables | .env or Docker compose | cat .env > env.backup |
Platform Engineer |
1.3 Migration SLA Overview
| Asset | SLA for Migration |
|---|---|
| Workflow JSON | ≤ 5 days |
| Credentials | ≤ 3 days |
| Custom Nodes | ≤ 2 days |
| Environment Variables | Immediate |
Custom nodes often bite later; allocate sufficient time.
EEFA Note – Exported JSON may contain clear‑text secrets. Run the export through the redaction script before committing to source control.
Redact Secrets (Bash)
#!/usr/bin/env bash # Remove inline credentials from a workflow JSON file
jq 'walk(
if type=="object" and .type=="n8n-nodes-base.httpRequest"
then .parameters.auth = "***REDACTED***"
else .
end)' "$1" > "${1%.json}_redacted.json"
Running the script on a CI runner with limited permissions helps avoid accidental leaks.
2. Create a Parallel “Shadow” Environment
If you encounter any n8n in modern saas architecture resolve them before continuing with the setup.
Purpose: A sandbox that mirrors production lets you test migrations without risking live data.
*In production we typically spin this up in a staging namespace to keep it isolated.*
- Provision a clone using Docker Compose (or Helm) on a distinct sub‑domain, e.g.,
n8n-shadow.mycorp.com. - Import the redacted JSON files.
- Connect the shadow instance to a read‑only replica of the production database.
2.1 Spin‑up Commands
| Step | Command | Success Check |
|---|---|---|
| Start container | docker compose -f docker-compose.yml -p shadow up -d |
docker ps | grep shadow |
| Import workflow | n8n import:workflow --file workflow_redacted.json --overwrite |
Workflow appears in UI |
| Attach read‑only DB | Update DB_TYPE & DB_POSTGRESDB env vars |
No write errors in logs |
Never point the shadow instance at the primary DB; a stray write would corrupt live data and breach compliance.
3. Migrate Workflows One‑by‑One
3.1 Choose the Target Platform
| n8n Feature | Target Platform | Migration Path | Known Gaps |
|---|---|---|---|
| HTTP Request | Make (Integromat) | Export → HTTP module mapping | Limited retry policy |
| Webhook triggers | Custom Node.js server | Export → Express route generator | Auth handling must be re‑implemented |
| Database queries | Direct SQL scripts | Export → Parameterized query scripts | Transaction handling differs |
We usually start with the simplest HTTP nodes to validate the pipeline.
3.2 Automated Translation Script
The script converts n8n nodes to a generic JSON format that the new platform can ingest. Run it per workflow and commit the output.
The Python helper performs a thin mapping; it is not a full feature‑parity converter.
Imports & Helpers (Python)
#!/usr/bin/env python3 import json, sys
Node Translator (Python)
def translate_node(node):
if node["type"] == "n8n-nodes-base.httpRequest":
return {
"module": "http",
"method": node["parameters"]["method"],
"url": node["parameters"]["url"],
"headers": node["parameters"]
.get("options", {})
.get("headerParameters", {})
}
return None
Main Execution (Python)
def main(infile, outfile):
wf = json.load(open(infile))
translated = [
translate_node(n) for n in wf["nodes"] if translate_node(n)
]
json.dump({"steps": translated}, open(outfile, "w"), indent=2)
if __name__ == "__main__":
main(sys.argv[1], sys.argv[2])
3.3 Side‑by‑Side Execution
| Phase | Action | Validation Metric |
|---|---|---|
| Warm‑up | Enable new workflow in addition to the n8n version | Success ≥ 99 % of original |
| Shadow Run | Disable n8n trigger; keep webhook alive for fallback | Latency ≤ 200 ms, error ≤ 0.5 % |
| Cut‑over | Deactivate n8n node permanently | No alerts for 48 h |
During the warm‑up phase keep both versions running but route only a small sample of traffic to the new workflow.
EEFA Tip – Keep the original n8n workflow enabled but paused. This preserves node IDs that external systems may cache.
4. Data Consistency & State Transfer
Many workflows rely on run IDs, temporary files, or queued messages. Transfer them before the final cut‑over.
*In our experience, queues are the sneakiest source of data loss.*
If you encounter any automation boundaries n8n vs app resolve them before continuing with the setup.
| Asset | Transfer Method | Validation |
|---|---|---|
| Execution logs | n8n export:execution → import into target logging (ELK) |
Record count match |
Files in /data |
rsync -avz ~/.n8n/data/ target:/var/lib/target-data/ |
MD5 checksum equality |
| In‑flight queue messages | Pause producers, drain queue, replay to new system | Queue depth = 0 before cut‑over |
EEFA Note – For Redis‑backed queues, flush only the n8n namespace after confirming the new system has consumed all pending jobs:
redis-cli -n 0 DEL n8n:*
5. Monitoring, Alerting, and Rollback
5.1 Health Dashboard
Create a Grafana dashboard that shows both n8n and the new platform metrics.
Prometheus Exporter Snippet (YAML)
scrape_configs:
- job_name: 'n8n'
static_configs:
- targets: ['n8n-shadow.mycorp.com:9469']
Add a similar block for the target platform’s exporter.
*We typically set the alert thresholds a bit tighter than production to catch regressions early.*
5.2 Rollback Playbook
| Trigger | Immediate Action | Follow‑up |
|---|---|---|
| > 5 % error spike in target | Re‑enable original n8n workflow (unpause) | Open incident ticket, notify stakeholders |
| Missing data after migration | Switch DB read‑only back to primary, re‑run migration script with --force |
Post‑mortem, adjust mapping tables |
| Credential leak detected | Revoke compromised keys, rotate secrets, run redaction script again | Update secret store (e.g., Vault) |
EEFA Warning – Keep n8n credentials for at least 14 days after cut‑over; deleting them early removes the ability to roll back instantly.
6. Decommission the Production n8n Instance
- Drain all scheduled Cron triggers.
- Backup the Docker volume.
- Terminate the container or Helm release.
- Archive the backup in immutable storage (10‑year retention for audit).
Before deleting, double‑check that no scheduled jobs remain pending.
6.1 Decommission Commands
| Step | Command | Confirmation |
|---|---|---|
| Pause schedules | n8n schedule:pause-all |
n8n schedule:list shows “paused” |
| Backup volume | docker run --rm -v n8n_data:/data -v $(pwd):/backup alpine tar czf /backup/n8n_final_backup.tar.gz /data |
SHA‑256 hash matches source |
| Delete container | docker rm -f n8n-prod |
docker ps no longer lists n8n |
| Archive to Glacier | aws s3 cp n8n_final_backup.tar.gz s3://corp-archives/n8n/ --storage-class GLACIER |
S3 console shows “Glacier” class |
Verify that no external system still points to the old webhook URL. Keep a DNS wildcard (*.old-n8n.mycorp.com) that returns 410 Gone for an extra 30 days.
Conclusion
Export assets, clone a read‑only shadow, translate workflows incrementally, and run both stacks side‑by‑side to achieve a zero‑downtime n8n retirement. The staged approach preserves data integrity, offers a clear rollback window, and satisfies compliance audits. Follow the tables, scripts, and monitoring checklist above to decommission n8n safely in any production environment.
