W-18195573-CHtoCH2-App-Migration

cloudhub/modules/ROOT/nav.adoc

@@ -13,6 +13,7 @@
  ** xref:penetration-testing-policies.adoc[Run Vulnerability Assessment and Penetration Tests]
  * xref:cloudhub-release-notes.adoc[Release Notes]
  * xref:vpc-upgrade.adoc[]
+ * xref:app-migration.adoc[]
  * xref:cloudhub-use.adoc[Using CloudHub]
  ** xref:developing-applications-for-cloudhub.adoc[Develop Applications for CloudHub]
  ** xref:deploying-to-cloudhub.adoc[Deploy to CloudHub]

cloudhub/modules/ROOT/pages/app-migration.adoc

@@ -0,0 +1,195 @@
+= CloudHub to CloudHub 2.0 Application Migration
+
+After your Anypoint VPC upgrade is complete, you can migrate all associated applications. Migration involves creating an equivalent CloudHub 2.0 application for every CloudHub application, and linking them to create weighted DNS records for both the CloudHub and the CloudHub 2.0 URLs. 
+
+
+The current CloudHub application continues to run without any disruption until the upgrade is complete. After the upgrade is complete, you can continue to use the same CloudHub URL for your new CloudHub 2.0 application.
+
+Some configuration settings of the CloudHub application aren't automatically mapped to the new CloudHub 2.0 application. Go to your new CloudHub 2.0 application settings to finish the configuration.
+
+[NOTE]
+During the application upgrade process, no out-of-the-box entitlements are provided. Work with your account representative to remain compliant with entitlements and finish the upgrade on time.
+
+== Upgrade Your CloudHub Application to CloudHub 2.0 via Anypoint Platform
+
+. From *Anypoint Platform*, select *Runtime Manager* > *Applications*.
+. Select the CloudHub application to upgrade and go to *Settings*. 
++
+If your application is eligible for the upgrade, the upgrade tooling is available on the *Settings* page.
+. Click *Upgrade to CloudHub 2.0*, then click *Start Upgrade*.
++
+image::upgrade-application-window.png[CloudHub to CloudHub 2.0 application upgrade window]
++
+The *Upgrade Application to CloudHub 2.0* page opens.
++
+* *Application Name* field shows the inherited CloudHub application name by default.
++
+To use a different name for your CloudHub 2.0 application, change it by editing the field.
+* *Upgrading From* field shows the name of the CloudHub application the new application is being upgraded from.
++
+You can’t edit this field.
+* *Deployment Target* field shows the preselected private space for the application deployment based on the upgraded CloudHub VPC.
++
+You can’t edit this field.
+. For the *Application File*, you can either:
+.. Upload your application file: Download the application asset from the link under *Application File*, make the necessary changes, and upload it to deploy your new application to the CloudHub 2.0 private space.
+.. Import file from Exchange: Import the CloudHub application you want to upgrade.
+. In the *Ingress* tab, specify the *Endpoint* configuration:
+.. Select a *Host* from the dropdown list.
++
+[NOTE]
+If you're using `anypoint.dns.net` without a TLS context, the *Ingress* tab doesn’t show it as a possible endpoint.
++
+.. Select a specific subdomain from the dropdown list.
+.. Add a specific path.
+.. Optionally, provide a specific path rewrite.
+.. Select whether you want to provide internal or external access to your endpoint.
+. Follow the steps to xref:cloudhub-2::ch2-deploy.adoc[deploy an application to CloudHub 2.0].
+
+[WARNING]
+====
+If you use a different name for the CloudHub 2.0 application, make sure you put the CloudHub application name in the *Ingress* tab settings in the subdomain field of the endpoint configuration. If you configure URLs incorrectly, traffic doesn't reach the CloudHub 2.0 application during xref:app-migration.adoc#next-steps-after-application-upgrade[traffic switching].
+
+In applications with inbound traffic, the Shared Load Balancer (SLB) handles traffic switching if your Ingress configuration includes the default CloudHub application endpoint in the format: `<app_name>.<region>.cloudhub.io`. However, if that default endpoint is missing and you have configured a vanity domain or an `anypointdns.net endpoint` instead, the Dedicated Load Balancer (DLB) switches the traffic. For more information about SLB and DLB traffic switching, see xref:app-migration.adoc#understanding-the-traffic-source[Understanding the Traffic Source].
+====
+
+[NOTE]
+The *Host* dropdown list shows only the domains added under the certificates of the underlying VPC Dedicated Load Balancer configuration before the application upgrade started. If you add a new certificate to the original VPC Dedicated Load Balancer after the application upgrade has started, you need to manually add it under the *Domain & TLS* tab of your newly created private space for that domain to appear on the *Host* dropdown list.
+
+== Next Steps After Application Upgrade
+
+After the CloudHub 2.0 application is deployed, you can test the app by directing traffic to it and verifying network connectivity and the app behavior. 
+
+To avoid updating your client applications that connect to CloudHub, retain the domains from CloudHub on CloudHub 2.0. To link your applications, apply either of these options:
+
+Customer-managed:: Switch the application’s xref:cloudhub-2::ch2-config-endpoints-paths.adoc[DNS] to point to CloudHub 2.0.
+
+MuleSoft-managed:: Carry over vanity URLs while incrementally switching percentage of traffic from CloudHub to CloudHub 2.0.
+
+[IMPORTANT]
+Restart your Dedicated Load Balancer before initiating the traffic switching.
+
+To gradually switch traffic from CloudHub to CloudHub 2.0:
+
+. In *Runtime Manager*, go to *Finish Upgrade*.
+. Select the percentage of traffic to direct from CloudHub to CloudHub 2.0, and click *Save changes*.
++
+image::traffic-switching.png[CloudHub to CloudHub 2.0 app traffic switching window.]
+
+[NOTE]
+You can roll back to CloudHub if there are failures during this stage.
+
+=== Understanding the Traffic Source
+
+The traffic source determines which type of DNS record is updated to manage the traffic flow between your CloudHub and CloudHub 2.0 applications during the migration process. Understanding this concept helps you anticipate how ‌‌traffic is managed based on your application's existing and new endpoint configurations.
+
+CloudHub can theoretically receive traffic from two main sources:
+
+* Shared Load Balancer (SLB): This source is typically associated with the default endpoints of your CloudHub application, often listening on ports `8081/8082`.
+* Dedicated Load Balancer (DLB): This source is usually associated with vanity domains configured for your CloudHub application, often listening on ports `8091/8092`.
+
+CloudHub 2.0 applications listen on a single port: `8081`. 
+
+During traffic switching, CloudHub needs to know the traffic source to correctly modify the DNS records. This is because applications using SLB have a different DNS record structure than those using DLB.
+
+To facilitate the gradual migration of traffic from CloudHub to CloudHub 2.0, the system creates weighted DNS records. These records direct a certain percentage of traffic to your CloudHub application and the remaining percentage to your linked CloudHub 2.0 application. The specific DNS record that needs to be weighted depends on whether the traffic to your CloudHub application originates from the SLB or the DLB.
+
+The system infers the traffic source based on the endpoints configured for your application. The rules for inference are:
+
+* If your application has a CloudHub default endpoint, the SLB DNS record is used for traffic switching. CloudHub default domains follow patterns like `$region.$env.cloudhub.io` or `*.ca-c1.stgx.cloudhub.io/`.
+* If your application has any other endpoints, such as vanity domains or mule-worker endpoints, the DLB DNS record is used for traffic switching. 
+* Vanity domains are any domains other than the default CloudHub or CloudHub 2.0 domains.
++
+Make sure that the vanity domain on CloudHub 2.0 matches the one on the CloudHub application, or avoid setting a traffic switch percentage to prevent dropped traffic.
+* If your application has both default domains and vanity domains configured, default domains take precedence over vanity domains.
+
+If you change your application's endpoint configuration, the inferred traffic source can also change. For example, if you initially had only vanity domains (DLB) and then add a CloudHub default endpoint, the traffic source is inferred as SLB.
+
+
+==== HTTP and HTTPS Requests
+
+When sending traffic via SLB in CloudHub applications, you can target either HTTP or HTTPS. This impacts on whether the SLB uses port 8081 or 8082 to forward requests to your application: 
+
+* If you target HTTP, the SLB receives traffic on HTTP and forwards it to port 8081. The app then receives on port 8081.
+* If you target HTTPS, the SLB receives traffic on HTTPS and forwards it to port 8082. The app then receives on port 8082.
+
+CloudHub 2.0 private spaces are configured by default to redirect traffic to HTTPS. If you use a mix of HTTP and HTTPS applications in CloudHub SLB and want to migrate this configuration, use either of these workarounds:
+
+* Enable the *Accept HTTP* option within the *Advanced* tab of the private space settings. This allows CloudHub 2.0 to accept HTTP traffic. 
++
+image::accept-http.png[Option to accept HTTP traffic.]
++
+[WARNING]
+This option applies to all client-to-private-space traffic. If you enable it, all the applications in that private space become open to accepting HTTP traffic.
++
+* Update your CloudHub HTTP applications to become HTTPS. In this case, you can leave the “redirect to HTTPS” option on the private space settings. 
++
+[NOTE]
+This workaround can take more work and time depending on the number of HTTP CloudHub applications you have.
+
+
+[WARNING]
+The CloudHub DLB routes requests from clients to Mule apps deployed within the VPC. The DLB sends requests to a Mule application. It uses the HTTP Host header to find the certificate endpoint that matches the request. Then, it uses the URL mapping rules for that endpoint to send the request to the Mule application. If the request doesn't match any certificate configured on the DLB, the DLB uses the "default" certificate endpoint to match the request against its URL mapping rules. During traffic switching, CloudHub 2.0 doesn't contain mapping rules for this unmatched host within the default certificate.
+
+
+=== Managing API Policies During Traffic Switching
+
+When API policies are applied to your new application, they begin with a clean internal status.
+
+==== Policies Unchanged by the App Migration
+
+These policies don't rely on internal status and their behavior remains consistent:
+
+* http-basic-authentication
+* cors
+* client id enforcement
+* Header injection
+* Header removal
+* ip-allowlist
+* ip-blocklist
+* ldap-authentication
+* message-logging
+* json-threat-protection
+* xml-threat-protection
+
+==== Policies Affected by Internal Status (Caching)
+
+These policies rely on internal status to cache data: 
+
+* external-oauth2-access-token-enforcement
+* openam-access-token-enforcement
+* openidconnect-access-token-enforcement
+* pingfederate-access-token-enforcement
+* mule-http-caching-policy
+* jwt-validation
+
+When transitioning to the new application, these policies can either trigger additional requests to the origin servers or have different cached values depending on which application receives the requests.
+
+==== Policies Affected by Internal Status (Request Counting)
+
+These policies track the number of processed requests and can sometimes exhibit unexpected behavior during the transition to the new application: 
+
+* rate-limiting
+* rate-limiting-sla-based
+* spike-control
+
+If there's a hard change on traffic from one application to the other, policy counters behave as if they were reset. In a balanced round-robin traffic distribution, the effective number of requests can sometimes double as each application maintains an independent counting mechanism.
+
+
+During the CloudHub to CloudHub 2.0 application migration, traffic gradually shifts, and both applications are active simultaneously. If your API Manager policies are closely integrated with your original CloudHub application, these configurations can’t be easily shared or migrated in real time. To maintain consistent policy enforcement, configure equivalent policies on your CloudHub 2.0 application's API instance during traffic switching.
+
+Auto-discovery connects a deployed Mule application with an API defined in API Manager. Throughout the migration, both your CloudHub and CloudHub 2.0 applications are linked to the same API.
+
+
+== Complete the Application Upgrade
+
+After traffic is fully redirected to the CloudHub 2.0 application, you have 30 days to stop your CloudHub application and mark the upgrade as complete. If you don't stop it within this period, the platform automatically stops the application for you.
+
+If you change your CloudHub application after it stops, the changes aren't replicated in your new CloudHub 2.0 application.  Make any changes to the CloudHub 2.0 application settings. 
+
+After your CloudHub application is stopped, you have 30 days to delete it. If you don't delete it within this period, the platform automatically deletes the application for you.
+
+== See Also
+
+* xref:vpc-upgrade.adoc[]
+* xref:cloudhub-2::ch2-deploy-private-space.adoc[]