deployment-instructions.md

Contoso Traders - Deployment instructions

This document will help you deploy the Contoso Traders application in your Azure environment. You'll be using both GitHub Actions and Azure CLI for this.

Once deployed, you'll be able to walk through various demo scenarios for Microsoft Playwright, Azure Load Testing, and Azure Chaos Studio.

Prerequisites

You will need following to get started:

1. GitHub account: Create a free account here.
2. Azure subscription: Create a free account here.
3. Azure CLI: Instructions to download and install here.

Prepare your Azure Subscription

1. Log into Azure CLI with your Azure credentials: az login

2. Ensure that the correct Azure subscription is selected: az account show

   • If not, select the correct subscription: az account set -s <AZURE-SUBSCRIPTION-ID>. Replace <AZURE-SUBSCRIPTION-ID> with your Azure subscription ID.

3. Register some required resource providers in your Azure subscription:

   • az provider register -n Microsoft.OperationsManagement -c
   • az provider register -n Microsoft.Cdn -c
   • az provider register -n Microsoft.Chaos -c

4. Create an Azure Service Principal and add it to the Owner role in your Azure subscription:

   • az ad sp create-for-rbac -n contosotraders-sp --role Owner --scopes /subscriptions/<AZURE-SUBSCRIPTION-ID> --sdk-auth. Replace <AZURE-SUBSCRIPTION-ID> with your Azure subscription ID.
   • Make a note of the JSON output from above step (especially the clientId, clientSecret, subscriptionId and tenantId properties). These will be required later.
   • You'll notice a warning in the output: Option '--sdk-auth' has been deprecated and will be removed in a future release. This is a known issue, without workarounds, but can be safely ignored.

5. If for some reason, you do not have permissions to add the service principal in the Owner role on the subscription, then you can create a custom role and assign it to the service principal as follows (remember to replace <AZURE-SUBSCRIPTION-ID> in snippets below with your Azure subscription ID).

   1. If using bash:

      az role definition create --role-definition '{
          "Name": "ContosoTraders Write Role Assignments",
          "Description": "Perform Role Assignments",
          "Actions": ["Microsoft.Authorization/roleAssignments/write"],
          "AssignableScopes": ["/subscriptions/<AZURE-SUBSCRIPTION-ID>"]
      }'

   2. If using PowerShell or cmd shell, you can run az role definition create --role-definition ./custom-role.json. Note that you need to first create a file called custom-role.json containing the following snippet.

      {
          "Name": "ContosoTraders Write Role Assignments",
          "Description": "Perform Role Assignments",
          "Actions": ["Microsoft.Authorization/roleAssignments/write"],
          "AssignableScopes": ["/subscriptions/<AZURE-SUBSCRIPTION-ID>"]
      }

   3. Finally create the service principal and assign it to the custom role:

      `az ad sp create-for-rbac -n contosotraders-sp --role "ContosoTraders Write Role Assignments" --scopes /subscriptions/<AZURE-SUBSCRIPTION-ID> --sdk-auth`

Prepare your GitHub Account

1. Fork the contosotraders-cloudtesting repo in your account.

2. Set up the repository secrets in your forked repo. On your fork of the github repository, go to the Settings tab > Secrets and variables > Actions > Secrets tab and create these necessary repository secrets:

   Secret Name	Secret Value
   SQL_PASSWORD	A password which will be set on all SQL Azure DBs
   SERVICEPRINCIPAL	See details below

   The value of the SERVICEPRINCIPAL secret above needs to have the below format.

   {
     "clientId": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
     "clientSecret": "your-client-secret",
     "tenantId": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz",
     "subscriptionId": "zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz"
   }

   The values of the properties needed can be found in the JSON output of the az ad sp create-for-rbac command in the previous section.

3. Create two environments for deployment. On your fork of the github repository, go to the Settings tab > Environments > Click on New Environment button and create the following two environments:

   • staging

   • production (optional)

   • Then, for each of these above environments, create this environment variable:

   Variable Name	Variable Value
   SUFFIX	A unique environment suffix (max 6 characters, alphanumeric, lower case only, no whitespace, no special chars). E.g. 'test51' or '1stg'

Deploy the Application

1. Go to your forked repo's Actions tab, selecting the contoso-traders-cloud-testing workflow, and click on the Run workflow button.

2. This github workflow will provision the necessary infrastructure to your Azure subscription as well as deploy the applications (APIs, UI) to the infrastructure. Note that the workflow might take about 15 mins to complete.

Verify the Deployment

1. Once the workflow completes, the UI's accessible CDN endpoint URL will be displayed in the github workflow run.

   

2. Clicking on the URL above, will load the application in a new browser tab. You can then verify that the application is indeed up and running.

Troubleshooting Deployment Errors

Here are some common problems that you may encounter during deployment:

1. AI Terms and services: If you see an error stating that "Responsible AI terms are not accepted for this subscription", you'll have to manually create an Azure Cognitive Service resource in your subscription temporarily, and accept the Responsible AI terms. Once created, you can then re-run the workflow job.

   • The Responsible AI terms are shown only once per subscription (during first Cognitive Service resource creation in subscription), and once accepted, they are not shown again.
   • Currently, there exists no mechanism to accept the Responsible AI terms programmatically. It can only be done manually through the Azure portal.
   • You can read more about Responsible AI here.

2. Other intermittent errors: Should you encounter any of these intermittent errors in the github workflow, please re-run the failed jobs (it'll will pass on retry). We're working to fix these soon.

Explore Demo Scenarios

For further learning, you can run through some of the demo scripts listed below:

• Developer workflow
• Azure Load Testing
• Azure Chaos Studio
• UI Testing with Playwright

Cleanup

Once you are done deploying, testing, exploring, you should delete the contoso-traders-rg{SUFFIX} resource group to prevent incurring additional costs.

The contoso-traders-aks-nodes-rg{SUFFIX} will be automatically deleted as part of the AKS cluster deletion.

Cost Considerations

A quick note on costs considerations when you deploy the application to your Azure subscription:

1. Azure Load Testing (pricing details): The number of virtual users and duration of the test are the key factors that determine the cost of the test. In this demo, the load tests are configured to use 5 virtual users and the test is set to run for 3 mins.
2. Azure Kubernetes Service (pricing details): The number of nodes and the number of hours that the cluster is running are the key factors that determine the cost of the cluster. In this demo, the cluster is configured to use 1 node (powered by vm scale sets) and the cluster is set to run 24x7 (you can manually stop the cluster when not in use). Because of a limitation in the AKS bicep schema, the AKS cluster has to use premium SSD storage disks.
3. Azure Container Apps (pricing details): Each instance has 0.5 vCPU and 1.0 GiB of memory. In this demo, the container app is configured to use 1 instance, but can autoscale out to max 3 instances under load.
4. Azure Virtual Machines (pricing details): The jumpbox VM uses the Standard_D2s_v3 VM size, which has 2 vCPU and 8 GiB of memory. The jumpbox VMs are schedule to auto-shutdown at 1900 UTC daily. You can also manually stop & deallocate the VM when not in use.
5. Github Actions / storage quota (pricing details): We've set the playwright test to enable recordings only on failures/retries. This brings the playwright report to ~55 MB when tests fail.

The above costs are based on the default configuration of the demo. You can modify the configuration to reduce the costs. For example, you can reduce the number of instances in the container app, reduce the number of virtual users in the load test, etc.