add steps for azd automation (#57)

## Purpose
And fix doc order issue

## Does this introduce a breaking change?
<!-- Mark one with an "x". -->
```
[ ] Yes
[x] No
```

## Pull Request Type
What kind of change does this Pull Request introduce?

<!-- Please check the one that applies to this PR using "x". -->
```
[x] Bugfix
[x] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[x] Documentation content changes
[ ] Other... Please describe:
```

Author: sonwan2020

azure.yaml

@@ -1,7 +1,6 @@
 # yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
 
 name: java-microservices-aca-lab
-resourceGroup: rg-petclinic
 infra:
   provider: bicep
   path: infra/bicep

docs/02_lab_migrate/0203.md

@@ -59,7 +59,7 @@ Your MySQL database will also have a firewall enabled. This firewall will by def
         --rule-name allAzureIPs \
         --name ${MYSQL_SERVER_NAME} \
         --resource-group ${RESOURCE_GROUP} \
-        --start-ip-address 0.0.0.0 --end-ip-address 0.0.0.0
+        --start-ip-address 0.0.0.0 --end-ip-address 255.255.255.255
    ```
 
 1. From the Git Bash window, in the config repository you cloned locally, use your favorite text editor to open the _application.yml_ file. Replace the full contents of the _application.yml_ file with the contents of [this application.yml](0203_application.yml) file. The updated _application.yml_ file includes the following changes:
@@ -70,7 +70,7 @@ Your MySQL database will also have a firewall enabled. This firewall will by def
    * It adds extra `eureka` config on lines 61 to 66.
    * It removes the `chaos-monkey` and `mysql` profiles.
 
-1. In the part you pasted, update the values of the target datasource endpoint on line 12, the corresponding admin user account on line 13, and its password on line 14 to match your configuration. Set these values by using the information in the Azure Database for MySQL Flexible Server connection string you recorded earlier in this task.
+1. In the part you pasted, update the values of the target datasource endpoint on line 6, the corresponding admin user account on line 7, and its password on line 8 to match your configuration. Set these values by using the information in the Azure Database for MySQL Flexible Server connection string you recorded earlier in this task.
 
 1. Save the changes and push the updates you made to the _application.yml_ file to your private GitHub repo by running the following commands from the Git Bash prompt:
 

docs/06_lab_automation/0601.md

@@ -1,63 +1,67 @@
 ---
-title: '1. Prepare the configuration'
+title: '1. Prepare the environment'
 layout: default
 nav_order: 1
-parent: 'Lab 8: Use Azd to deploy the lab solution'
+parent: 'Lab 6: Deploy to Azure automatically'
 ---
 
-# 1. Prepare the configuration
+# 1. Prepare the environment
 
-Fill the configuration file according to your environment.
+Prepare your local environment and plan your Azure resource, get ready for the one-click deployment.
+
+{: .note }
+> This automation guide is tested in linux environment only. Here we use WSL environment to run the automation tool.
 
 ## Step by step guidance
 
-1. If you want to use azd to deploy from a new environment, prepare your images in Azure Container Registry
+1. Install WSL environment
+   Note: you may skip this step if you are using other linux environment.
+   Install WSL to your windows system [How to install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install)
 
-    ```bash
-    APPNAME=petclinic
-    RESOURCE_GROUP=rg-$APPNAME
+1. Install tools
+
+   - Follow this guide to install azd tool to your WSL environment: [Install Azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd?tabs=winget-windows%2Cbrew-mac%2Cscript-linux&pivots=os-linux)
+   - Install az cli: [Install az](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli-linux?pivots=apt#option-1-install-with-one-command)
+   - Install docker: [Docker Desktop WSL 2](https://docs.docker.com/desktop/wsl/)
+
+1. Plan your Azure Container Registry
+
+   An Azure Container Registry is required to save the images for the solution, either create a new Container Registry or use an existing one:
+   - Option 1: Create a new Azure Container Registry
 
-    # prepare ACR
-    MYACR=acr$APPNAME
+    ```bash
+    ACR_RESOURCE_GROUP=<your-resource-group>
+    ACR_NAME=<acr-name>
     az acr create \
-        -n $MYACR \
-        -g $RESOURCE_GROUP \
+        -n $ACR_NAME \
+        -g $ACR_RESOURCE_GROUP \
         --sku Basic \
         --admin-enabled true
+    ```
 
-    ACR_ID=$(az acr show -n $MYACR -g $RESOURCE_GROUP --query id -o tsv)
+    - Option 2: Use existing
+    Collect the values for variable `ACR_RESOURCE_GROUP` and `ACR_NAME`
+    Please add yourself the `Contributor` role in the container registry, we will:
+        1. push images to the acr.
+        1. assign `AcrPull` permission to new user managed identity.
 
-    # create user managed identity
-    ACR_IDENTITY=uid-acr-$APPNAME
+1. Prepare placeholder image to Azure Container Registry
+    In the azd deploy process, we will first create azure resource and container apps, then update the target container apps with the code in the lab solution.
+    In this step, we push a placeholder image for the new container apps.
 
-    az identity create --resource-group $RESOURCE_GROUP --name $ACR_IDENTITY
-    ACR_UMID=$(az identity show --resource-group $RESOURCE_GROUP --name $ACR_IDENTITY --query id --output tsv)
-    SP_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $ACR_IDENTITY --query principalId --output tsv)
-    CLIENT_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $ACR_IDENTITY --query clientId --output tsv)
+    - login to acr with command `az acr login -n $ACR_NAME`
+    - use a simple java image as the placeholder image:
 
-    # assign role
-    az role assignment create --assignee $SP_ID --scope $ACR_ID --role acrpull
+    ```bash
+    az acr import --name $ACR_NAME \
+        --source mcr.microsoft.com/azurespringapps/default-banner:distroless-2024022107-66ea1a62-87936983 \
+        --image azurespringapps/default-banner:latest
     ```
 
-1. Prepare your images to Azure Container Registry
-    You may use the ACR createed in Lab 3, and the user managed identity too.
-    Please build your passwordless image after Lab 4.
-
-1. In your local repo, open file `infra/bicep/main.parameters.json`, fill the parameters
-
-    - vnetEndpointInternal: is the container apps subnet internal-only?
-    - sqlAdmin: the admin user for sql server
-    - sqlAdminPassword: the admin password for sql server
-    - configGitRepo: Default to this repo `https://github.com/Azure-Samples/spring-petclinic-microservices-config`
-    - configGitPath: `passwordless` profile default to directory `config` in this repo
-    - acrRegistry: The ACR address with your build images, `$MYACR.azurecr.io`
-    - acrIdentityId: The user mananged identity id with AcrPull access, `$ACR_UMID`
-    - miPrincipalId: The principal id for the user mananged identity, `$SP_ID`
-    - miClientId: The client id for the user mananged identity, `$CLIENT_ID`
-    - apiGatewayImage: The API gateway image with tag
-    - customerServiceImage: The customer service image with tag
-    - vetsServiceImage: The vets service image with tag
-    - visitsServiceImage: The visits service image with tag
-    - adminServerImage: The admin server image with tag
-    - chatAgentImage: The chat agent image with tag
-    - applicationInsightsConnString: The connection string of your AI instance
+1. Fill the azd configuration files
+
+    - In your local repo, open file `azure.yaml`
+        - replace all the `<your-acr>` with your variable `$ACR_NAME`
+
+    - By default, the azd tool will create all resource into the same resource group, default to `rg-${environmentName}`
+    Please refer to file [main.bicep](../../infra/bicep/main.bicep) for more configurations.

docs/06_lab_automation/0602.md

@@ -2,61 +2,41 @@
 title: '2. Run Azd'
 layout: default
 nav_order: 2
-parent: 'Lab 8: Use Azd to deploy the lab solution'
+parent: 'Lab 6: Deploy to Azure automatically'
 ---
 
-# 1. Run Azd Command to deploy
+# 2. Run Azd Command to deploy
 
 Run `azd up` to deploy the petclinic solution and dependent components to Azure Container App
 
 ## Step by step guidance
 
 1. Run `azd up`
-
-    - fill your environment name.
-    - select the target subscription
-    - select the target region
-
-    This command will create these components to your environment:
-
-    - Resource Group
-    - Virtual Network with subnets
-    - Log Analytics Workspace
-    - Azure Container Apps environment
-    - Managed components in ACA environment: SpringCloudEureka / SpringCloudConfig / SpringBootAdmin
-    - MySQL flexibleServers
-    - The petclinic solution apps api-gateway, admin-server, customer-service, vets-service, visits-service
-
-    You can view detailed progress in the Azure Portal: xxx
-    Open the link to check the deployment status in portal
-
-    {: .note }
-    > You may encounter some failures during the deploy, fix the errors according to the deployment status.
-    > If there are internal errors, please re-run the `azd up` commands to redeploy.
-
-1. Run rebuild service connection from apps to sql database
-    Due to some limitation, the bicep won't create database user for the service connections, See Lab 4 step 2.
-
-    Run the commands below to create the db user
-
-    ```bash
-    CLIENT_ID=$(az identity show --resource-group $RESOURCE_GROUP --name $ACA_IDENTITY --query 'clientId' --output tsv)
-    echo $CLIENT_ID
-    az containerapp connection create mysql-flexible \
-    --connection mysql_conn \
-    --source-id $CUSTOMERS_ID \
-    --target-id $DB_ID \
-    --client-type SpringBoot \
-    --user-identity client-id=$CLIENT_ID subs-id=$SUBID mysql-identity-id=$ADMIN_IDENTITY_RESOURCE_ID \
-    -c customers-service
+    Fill the variables required from the prompt:
+
+    ```text
+    ? Enter a new environment name: <env-name>
+    ? Select an Azure Subscription to use: xxx xxx
+    ? Select an Azure location to use: xxx
+    ? Enter a value for the 'acrGroupName' infrastructure parameter: <your acr group>
+    ? Enter a value for the 'acrName' infrastructure parameter: <your acr name>
+    ? Enter a value for the 'acrSubscription' infrastructure parameter: <your acr subscription>
     ```
 
-    Only one command required for this solution:
+    You may find the settings in directory `.azure/<env-name>/`
+
+    Then azd commands are executed:
+        - azd package: package your solution via the services and docker configurations in ./azure.yaml
+        - azd provision: create/update the azure resources defined in infra/bicep/main.bicep
+        - azd deploy: deploy the local build solution to azure services.
 
-    - The apps share the same connection name, so same user name in db.
-    - Once the user name is set, your don't have to recreate it.
+    If you meet any problems during this step, refer to page [Triage the issues](0603.md)
 
-1. Verify
+1. Run  `azd show`
+    You may see lots of variables from the results.
+    Open the urls to your deployed service:
 
-    - visit the api-gateway Application Url
-    - visit the admin-server Application Url
+    ```text
+    gatewayFqdn="api-gateway.<cluster-id>.<region>.azurecontainerapps.io"
+    adminFqdn="admin-server.<cluster-id>.<region>.azurecontainerapps.io"
+    ```

docs/06_lab_automation/0603.md

@@ -0,0 +1,38 @@
+---
+title: '3. Triage the issues'
+layout: default
+nav_order: 3
+parent: 'Lab 6: Deploy to Azure automatically'
+---
+
+# 3. Triage the issues
+
+1. Visit deployment details
+  From the command output, find the hint:
+  `You can view detailed progress in the Azure Portal:`
+  And visit the link to see the details of your deployment.
+
+  In your deployment page, you may click each Resource link, and check the Inputs/Output variables for better triage.
+
+1. Failed to provision java component 'configserver'
+
+    ```text
+    ERROR: error deploying infrastructure: deploying to subscription:
+
+    Deployment Error Details:
+    JavaComponentOperationError: Failed to provision java component 'configserver'. Error details: Failed to create config map external-auth-config-map for JavaComponent configserver in k8se-system namespace. There will be no re-tries..
+    ```
+
+    > This is a temporary error in service, just ignore and retry.
+
+1. Failed to deploy open AI instance
+
+    ```text
+    InvalidTemplateDeployment: The template deployment 'openai' is not valid according to the validation procedure. The tracking id is 'xxx'. See inner errors for details.
+    SpecialFeatureOrQuotaIdRequired: The subscription does not have QuotaId/Feature required by SKU 'S0' from kind 'OpenAI' or contains blocked QuotaId/Feature.
+    ```
+
+    > Azure OpenAI is not enabled in your subscription + region settings, please check the feature status. You may edit the configurations in `./infra/bicep/main.parameters.json`
+    > - Disable openAI by set *enableOpenAi = false* and run *azd up*.
+    > - Find a subcription + region combination and set the values `openAiSubscription`, `openAiLocation`, and run *azd up*.
+    > - Use an existed openAI instance. See guide in page [Reuse existing resource](./0604.md)

docs/06_lab_automation/0604.md

@@ -0,0 +1,13 @@
+---
+title: '4. Reuse existing resource'
+layout: default
+nav_order: 4
+parent: 'Lab 6: Deploy to Azure automatically'
+---
+
+# 4. Reuse existing resource
+
+The default `azd up` process will create lots of resource into the target resource group.
+Sometimes you may reuse some existing resources for your solution.
+
+1. Reuse Azure openAI instance

docs/06_lab_automation/06_openlab_automation.md

@@ -1,11 +1,11 @@
 ---
-title: 'Lab 6: Automatically deploy lab solution to Azure Container Apps'
+title: 'Lab 6: Deploy to Azure automatically'
 layout: default
 nav_order: 8
 has_children: true
 ---
 
-# Lab 6: Automatically deploy lab solution to Azure Container Apps
+# Lab 6: Deploy to Azure automatically
 
 # Student manual
 
@@ -14,14 +14,14 @@ has_children: true
 In the Lab 2, Lab 3, Lab 4 and Lab 5 we deploy the petclinic microservice solution to Azure Container Apps step by step.
 These steps are full of details but time costing.
 
-In this lab, we import a new tool [azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) to help deploy the solution to Azure with single command.
+In this lab, we introduce a new tool [azd](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/) to help deploy the solution to Azure with single command.
 
 ## Objectives
 
 After you complete this lab, you will be able to:
 
 - Get familiar with the azd tool.
-- Deploy the petclinic solution to new ACA environment.
+- Deploy the petclinic solution (with AI) to new ACA environment.
 - Test your setup.
 
 ## Lab Duration
@@ -35,7 +35,7 @@ During this lab, you will:
 - Prepare your azd tools environment.
 - Get your Azure Registry ready and fill the configuration files.
 - Run `azd up` command to deploy the sample soluton to Azure Container Apps.
-- Test your setup.
+- Learn how to triage some problems with the one-click solution.
 
 ## Limits
 

docs/07_lab_security/0701.md

@@ -2,7 +2,7 @@
 title: '1. Networking resources'
 layout: default
 nav_order: 1
-parent: 'Lab 6: Protect endpoints using Web Application Firewalls'
+parent: 'Lab 7: Protect endpoints using Web Application Firewalls'
 ---
 
 # Create additional networking resources

docs/07_lab_security/0702.md

@@ -2,7 +2,7 @@
 title: '2. Create Key Vault'
 layout: default
 nav_order: 2
-parent: 'Lab 6: Protect endpoints using Web Application Firewalls'
+parent: 'Lab 7: Protect endpoints using Web Application Firewalls'
 ---
 
 # Create an Azure Key Vault service

docs/07_lab_security/0703.md

@@ -2,7 +2,7 @@
 title: '3. Certificate'
 layout: default
 nav_order: 3
-parent: 'Lab 6: Protect endpoints using Web Application Firewalls'
+parent: 'Lab 7: Protect endpoints using Web Application Firewalls'
 ---
 
 # Acquire a certificate and add it to Key Vault