Train the trainers initial session feedback integration (#175)

rotycenh · web-flow · commit 312e261b177f · 2025-02-27T13:11:52.000+08:00
## Purpose  Integration changes to docs contents as a result of feedback from our initial Train the Trainers session on Feb 20. ## Does this introduce a breaking change?  ``` [ ] Yes [ x] No ``` ## Pull Request Type What kind of change does this Pull Request introduce?  ``` [ ] Bugfix [ ] Feature [ ] Code style update (formatting, local variables) [ ] Refactoring (no functional changes, no api changes) [ x] Documentation content changes [ ] Other... Please describe: ``` ## How to Test Preview site available here: https://ronline-java-aca-preview.azurewebsites.net/
diff --git a/cleanup.md b/cleanup.md
@@ -11,7 +11,7 @@ If you're finished with the resources that you created for these labs, clean up
 
 1. Clean up the Azure OpenAI Service instance (optional). 
 
-   If you completed the optional [Lab 5]({% link docs/05_lab_openai/05_openlab_openai_aca.md %}), you created a new Azure OpenAI instance. Use the following command to delete it before you delete any other resources. If you didn't complete Lab 5, you can ignore this step.
+   If you completed the optional [Lab 3]({% link docs/03_lab_openai/03_openlab_openai_aca.md %}), you created a new Azure OpenAI instance. Use the following command to delete it before you delete any other resources. If you didn't complete Lab 3, you can ignore this step.
 
      ```bash
      az cognitiveservices account delete -g $RESOURCE_GROUP -n $OPEN_AI_SERVICE_NAME
diff --git a/docs/01_lab_plan/0101.md b/docs/01_lab_plan/0101.md
@@ -15,8 +15,12 @@ To start, you’ll learn about the Spring Petclinic workload.
 
 1.  On your lab computer, open a web browser, go to [GitHub](https://github.com), and sign in to your GitHub account. If you don’t have a GitHub account, create one (go to [Join GitHub](https://github.com/join), and follow the instructions at [Signing up for a new GitHub account](https://docs.github.com/en/get-started/signing-up-for-github/signing-up-for-a-new-github-account)).
 1.  Go to the [source folder of this lab’s GitHub repo](https://github.com/Azure-Samples/java-on-aca/tree/main/src), and review the **README.md file**.
-1.  Learn how to run the application in dev environments. Pay particular attention to the readme sections that cover [starting services locally without Docker](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-without-docker), [starting services locally with docker-compose](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-with-docker-compose), and [starting services locally with docker-compose and Java](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-with-docker-compose-and-java). After you’ve configured your development environment, if time permits, consider launching the application locally using one of these methods.
-1.  In the source folder of this lab’s GitHub repo, go to each folder that contains the code of the individual spring-petclinic-\* services and review the content.
+1.  Review the instructions for manually running the application in your dev environment. Pay particular attention to the readme sections that cover [starting services locally without Docker](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-without-docker), [starting services locally with docker-compose](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-with-docker-compose), and [starting services locally with docker-compose and Java](https://github.com/Azure-Samples/java-on-aca/tree/main/src#starting-services-locally-with-docker-compose-and-java). 
+
+    {: .note }
+    At this point, you **do not** need to run the app in your dev environment using these methods. Simply reviewing and understanding how you can use these instructions is sufficient for now. However, if you've got extra time after completing the rest of this lab, feel free to try launching the application and exploring its functionality locally.
+
+1.  In the source folder of this lab’s GitHub repo, go to each folder that contains the code of the individual spring-petclinic-\* services and spend a few minutes reviewing the contents, familiarizing yourself with the overall code structure.
 
 ![microservices overview](../../images/services.png)
 
diff --git a/docs/02_lab_launch/0201.md b/docs/02_lab_launch/0201.md
@@ -11,7 +11,10 @@ First, you’ll need to sign your lab environment in to Azure and configure it t
 
 ## Step-by-step guidance
 
-1.  In your lab environment, open a command-line environment (Windows Subsystem for Linux, Git Bash, PowerShell, or VS Code terminal) and sign in to your Azure subscription with the following command:
+{: .note }
+We'll be using Bash commands to complete this lab. You can use any compatible command-line environment, such as the Windows Subsystem for Linux, Git Bash, or the Visual Studio Code Bash terminal. To avoid potential errors, **do not** run these commands in a PowerShell session.
+
+1.  In your lab environment, open a command-line environment and sign in to your Azure subscription with the following command:
 
     ```bash
     az login
diff --git a/docs/02_lab_launch/0203.md b/docs/02_lab_launch/0203.md
@@ -22,7 +22,7 @@ By default, the MySQL database you create will have a firewall enabled that will
     > The server name must be globally unique, so if the randomly generated name is already in use, adjust it accordingly . Keep in mind that the name can contain only lowercase letters, numbers, and hyphens.
 
     {: .note }
-    > For simplicity’s sake, in this lab, we’re using a MySQL admin password to allow apps to connect to MySQL Server. However, we don’t recommend this when operating in a production environment. For the secured managed identity solution, refer to [Lab 04: Connect to a database securely using managed identity]({% link docs/04_lab_secrets/04_openlab_secrets_aca.md %}).
+    > For simplicity’s sake, in this lab, we’re using a MySQL admin password to allow apps to connect to MySQL Server. However, we don’t recommend this when operating in a production environment. For the secured managed identity solution, refer to [Lab 5: Connect to a database securely using managed identity]({% link docs/05_lab_secrets/05_openlab_secrets_aca.md %}).
 
     ```bash
     MYSQL_SERVER_NAME=mysql-$APPNAME-$UNIQUEID
diff --git a/docs/03_lab_openai/0301.md b/docs/03_lab_openai/0301.md
@@ -1,11 +1,11 @@
 ---
-title: '1. Create an Azure OpenAI account (optional)'
+title: '1. Create an Azure OpenAI account (Optional)'
 layout: default
 nav_order: 1
-parent: 'Lab 5: Integrate Azure OpenAI Service with your apps'
+parent: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 ---
 
-# Create an Azure OpenAI account (optional)
+# Create an Azure OpenAI account (Optional)
 
 Before you can add AI capabilities to your application, you need to create an Azure OpenAI account and deploy the language models that you want to use.
 
diff --git a/docs/03_lab_openai/0302.md b/docs/03_lab_openai/0302.md
@@ -4,7 +4,7 @@ layout: default
 nav_order: 2
 nav_exclude: true
 search_exclude: true
-parent: 'Lab 5: Integrate with Azure OpenAI'
+parent: 'Lab 3: Integrate with Azure OpenAI'
 ---
 
 Deploy the sample ai servcie `chat-agent`, and explore the power of Azure Open AI service.
diff --git a/docs/03_lab_openai/0303.md b/docs/03_lab_openai/0303.md
@@ -1,11 +1,11 @@
 ---
-title: '3. Improve the chat service experience (optional)'
+title: '3. Improve the chat service experience (Optional)'
 layout: default
 nav_order: 6
-parent: 'Lab 5: Integrate Azure OpenAI Service with your apps'
+parent: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 ---
 
-# Improve the chat service experience (optional)
+# Improve the chat service experience (Optional)
 
 You’ve completed this lab’s step-by-step instructions and built a chatbot that integrates with the Sprint Petclinic application. The following optional sections can extend the chat service’s capabilities and improve how users interact with it.
 
diff --git a/docs/03_lab_openai/0304.md b/docs/03_lab_openai/0304.md
@@ -2,7 +2,7 @@
 title: '4. Review'
 layout: default
 nav_order: 7
-parent: 'Lab 5: Integrate Azure OpenAI Service with your apps'
+parent: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 ---
 
 # Review
@@ -11,4 +11,4 @@ In this lab, you learned how to build a Spring application-based chat service po
 
 The following diagram should reflect the current state of the deployed application.
 
-![lab 5 overview](../../images/acalab5.png)
+![lab 3 overview](../../images/acalab-openai.png)
diff --git a/docs/03_lab_openai/03_openai.md b/docs/03_lab_openai/03_openai.md
@@ -2,7 +2,7 @@
 title: '2. Create AI application from scratch'
 layout: default
 nav_order: 3
-parent: 'Lab 5: Integrate Azure OpenAI Service with your apps'
+parent: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 ---
 
 # Create an AI application from scratch for the Petclinic workload
@@ -15,7 +15,7 @@ You’ll start by creating a new Spring Boot service application that connects w
 
 -   A GitHub Copilot subscription. (If you don’t already have a subscription, try [GitHub Copilot Free](https://docs.github.com/en/copilot/quickstart#sign-up-for-github-copilot).)
 -   The [GitHub Copilot Chat extension](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot-chat) installed in your copy of Visual Studio Code.
--   A prepared Azure OpenAI instance with the `gpt-4o` model deployed. For more details, refer to the instructions [in previous section of this lab]({% link docs/05_lab_openai/0501.md %}).
+-   A prepared Azure OpenAI instance with the `gpt-4o` model deployed. For more details, refer to the instructions [in previous section of this lab]({% link docs/03_lab_openai/0301.md %}).
 -   The `endpoint` and `api-key` values for your Azure OpenAI instance. You can find these by going to your Azure OpenAI instance in the Azure portal and looking in the `Resource Management` \> `Keys and Endpoint` section.
 
 ## Step by step guidance
diff --git a/docs/03_lab_openai/03_openai_existing.md b/docs/03_lab_openai/03_openai_existing.md
@@ -1,10 +1,10 @@
 ---
 title: 'Integrate AI to existing project'
 layout: default
-nav_order: 4
+nav_order: 5
 nav_exclude: true
 search_exclude: true
-parent: 'Lab 5: Integrate with Azure OpenAI'
+parent: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 ---
 
 # Integrate AI into your existing project
diff --git a/docs/03_lab_openai/03_openlab_openai_aca.md b/docs/03_lab_openai/03_openlab_openai_aca.md
@@ -1,11 +1,11 @@
 ---
-title: 'Lab 5: Integrate Azure OpenAI Service with your apps'
+title: 'Lab 3: Integrate Azure OpenAI Service with your apps'
 layout: default
 nav_order: 7
 has_children: true
 ---
 
-# Lab 5: Integrate Azure OpenAI Service with your applications
+# Lab 03: Integrate Azure OpenAI Service with your applications
 
 ## Introduction
 
@@ -22,7 +22,7 @@ As you work through this lab, you’ll learn how to:
 
 The following image illustrates how your application’s architecture should look after you’ve completed this lab.
 
-![lab 5 overview](../../images/acalab5.png)
+![lab 3 overview](../../images/acalab-openai.png)
 
 ## Duration
 
diff --git a/docs/04_lab_monitor/0401.md b/docs/04_lab_monitor/0401.md
@@ -2,7 +2,7 @@
 title: '1. Inspect in the Azure portal'
 layout: default
 nav_order: 1
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Inspect your Azure Container Apps environment in the Azure portal
diff --git a/docs/04_lab_monitor/0402.md b/docs/04_lab_monitor/0402.md
@@ -2,7 +2,7 @@
 title: '2. Enable Log Analytics'
 layout: default
 nav_order: 2
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Enable Log Analytics on your Azure Container Apps environment
diff --git a/docs/04_lab_monitor/0403.md b/docs/04_lab_monitor/0403.md
@@ -2,7 +2,7 @@
 title: '3. Configure Application Insights (Optional)'
 layout: default
 nav_order: 3
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Configure Application Insights to receive monitoring information from your applications
diff --git a/docs/04_lab_monitor/0404.md b/docs/04_lab_monitor/0404.md
@@ -2,7 +2,7 @@
 title: '4. Analyze monitoring data (Optional)'
 layout: default
 nav_order: 4
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Analyze application-specific monitoring data
diff --git a/docs/04_lab_monitor/0405.md b/docs/04_lab_monitor/0405.md
@@ -2,7 +2,7 @@
 title: '5. Azure Managed Grafana (Optional)'
 layout: default
 nav_order: 5
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Build a Java metrics dashboard with Azure Managed Grafana
@@ -55,30 +55,30 @@ If you’d like to learn more about how Azure Managed Grafana helps visualize ex
     1. Choose the default built-in `Azure Monitor` as the data source.
     1. Select `Import`.
 
-        ![Import Java Metrics dashboard](../../images/acalab3-05-grafana-import-dashboard.png)
+        ![Import Java Metrics dashboard](../../images/acalab-monitoring-05-grafana-import-dashboard.png)
 
 1.  View the Java metrics dashboard with Grafana. Now you can explore all the supported Container Apps Java metrics. Just select your Container Apps resource from the Resource filter.
 
     The dashboard provides the following live metric data:
 
     - Container App Overview
 
-      ![Container App Overview](../../images/acalab3-05-grafana-overview.png)
+      ![Container App Overview](../../images/acalab-monitoring-05-grafana-overview.png)
 
     - JVM Memory Usage
 
-      ![JVM Memory Usage](../../images/acalab3-05-grafana-jvm-mem.png)
+      ![JVM Memory Usage](../../images/acalab-monitoring-05-grafana-jvm-mem.png)
 
     - JVM Memory Buffer
 
-      ![JVM Memory Buffer](../../images/acalab3-05-grafana-jvm-buffer.png)
+      ![JVM Memory Buffer](../../images/acalab-monitoring-05-grafana-jvm-buffer.png)
 
     - JVM Garbage Collection
 
-      ![JVM GC](../../images/acalab3-05-grafana-jvm-gc.png)
+      ![JVM GC](../../images/acalab-monitoring-05-grafana-jvm-gc.png)
 
     - JVM Memory Usage Analysis
 
-      ![detailed JVM Memory Usage Analysis](../../images/acalab3-05-grafana-jvm-mem-analysis.png)
+      ![detailed JVM Memory Usage Analysis](../../images/acalab-monitoring-05-grafana-jvm-mem-analysis.png)
 
 You can use this dashboard as a starting point to create your own customized metric visualizations and monitoring solutions.
diff --git a/docs/04_lab_monitor/0406.md b/docs/04_lab_monitor/0406.md
@@ -2,7 +2,7 @@
 title: '6. Review'
 layout: default
 nav_order: 6
-parent: 'Lab 3: Enable monitoring'
+parent: 'Lab 4: Enable monitoring (Optional)'
 ---
 
 # Review
@@ -19,4 +19,4 @@ As part of this process, you:
 
 The following image should now reflect your current application architecture.
 
-![lab 3 overview](../../images/acalab3.png)
+![lab 4 overview](../../images/acalab-monitor.png)
diff --git a/docs/04_lab_monitor/04_openlab_monitoring_aca.md b/docs/04_lab_monitor/04_openlab_monitoring_aca.md
@@ -1,11 +1,11 @@
 ---
-title: 'Lab 3: Enable monitoring'
+title: 'Lab 4: Enable monitoring (Optional)'
 layout: default
-nav_order: 5
+nav_order: 7
 has_children: true
 ---
 
-# Lab 03: Enable monitoring and end-to-end event tracing
+# Lab 04: Enable monitoring and end-to-end event tracing (Optional)
 
 ## Introduction
 
@@ -25,7 +25,7 @@ As you work through this lab, you’ll learn how to:
 
 The following image shows how your application’s architecture should look once you complete this lab.
 
-![lab 3 overview](../../images/acalab3.png)
+![lab 4 overview](../../images/acalab-monitor.png)
 
 ## Duration
 
diff --git a/docs/05_lab_secrets/0501.md b/docs/05_lab_secrets/0501.md
@@ -2,7 +2,7 @@
 title: '1. Create a database admin account'
 layout: default
 nav_order: 1
-parent: 'Lab 4: Connect to a database with managed identity'
+parent: 'Lab 5: Connect to a database with managed identity (Optional)'
 ---
 
 # Create a database administrator account
diff --git a/docs/05_lab_secrets/0502.md b/docs/05_lab_secrets/0502.md
@@ -2,7 +2,7 @@
 title: '2. Update app configuration'
 layout: default
 nav_order: 2
-parent: 'Lab 4: Connect to a database with managed identity'
+parent: 'Lab 5: Connect to a database with managed identity (Optional)'
 ---
 
 # Update application configuration to use passwordless connectivity
diff --git a/docs/05_lab_secrets/0503.md b/docs/05_lab_secrets/0503.md
@@ -2,7 +2,7 @@
 title: '3. Connect Container Apps'
 layout: default
 nav_order: 3
-parent: 'Lab 4: Connect to a database with managed identity'
+parent: 'Lab 5: Connect to a database with managed identity (Optional)'
 ---
 
 # Connect Container Apps to a database by using Azure Service Connector
diff --git a/docs/05_lab_secrets/0504.md b/docs/05_lab_secrets/0504.md
@@ -2,7 +2,7 @@
 title: '4. Review'
 layout: default
 nav_order: 4
-parent: 'Lab 4: Connect to a database with managed identity'
+parent: 'Lab 5: Connect to a database with managed identity (Optional)'
 ---
 
 # Review
@@ -17,4 +17,4 @@ As part of this process, you:
 
 The following diagram should reflect your application’s current architecture.
 
-![lab 4 overview](../../images/acalab4.png)
+![lab 5 overview](../../images/acalab-managed-identity.png)
diff --git a/docs/05_lab_secrets/05_openlab_secrets_aca.md b/docs/05_lab_secrets/05_openlab_secrets_aca.md
@@ -1,11 +1,11 @@
 ---
-title: 'Lab 4: Connect to a database with managed identity'
+title: 'Lab 5: Connect to a database with managed identity (Optional)'
 layout: default
-nav_order: 6
+nav_order: 8
 has_children: true
 ---
 
-# Lab 04: Connect to a database securely by using managed identity
+# Lab 05: Connect to a database securely by using managed identity (Optional)
 
 ## Introduction
 
@@ -25,7 +25,7 @@ As you work through this lab, you’ll learn how to:
 
 The following diagram illustrates how your application’s architecture should look after you’ve completed this lab.
 
-![lab 4 overview](../../images/acalab4.png)
+![lab 5 overview](../../images/acalab-managed-identity.png)
 
 ## Duration
 
diff --git a/docs/06_lab_automation/0601.md b/docs/06_lab_automation/0601.md
@@ -50,9 +50,4 @@ search_exclude: true
       export AAD_USER_ID=<user-object-id>
       ```
 
-   {: .note }
-   > If you run the automation in PowerShell, export environment variables with commands like
-   ```pwsh
-   $env:USER_NAME=<user-name>
-   $env:AAD_USER_ID=<aad-user-id>
-   ```
+
diff --git a/docs/06_lab_automation/06_openlab_automation.md b/docs/06_lab_automation/06_openlab_automation.md
@@ -44,9 +44,10 @@ During this lab, you will:
 - This version of azd templates includes most operations in:
 
   - [Lab 2: Launch a Spring Apps microservices application to Azure Container Apps]({% link docs/02_lab_launch/02_openlab_setup_aca.md %})
-  - [Lab 3: Enable monitoring and end-to-end tracing]({% link docs/03_lab_monitor/03_openlab_monitoring_aca.md %})
-  - [Lab 4: Connect to Database securely using identity]({% link docs/04_lab_secrets/04_openlab_secrets_aca.md %})
-  - [Lab 5: Integrate with Azure OpenAI]({% link docs/05_lab_openai/05_openlab_openai_aca.md %})
+  - [Lab 3: Integrate with Azure OpenAI]({% link docs/03_lab_openai/03_openlab_openai_aca.md %})
+  - [(Optional) Lab 4: Enable monitoring and end-to-end tracing]({% link docs/04_lab_monitor/04_openlab_monitoring_aca.md %})
+  - [(Optional) Lab 5: Connect to Database securely using identity]({% link docs/05_lab_secrets/05_openlab_secrets_aca.md %})
+  
 
 - By default, the automation process will create MySQL server admin password with random string, you can reset the admin password in either way:
 
diff --git a/images/acalab-managed-identity.png b/images/acalab-managed-identity.png
diff --git a/images/acalab-monitor.png b/images/acalab-monitor.png
diff --git a/images/acalab-monitoring-05-grafana-import-dashboard.png b/images/acalab-monitoring-05-grafana-import-dashboard.png
diff --git a/images/acalab-monitoring-05-grafana-jvm-buffer.png b/images/acalab-monitoring-05-grafana-jvm-buffer.png
diff --git a/images/acalab-monitoring-05-grafana-jvm-gc.png b/images/acalab-monitoring-05-grafana-jvm-gc.png
diff --git a/images/acalab-monitoring-05-grafana-jvm-mem-analysis.png b/images/acalab-monitoring-05-grafana-jvm-mem-analysis.png
diff --git a/images/acalab-monitoring-05-grafana-jvm-mem.png b/images/acalab-monitoring-05-grafana-jvm-mem.png
diff --git a/images/acalab-monitoring-05-grafana-overview.png b/images/acalab-monitoring-05-grafana-overview.png
diff --git a/images/acalab-openai.png b/images/acalab-openai.png
