Back to blog

CloudHub 1.0 → 2.0 migration pitfalls to fix before cutover

2026-09-17

Migrating CloudHub 1.0 → CloudHub 2.0 means moving from workers to container replicas and from VPC/DLB to a Private Space with managed ingress — not redeploying the same JAR. Official tooling (VPC upgrade + application linking with weighted traffic) shortens the infrastructure path, but it does not redesign patterns CloudHub 2.0 deliberately does not support: persistent VM queues, CloudHub Connector, Insights, JVM overrides, TLS 1.0, or Mule below 4.3.

What this piece is not: a marketing checklist that says “move and forget.” It is a practitioner cutover guide for architects and integration leads planning the VPC upgrade tool, app linking, and a traffic ramp — before partners see timeouts and the team deletes CloudHub 1.0 too early.

Below: the CH1→CH2 deltas that actually break migrations, pitfall cards (symptom → cause → docs → pattern), an ordered checklist, and AEO-ready FAQ.

CH1 vs CH2 in brief (only what breaks migrations)

Workers → replicas, VPC → Private Space, DLB → managed ingress

On CloudHub 1.0 an app runs on workers (VMs) in a VPC, optionally behind a Dedicated Load Balancer. On CloudHub 2.0 it runs on replicas (containers) in a Private Space with an automatically provisioned ingress load balancer. App names are unique within a Business Group / Private Space (not per whole control plane as on CH1). Outbound static IPs on CH2 are at Private Space level (shared by apps), not per-app as with Static IPs on CH1.

Source: CloudHub 2.0 for CloudHub 1.0 Users, Migration Configuration.

What is officially unsupported

Before you click Upgrade, inventory should catch at least:

Area Status on CH2
Mule < 4.3.0 Not supported
Persistent VM queues Not supported — use an external broker (e.g. Anypoint MQ)
CloudHub Connector Not supported
Custom notifications / Insights Not supported → Anypoint Monitoring
Overwriting JVM parameters / custom JVM truststore Not supported
TLS 1.0 Not supported (use 1.2 / 1.3)
VPN between CH1 VPC and CH2 Private Space Impossible
VPC peering / Direct Connect Deprecated on CH2 → Transit Gateway / VPN

Source: ch2-comparison — Considerations and Limitations.

The official upgrade-tool blog is explicit: tooling supports simple-to-moderate cases; complex scenarios need customization before migration — not “zero redesign.”

Pitfall #1: Persistent VM queues → Anypoint MQ / broker

Why CH2 does not support persistent VM queues

Symptom: after deploy to CH2 the “Persistent queues” option is gone; or a VM queue loses messages after restart / crash.

Cause: container architecture with volatile storage. Local persistent="true" on container disk does not survive restart or redeploy. Official path: external broker.

Docs: “Use Anypoint MQ for persistent queues… Persistent queues are not supported.” (ch2-comparison); migration requires removing persistent queues and implementing Anypoint MQ (migration-configuration); blog Transition from Persistent VM Queues… (2024-08-15) points to Anypoint MQ, Kafka/MSK, JMS, etc.

Replacement patterns + clustering with schedulers

  1. Inventory all vm:publish / vm:consume and the Persistent queues flag in Runtime Manager.
  2. Replace with publish → Anypoint MQ (or Kafka/MSK/JMS) + subscriber flow.
  3. If the source is a scheduler and you have ≥2 replicas: enable Runtime Cluster Mode (requires min. 2 replicas). Without it every container fires the scheduler → duplicates.
  4. State that used to “persist” locally → Object Store v2 — CH2 clears local disk on restart (ch2-clustering).
  5. Configure egress to MQ hosts (pitfall #4).

Practical HA/cluster context: CloudHub 2.0 Part II – Shared Space in HA and Cluster Mode. Upgrade-tool path: VirtualMuleys103 – Upgrade Tool Overview and the official VPC→Private Space demo.

Pitfall #2: CloudHub Connector and custom notifications

Symptom: deploy or runtime fails on CloudHub Connector; CH1 custom alerts go silent; Insights unavailable.

Cause: CH2 does not support CloudHub Connector, custom notifications, or Insights.

Docs: unsupported list in ch2-comparison; migration-configuration: Remove CloudHub Connector and replace with custom logic; alerting via Anypoint Monitoring.

Pattern: before migration, grep for CloudHub Connector dependency and notification flows. Move alerts to Anypoint Monitoring (per-app). Operational status via REST/API Manager or your own endpoints — not the platform connector.

Pitfall #3: Networking — Peer/DC, TGW/VPN, dual-AZ static IPs

VPC upgrade eligibility

The VPC upgrade tool clones CIDR and (when present) TGW/VPN into a Private Space — but only for eligible VPCs:

  • ≥ 25% free space and ≥ 100 free IPs per subnet
  • Legacy VPN disqualifies
  • Direct Connect / Peering → migrate to Transit Gateway or VPN first
  • TLS 1.1 SHA1 ciphers (ECDHE-*-AES*-SHA1) do not carry over
  • Firewall ports other than 80, 443, 30500–32500 drop on migration
  • TCP traffic: HTTP/HTTPS OK; tooling does not migrate TCP

Source: vpc-upgrade — Eligibility.

Peering does not migrate; CH1↔CH2 VPN forbidden

Peering stays on the old VPC — CH2 apps cannot use it. You cannot create a VPN between a CH1 VPC and a CH2 Private Space (ch2-comparison). For partial migration CH2→CH1 via DLB, add CH2 infrastructure CIDRs to the DLB allowlist: 100.64/66/67/68.0.0/16 (vpc-upgrade).

Dual-AZ IPs: the tool discovers two AZs → two sets of inbound/outbound static IPs. On CH2 IPs are shared at Private Space level; unique IPs per app = separate Private Space (migration-configuration — Static IP Addresses). Before cutover: export new IPs → notify partners / firewall team. During upgrade, entitlement counts are doubled — align with your account rep.

Pitfall #4: Egress — “everything worked on CH1”

Symptom: app starts, but publish to Anypoint MQ, Object Store v2, or platform calls time out / return 500; logs show Failed to send request.

Cause: CH1 allowed all outbound without egress rules. CH2 has an egress firewall (Private Space + optional app-level). Removing the default allow-all without rules to Anypoint services blocks traffic (vpc-upgrade, migration-configuration).

Pattern (from App-level Egress Control blog, 2024-02-06):

  • Do not remove allow-all until you have a replacement.
  • Rule groups per app class (MQ, OSv2, Salesforce, ERP).
  • For Anypoint MQ typically: HTTPS to anypoint.mulesoft.com and the regional host, e.g. mq-eu-central-1.anypoint.mulesoft.com (host from the connector URL).
  • For OSv2: anypoint.mulesoft.com + object-store-<region>.anypoint.mulesoft.com.
  • Test connectivity before the first % of traffic.

Source: App-level Egress Control.

Pitfall #5: Traffic % linking, SLB vs DLB, default *.cloudhub.io

Symptom: after Save Changes on % traffic, some or all traffic disappears; switching takes the “wrong” path.

Cause — traffic source inference (app-migration — Understanding the Traffic Source):

  • Presence of default endpoint <app>..cloudhub.io ⇒ switching via SLB
  • No default + vanity / anypointdns.net ⇒ DLB
  • Using inherited *.cloudhub.io on the CH2 app breaks inference and can cause outage

Also: without CloudHub Network Administrator permission the switch fails; restart the DLB before switching; the CH1 app must stay STARTED until the link is established.

Pattern: explicitly choose SLB vs DLB path; for DLB keep vanity/anypointdns.net (no default cloudhub.io on CH2). Ramp: 5% → 25% → 50% → 100% with a rollback plan. HTTPS DLB: Last-Mile Security + Upstream TLS 1.2+. If you rename the CH2 app, put the old CH1 name in the Ingress subdomain — otherwise traffic will not arrive.

Pitfall #6: Properties, protected values, API policies under parallel traffic

Properties and the ****** trap

Upgrade copies properties in the UI, but they do not persist until you edit ≥1 property or add a new one. Protected props show as ****** — you must manually enter the real value (app-migration — Application Properties).

Pattern: secure-props checklist from vault/secret manager; after upgrade: “touch” one property + re-enter all protected values; verify in non-prod before linking.

API policies under split traffic

Both apps are active; stateful policies (cache / counters) do not share state. Rate-limiting under round-robin can behave like ~2× the limit; a hard cut ≈ resets counters. Applies to e.g. rate-limiting, rate-limiting-sla-based, spike-control, OAuth/JWT/caching policies (app-migration — Managing API Policies).

Pattern: duplicate equivalent policies on the CH2 API instance before % traffic; for rate-limit consider temporary loosen or hard-cut in a low-traffic window; watch 429s and auth errors during the ramp. Autodiscovery may attach both apps to the same API in API Manager.

Cutover checklist (order)

  1. Inventory — persistent queues, CloudHub Connector, ports ≠ 80/443/30500–32500, TLS 1.0/1.1 SHA1, Mule < 4.3, JVM overrides, Insights/custom notifications, partner outbound allowlists.
  2. VPC eligibility — free IP %, legacy VPN, Peer/DC → TGW/VPN, default VPC disabled.
  3. Code redesign — MQ/broker, connector out, OSv2 instead of local disk, runtime ≥ 4.3, pom.xml for two-step CH2 deploy (Exchange → deploy).
  4. Private Space / VPC upgrade tool — space name, reserved CIDR if needed; TLS certs manually if best-effort migrate failed; doubled entitlements with account rep.
  5. Egress — Private Space + app-level rules to MQ/OSv2/API Manager before production traffic.
  6. Deploy CH2 — no inherited default *.cloudhub.io; vanity/anypointdns.net; Last-Mile Security when HTTPS.
  7. Properties — touch + re-enter ******; non-prod smoke test.
  8. Link + % traffic — Network Admin; restart DLB; CH1 STARTED; ramp 5→25→50→100; rollback = lower % / restart CH1.
  9. API policies — equivalent config on CH2; monitor 429/auth.
  10. Stop CH1 within 30 days after 100% → delete within the next 30 days; then no rollback and no recreating CH1 with the same name (app-migration — Complete the Application Upgrade).
  11. DLB failover → stop/delete DLB; after DLB delete there is no rollback.
  12. Cleanup VPC after all apps — release CH1 entitlements.

FAQ

1. How is CloudHub 1.0 → 2.0 migration different from a normal redeploy?

Redeploy assumes the same runtime and network model. CH1→CH2 changes the execution model (workers → replicas), networking (VPC/DLB → Private Space + managed ingress), and the supported-feature list. Patterns based on persistent VM queues, CloudHub Connector, or “all outbound” assumptions need redesign before cutover; upgrade tooling helps with infrastructure and % traffic but does not close those gaps automatically.

2. Does CloudHub 2.0 support persistent VM queues?

No. The comparison docs state plainly that persistent queues are not supported and you should use Anypoint MQ (or another external broker). A local object store with persistent="true" on disk also does not survive restart on CH2 — use Object Store v2 for state across restarts.

3. What replaces CloudHub Connector and custom notifications?

Remove CloudHub Connector from the app and replace with custom logic / API calls. Custom notifications and Insights do not work on CH2 — configure alerts in Anypoint Monitoring (per application).

4. What does the VPC upgrade tool do — and what does it not move?

It clones an eligible VPC into a Private Space (same CIDR), moves TGW/VPN when present, and migrates DLB certificates best-effort. It does not migrate peering; does not support legacy VPN; does not carry TLS 1.1 SHA1 ciphers; drops non-standard firewall ports outside 80/443/30500–32500; does not migrate TCP traffic. You cannot VPN CH1 VPC ↔ CH2 Private Space.

5. Why must business partners update IP allowlists after migration?

Upgrade/migration typically creates a Private Space with two AZs, hence two inbound/outbound static IP sets. On CH2 those IPs are shared at Private Space level, not per application as often on CH1. Old allowlists based on a single worker IP are no longer enough.

6. How does % traffic switching work and when can I roll back?

After linking CH1 and CH2 apps you set traffic percentage in Runtime Manager (Finish Upgrade). Rollback during verification: lower % or restart CH1 and restore traffic. Required: Network Administrator permission, DLB restart before switching, CH1 in STARTED state. SLB vs DLB inference depends on whether default *.cloudhub.io is present in endpoint config.

7. What happens if I delete the CloudHub 1.0 app after migration?

After full redirect: stop CH1 within 30 days, then delete within 30 days. While CH1 exists (even stopped), you can return via restart + % traffic. After delete migration is complete: you cannot recreate a CloudHub 1.0 app with the same name. Same irreversibility after DLB delete.

8. Why can Anypoint MQ / Object Store v2 fail despite correct code (egress)?

Because egress on CH2 is controlled. Removing default allow-all or enabling app-level egress without rules to anypoint.mulesoft.com and regional MQ/OSv2 hosts blocks connections — the app starts, platform calls fail. Configure rules and test before the traffic ramp.

9. Do I need Runtime Cluster Mode with a scheduler on multiple replicas?

Yes, if the scheduler is the source and you have ≥2 replicas. Without cluster mode each container fires the scheduler → duplicate processing. Cluster mode requires at least two replicas; the primary runs the scheduler, others consume from the broker. With cluster mode + OSv2 together, manage metered OSv2 usage deliberately.

10. Is Runtime Fabric the same as CloudHub 2.0?

No. CloudHub 2.0 is MuleSoft’s managed container platform (Shared/Private Spaces). Runtime Fabric is a different deployment model (customer-managed / self-managed Kubernetes control). Choosing RTF vs CH2 is a separate architecture decision — not this CH1→CH2 cutover.

Soft CTA

Planning a CloudHub 2.0 cutover and want a second pair of eyes on queue inventory, egress, and the % traffic plan? Solita is a Nordic MuleSoft partner with delivery from Poland (EU-shoring) — we help teams build a migration runbook without blind lift-and-shift. No “#1” claims and no marketing checklist: a concrete pitfall review before day D.

Sources

Official documentation

Official MuleSoft blogs

How-to video (verified titles / oEmbed)