Merge pull request #313297 from craigshoemaker/aca/deep/migration

[Container Apps] New: Migration guides

Author: denrea

articles/container-apps/TOC.yml

@@ -250,12 +250,20 @@ items:
               href: troubleshoot-target-port-settings.md
             - name: Container start
               href: troubleshoot-container-start-failures.md
-    - name: Migration
+    - name: Migrate to Azure Container Apps
       items:
         - name: Heroku migration overview
           href: migrate-heroku-overview.md
         - name: Migrate from Heroku
           href: migrate-heroku.md
+        - name: Migrate Spring Boot applications 
+          href: migrate-spring-boot.md
+        - name: Migrate Spring Cloud applications 
+          href: migrate-spring-cloud.md
+        - name: Migrate Tomcat applications
+          href: migrate-tomcat.md
+        - name: Migrate Java with GitHub Copilot app modernization
+          href: migrate-java-github-copilot-app-modernization.md
     - name: Azure Developer CLI (azd) templates
       href: container-apps-cli-templates.md
 - name: Observability

articles/container-apps/includes/migrate-java-post-migration-operations.md

@@ -0,0 +1,15 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+- **CI/CD pipelines**: Add a deployment pipeline for automatic, consistent deployments. Instructions are available for [Azure Pipelines](../azure-pipelines.md) and [GitHub Actions](../github-actions.md).
+- **Blue-green deployment**: Use container app revisions, revision labels, and ingress traffic weights to test code changes in production before making them available to end users. For more information, see [Blue-Green Deployment in Azure Container Apps](../blue-green-deployment.md).
+- **Service bindings**: Add service bindings to connect your application to supported Azure databases. Service bindings eliminate the need to provide connection information, including credentials, to your Spring Boot applications.
+- **JVM metrics**: Enable the Java development stack to collect JVM core metrics. For more information, see [Java metrics for Java apps in Azure Container Apps](../java-metrics.md).
+- **Alerts**: Add Azure Monitor alert rules and action groups to quickly detect and address aberrant conditions. For more information, see [Set up alerts in Azure Container Apps](../alerts.md).
+- **Zone redundancy**: Replicate your app across availability zones by enabling zone redundancy. Traffic is load balanced and automatically routed to replicas if a zone outage occurs. For more information, see [Reliability in Azure Container Apps](/azure/reliability/reliability-azure-container-apps).
+- **Web Application Firewall**: Protect your container app from common exploits and vulnerabilities by using Web Application Firewall on Application Gateway. For more information, see [Protect Azure Container Apps with Web Application Firewall on Application Gateway](../waf-app-gateway.md).

articles/container-apps/includes/migrate-java-post-migration-spring-components.md

@@ -0,0 +1,43 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+#### Service discovery and load balancing
+
+Enable your application to work with the Spring Cloud Registry component so other deployed Spring applications and clients can dynamically discover it. For more information, see [Configure settings for the Eureka Server for Spring component in Azure Container Apps](../java-eureka-server.md).
+
+Then, modify any application clients to use the Spring Client Load Balancer. When you use the Spring Client Load Balancer, the client gets addresses for all running instances of the application and finds one that works if another becomes corrupted or unresponsive. For more information, see [Spring Tips: Spring Cloud Load Balancer](https://spring.io/blog/2020/03/25/spring-tips-spring-cloud-loadbalancer) in the Spring Blog.
+
+#### API gateway
+
+Consider adding a [Spring Cloud Gateway](https://cloud.spring.io/spring-cloud-gateway/reference/html/) instance. Spring Cloud Gateway provides a single endpoint for all applications deployed in your Azure Container Apps environment. If you already deployed a Spring Cloud Gateway, ensure that you configured a routing rule to route traffic to your newly deployed application.
+
+#### Centralized configuration
+
+Consider adding a Spring Cloud Config Server to centrally manage and version-control configuration for all your Spring Cloud applications. First, create a Git repository to house the configuration and configure the app instance to use it. For more information, see [Configure settings for the Config Server for Spring component in Azure Container Apps](../java-config-server.md).
+
+Migrate your configuration by using the following steps:
+
+1. Inside the application's *src/main/resources* directory, create a *bootstrap.yml* file with the following contents:
+
+    ```yml
+    spring:
+      application:
+        name: <your-application-name>
+    ```
+
+1. In the configuration Git repository, create a *\<your-application-name\>.yml* file, where `your-application-name` is the same as in the preceding step. Move the settings from the *application.yml* file in *src/main/resources* to the new file you created. If the settings were previously in a *.properties* file, convert them to YAML first. You can find online tools or IntelliJ plugins to accomplish this conversion.
+
+1. Create an *application.yml* file in the directory you created. Use this file to define settings and resources shared among all applications in the Azure Container Apps environment, such as data sources, logging settings, and Spring Boot Actuator configuration.
+
+1. Commit and push these changes to the Git repository.
+
+1. Remove the *application.properties* or *application.yml* file from the application.
+
+#### Administration
+
+Consider adding the Admin for Spring managed component to enable an administrative interface for Spring Boot web applications that expose actuator endpoints. For more information, see [Configure the Spring Boot Admin component in Azure Container Apps](../java-admin.md).

articles/container-apps/includes/migrate-java-pre-migration-caches.md

@@ -0,0 +1,11 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+Identify any external caches in use. Frequently, you use Redis via Spring Data Redis. For configuration information, see the [Spring Data Redis](https://spring.io/projects/spring-data-redis) documentation.
+
+Determine whether you cache session data via [Spring Session](https://spring.io/projects/spring-session) by searching for the respective configuration (in [Java](https://docs.spring.io/spring-session/reference/3.0/index.html) or [XML](https://docs.spring.io/spring-session/reference/3.0/index.html)).

articles/container-apps/includes/migrate-java-pre-migration-certificates.md

@@ -0,0 +1,13 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+Document all the certificates used for public SSL endpoints or communication with backend databases and other systems. You can view all certificates on the production servers by running the following command:
+
+```bash
+keytool -list -v -keystore <path to keystore>
+```

articles/container-apps/includes/migrate-java-pre-migration-databases.md

@@ -0,0 +1,31 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+For a Spring Boot application, connection strings typically appear in configuration files when it depends on an external database. Here's an example from an *application.properties* file:
+
+```properties
+spring.datasource.url=jdbc:mysql://localhost:3306/mysql_db
+spring.datasource.username=dbuser
+spring.datasource.driver-class-name=com.mysql.jdbc.Driver
+```
+
+Here's an example from an *application.yaml* file:
+
+```yaml
+spring:
+  data:
+    mongodb:
+      uri: mongodb://mongouser:[email protected]:27017
+```
+
+See Spring Data documentation for more possible configuration scenarios:
+
+- [JPA Repositories](https://docs.spring.io/spring-data/jpa/docs/current/reference/html/#jpa.repositories)
+- [JDBC Repositories](https://docs.spring.io/spring-data/jdbc/docs/current/reference/html/#jdbc.repositories)
+- [Cassandra Repositories](https://docs.spring.io/spring-data/cassandra/docs/current/reference/html/#cassandra.repositories)
+- [MongoDB Repositories](https://docs.spring.io/spring-data/mongodb/docs/current/reference/html/#mongodb.repositories)

articles/container-apps/includes/migrate-java-pre-migration-file-system.md

@@ -0,0 +1,15 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+Identify any instances where your services read from or write to the local file system. Note which files are short-term or temporary and which files are long-lived.
+
+Azure Container Apps offers several types of storage. By using ephemeral storage, you can read and write temporary data within a running container or replica. By using Azure Files, you can provide permanent storage that multiple containers can share. For more information, see [Use storage mounts in Azure Container Apps](../storage-mounts.md).
+
+If your application serves **read-only static content**, consider moving it to Azure Blob Storage and adding Azure CDN for global distribution. For more information, see [Static website hosting in Azure Storage](/azure/storage/blobs/storage-blob-static-website) and [Quickstart: Integrate an Azure storage account with Azure CDN](/azure/cdn/cdn-create-a-storage-account-with-cdn).
+
+If your application handles **dynamically published static content** (uploaded or generated content that doesn't change after creation), you can integrate Azure Blob Storage and Azure CDN. You can also use an Azure Function to manage uploads and trigger CDN refreshes. For a sample implementation, see [Uploading and CDN-preloading static content with Azure Functions](https://github.com/Azure-Samples/functions-java-push-static-contents-to-cdn).

articles/container-apps/includes/migrate-java-pre-migration-jms.md

@@ -0,0 +1,57 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+Identify the brokers in use by looking in the build manifest (typically, a *pom.xml* or *build.gradle* file) for the relevant dependencies.
+
+For example, a Spring Boot application that uses ActiveMQ typically contains this dependency in its *pom.xml* file:
+
+```xml
+<dependency>
+    <groupId>org.springframework.boot</groupId>
+    <artifactId>spring-boot-starter-activemq</artifactId>
+</dependency>
+```
+
+Spring Boot applications that use commercial brokers typically contain dependencies directly on the brokers' JMS driver libraries. Here's an example from a *build.gradle* file:
+
+```json
+    dependencies {
+      ...
+      compile("com.ibm.mq:com.ibm.mq.allclient:9.4.0.5")
+      ...
+    }
+```
+
+After you identify the brokers in use, find the corresponding settings. You typically find them in the *application.properties* and *application.yml* files in the application directory.
+
+> [!NOTE]
+> Microsoft recommends using the most secure authentication flow available. The authentication flow described in this procedure, such as for databases, caches, messaging, or AI services, requires a high degree of trust in the application and carries risks not present in other flows. Use this flow only when more secure options, like managed identities for passwordless or keyless connections, aren't viable. For local machine operations, prefer user identities for passwordless or keyless connections.
+
+Here's an ActiveMQ example from an *application.properties* file:
+
+```properties
+spring.activemq.brokerurl=broker:(tcp://localhost:61616,network:static:tcp://remotehost:61616)?persistent=false&useJmx=true
+spring.activemq.user=admin
+spring.activemq.password=<password>
+```
+
+For more information on ActiveMQ configuration, see the [Spring Boot messaging documentation](https://docs.spring.io/spring-boot/reference/messaging/index.html).
+
+Here's an IBM MQ example from an *application.yaml* file:
+
+```yaml
+ibm:
+  mq:
+    queueManager: qm1
+    channel: dev.ORDERS
+    connName: localhost(14)
+    user: admin
+    password: <password>
+```
+
+For more information on IBM MQ configuration, see the [IBM MQ Spring components documentation](https://github.com/ibm-messaging/mq-jms-spring#ibm-mq-jms-spring-components).

articles/container-apps/includes/migrate-java-pre-migration-os-code.md

@@ -0,0 +1,11 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+<!-- Used by: migrate-spring-boot.md, migrate-spring-cloud-to-azure-container-apps.md, migrate-tomcat.md -->
+
+If your application contains code with dependencies on the host OS, refactor it to remove those dependencies. For example, replace any use of `/` or `\` in file system paths with [`File.Separator`](https://docs.oracle.com/javase/8/docs/api/java/io/File.html#separator) or [`Paths.get`](https://docs.oracle.com/javase/8/docs/api/java/nio/file/Paths.html#get-java.lang.String-java.lang.String...-).

articles/container-apps/includes/migrate-java-pre-migration-platform.md

@@ -0,0 +1,24 @@
+---
+author: deepganguly
+ms.author: deepganguly
+ms.service: azure-container-apps
+ms.topic: include
+ms.date: 03/11/2026
+---
+
+<!-- Used by: migrate-spring-boot.md, migrate-spring-cloud-to-azure-container-apps.md -->
+
+If you create your Dockerfile manually and deploy a containerized application to Azure Container Apps, you have full control over your deployment, including JRE/JDK versions.
+
+For deployment from artifacts, Azure Container Apps offers specific versions of Java (8, 11, 17, and 21) and specific versions of Spring Boot and Spring Cloud components. To ensure compatibility, first migrate your application to a supported version of Java in its current environment, then proceed with the remaining migration steps. Fully test the resulting configuration with the latest stable release of your Linux distribution.
+
+> [!NOTE]
+> This validation is especially important if your current server runs on an unsupported JDK, such as Oracle JDK or IBM OpenJ9.
+
+To check your current Java version, sign in to your production server and run the following command:
+
+```bash
+java -version
+```
+
+For supported versions of Java, Spring Boot, and Spring Cloud, see [Java on Azure Container Apps overview](../java-overview.md).