CloudHub 1 to CloudHub 2.0 Migration Whitepaper

1. Executive Summary

CloudHub 2.0 is MuleSoft's next-generation, container-based iPaaS runtime plane built on Kubernetes. It offers improved resource isolation, enhanced security controls, greater deployment flexibility, and a more modern networking model compared to CloudHub 1. MuleSoft has announced the end-of-life timeline for CloudHub 1, making migration to CloudHub 2.0 a strategic priority for all organizations.

2. Key Differences: CloudHub 1 vs CloudHub 2.0

Reference: Understand the Difference- CH1 vs CH2

3. Pre-Migration Planning

3.1 Inventory & Assessment

• Audit all CH1 applications: List all deployed apps, their Mule runtime versions, vCore allocations, and environments (Dev, UAT, Prod).
• Document custom properties: Capture all application properties, secure properties, and environment-specific configurations.
• Review VPC configuration: Document CIDR ranges, firewall rules, dedicated load balancers, internal DNS entries, TLS certificates/contexts and private connections (VPN/Direct Connect/VPC Peering/TGW).
• Identify runtime versions: CH2 requires Mule 4.4+. Applications on older runtimes must be upgraded first.
• List all connectors and dependencies: Verify connector compatibility with CH2. Most connectors are compatible, but check for any proprietary or custom connectors.
• Assess Object Store usage: Object Store v2 is supported in CH2 with the same API.
• Review Anypoint MQ usage: Anypoint MQ is fully supported in CH2.
• Check Scheduler applications: CH2 handles schedulers differently — review Mule Scheduler components:
• Reference: https://docs.mulesoft.com/cloudhub-2/ch2-manage-schedules

3.2 Runtime Version Requirements

Important: CloudHub 2.0 supports only Mule Runtime 4.4 and above. Applications running on Mule 4.3 or earlier must be upgraded before migration.

• Mule 4.4.x → Supported 
• Mule 4.5.x / 4.6.x / 4.7.x → Supported 
• Mule 4.3.x and below → Must upgrade 
• Mule 3.x → Not supported — requires re-architecture 

3.3 Stakeholder Alignment

• Identify application owners and business stakeholders.
• Define migration windows (prefer off-peak hours).
• Communicate expected downtime (if any) per application.
• Establish rollback criteria and procedures.

4. Environment Setup: Private Space Configuration

CloudHub 2.0 uses Private Spaces instead of VPCs. This is the networking foundation for your CH2 deployment. There are two ways to migrate from Cloudhub 1.0 to Cloudhub 2.0.

4.1 Manually Create a Private Space

4.1.1 Create a Private Space

For scenarios where CloudHub 1 and CloudHub 2.0 must coexist within the same network architecture, ensure a new CIDR block is allocated specifically for the CloudHub 2.0 environment to prevent network overlap. Please refer the documentation Create a Private Space:

1. Navigate to Anypoint Platform → Runtime Manager → Private Spaces.

2. Click Create Private Space and provide a name.

3. Click Create Private Network.

4. Select the region.

5. Define the CIDR block for the Private Space network (must not overlap with on-premises or other cloud networks).

4.1.2 Configure Firewall Rules (Private Space)

• By default, all traffic to your private space is blocked unless it’s explicitly allowed in a firewall rule.

• Please refer to documentation Configure Firewall Rules

4.1.3 Configure Connections (VPN / Transit Gateway)

• Re-establish VPN tunnels or Transit Gateway attachments to the new Private Space.

• Validate routing tables to ensure traffic flows correctly.

• Test connectivity from on-premises systems to the Private Space before migrating applications.

4.1.4 Configure SSL Endpoints

• Configure SSL certificates on the load balancer.

• Update DNS records (CNAME) to point to the new load balancer endpoint.

4.1.5 Prepare Application for CH2

1. Update Mule Runtime to 4.4+ in your POM file if needed.

2. Review connector versions: update to latest compatible versions.

3. Update mule-artifact.json: ensure minMuleVersion is set correctly.

4. Remove CH1-specific configurations such as:

   1. http.port / https.port/http.private.port/https.private.port → CH2 uses standard ${http.port} (8081).

5. Test locally using Anypoint Studio with the updated runtime.

6. Rebuild and package the application JAR.

4.1.6 Configure Application Properties in CH2

• Navigate to Runtime Manager → Deploy Application (select CH2 / Private Space).

• Recreate all application properties (plain and secure/encrypted).

• Secure properties use the same encryption key mechanism — ensure keys are migrated.

• Environment-specific properties should be configured per environment (Dev, UAT, Prod).

4.1.7 Deploy to CloudHub 2.0

1. In Anypoint Platform → Runtime Manager, click Deploy Application.

2. Select CloudHub 2.0 as the deployment target.

3. Choose the appropriate Private Space.

4. Configure:

   1. Replica count and replica size (equivalent to vCores in CH1).

   2. Runtime version (4.4+).

   3. Application name — must be unique within the organization.

5. Upload the application JAR or link to Exchange.

6. Set all required properties and secure properties.

7. Click Deploy.

4.1.8 Auto-Scaling Configuration

• Enable Horizontal Auto-Scaling if needed (CH2 supports this natively).

• Set minimum and maximum replica counts.

• Define scaling metrics (CPU/memory thresholds).

4.2 VPC to Private Space Upgrade Using VPC Upgrade Tool 

If you have an existing CH1 VPC, you can upgrade it to a CH2 Private Space via the Anypoint Platform VPC Upgrade Tool.

4.2.1 Upgrade VPC 

Before using the tool, understand the eligibility and work with your Account Team to ensure you remain compliant with entitlements.

1. Go to Anypoint Platform → Runtime Manager → VPCs.
2. Select the VPC you want to upgrade.
3. Click Upgrade to Private Space.
4. Review the pre-flight checks — the platform will validate:
   1. CIDR block compatibility
   2. Firewall rules migration
   3. Associated DLB configurations
5. Confirm and initiate the upgrade.

Monitor progress in the Notifications panel.

Note: During VPC upgrade, existing CH1 applications continue running uninterrupted. The upgrade creates a new Private Space backed by the same network configuration (CIDR, Firewall Rules, Private Connections).

4.2.2 Validate the Private Space

• Confirm Private Space appears under Runtime Manager → Private Spaces.
• Verify firewall rules are correctly copied.
• Test VPN/TGW connectivity.

4.2.3 Migrate Applications 

Reference: CloudHub to CloudHub 2.0 Application Migration

• Go to Runtime Manager → Applications.
• Select app → Settings → Upgrade to CloudHub 2.0.
• Configure: App name (can change) and Deployment target (auto-selected as the Private Space)
• Provide application: Upload jar file OR import from Exchange
• Configure Ingress 
• Deploy to CloudHub 2.0.

4.2.4 Traffic Switching

• Both CH1 and CH2 apps run in parallel. 
• You can use the slider on the CH2 app in Runtime Manager to perform a gradual traffic shift of 0-100%.
• Roll back the traffic to the CH1 app by setting slider to 0% in case of connectivity issues.

4.2.5 Traffic Cutover

• After traffic fully redirects to the CH2 application, update DNS entries or load balancer routing to point to CH2 endpoints.

4.2.6 Decommission CH1 Applications and Mark Upgrade as Complete

Reference: CloudHub to CloudHub 2.0 Migration Completion

• Once CH2 applications are stable (recommend 1–2 weeks observation period), stop CH1 applications.
• Delete CH1 app deployments.
• After all apps are migrated, perform a DLB failover.
• Mark Upgrade as Complete

5. Monitoring & Observability

5.1 Anypoint Monitoring

• CH2 supports Anypoint Monitoring with enhanced dashboards.
• Configure custom dashboards for key metrics (CPU, memory, message rates, error rates).
• Set up alerts for threshold breaches.

5.2 Log Management

• CH2 application logs are accessible via Runtime Manager → Logs.
• Configure log forwarding to external SIEM/log aggregation tools (Splunk, ELK, etc.) using the log forwarding connector or Anypoint Monitoring.
• Ensure log retention policies meet compliance requirements.

5.3 Health Checks

• Configure readiness and liveness probes if using custom health check endpoints.
• Use Anypoint Platform's built-in health monitoring for application status.

6. Security Considerations

• Secrets Manager: Use Anypoint Secrets Manager for storing certificates and keystores — fully supported in CH2.
• IP Whitelisting: Update any IP allowlists in downstream/upstream systems with the new CH2 outbound IP ranges.
• Mutual TLS (mTLS): Reconfigure mTLS settings on the Ingress Load Balancer.
• Secure Properties: Re-enter all encrypted properties in the CH2 deployment settings.
• Anypoint Access Management: Review and update environment permissions and roles.

7. Networking Checklist

• Private Space created with correct CIDR range
• VPN or Transit Gateway reconnected to Private Space
• Firewall rules migrated and validated
• Ingress Load Balancer configured
• SSL certificates applied to load balancer
• DNS entries updated
• Outbound IPs communicated to downstream systems
• On-premises connectivity tested end-to-end

8. Application Migration Checklist

• All CH1 apps inventoried and documented
• Mule runtime versions validated (4.4+)
• Application properties and secure properties catalogued
• Applications rebuilt and tested locally
• CH2 deployment configured per application
• Smoke tests passed in each environment (Dev → UAT → Prod)
• Monitoring and alerts configured
• Log forwarding verified
• Rollback plan documented per application
• Stakeholders notified of cutover schedule

9. Common Issues & Troubleshooting

10. Rollback Strategy

• Maintain CH1 deployments in a stopped (not deleted) state during the cutover validation period.
• Keep DNS TTLs low (60–300 seconds) before cutover to enable fast rollback.
• To rollback:
  • Restart the CH1 application and switchover traffic back to the CH1 application.
  • Revert DNS entries to CH1 load balancer endpoint.
  • Notify stakeholders.
• Define a clear go/no-go criteria before each environment cutover.