feat: finalize aca-revision and aks-store-on-aca

Signed-off-by: Kristina Devochko <guidemetothemoon@gmail.com>

.github/workflows/deploy-aca-revision-and-traffic-management.yaml

@@ -1,3 +1,4 @@
+# This workflow provisions all the necessary resources for the demo application from aca-revision-and-traffic-management folder.
 # Traffic splitting can be automated further, with revision name generation, health checks and full re-routing to the new version upon successful checks.
 # Microsoft has created a useful repository with a sample implementation of this process that can be used for reference and inspiration: https://github.com/Azure-Samples/containerapps-blue-green
 name: deploy-aca-revision-and-traffic-management-apps

aca-revision-and-traffic-management/README.md

@@ -1 +1,18 @@
 # Revision and traffic management in Azure Container Apps
+
+This folder contains Bicep code for provisioning a demo application that can be used to see multiple revisions and traffic splitting for Azure Container Apps in action. Demo application itself is a simple Hello World application that was initially created by Microsoft for AKS demos, but why not re-use it for Azure Container Apps as well?😼
+
+## Deployment instructions
+
+1. Deploy code as-is first (after adjusting parameters as per your use case) - initially in ```aca-public-apps.bicep``` it's defined that application will be deployed in multi-revision mode, but when we start from nothing only one, first, revision will be deployed. Due to that in ```*.bicepparam``` file traffic distribution is configured to send 100% traffic to the latest revision, which will be the app's very first revision.
+
+2. Let's make a change to the application to create a new revision - in ```aca-public-apps.bicep``` update ```TITLE``` environment variable with a new value that can identify new app revision. Next, let's update traffic distribution:
+    2.1. Get name of the currently active, first app revision by running following Azure CLI command (update ```resource-group``` parameter with the one defined in the respective ```.bicepparam``` file): ```az containerapp revision list --name aca-helloworld --resource-group <acaResourceGroupName_parameter_value> --query [0].name -o tsv```
+    2.2. In the respective ```.bicepparam``` file update ```trafficDistribution``` array: update weight number for ```latestRevision``` object - this object represents every new revision that's being provisioned. Uncomment second object and update ```revisionName``` value with the one retrieved in step 2.1. Then update ```weight``` value with the amount of traffic you want to send to the previous/initial revision. **Please note that weight for all revisions combined must be 100.**
+3. Re-provision resources with the new changes. Go to the public URL of the app and do a bunch of refreshes to verify that traffic is now routed to both versions/revisions of the application.
+
+### GitHub Actions Workflow
+
+Example of a GitHub Actions Workflow has been set up for you to use in your own repository to provision resources in this folder. Workflow is available in ```.github/workflows/deploy-aca-revision-and-traffic-management.yaml``` file in the root of the repository. Please note that you need to configure GitHub secrets for the workflow to be able to log into your Azure subscription and provision resources to it. I would recommend setting up a managed identity with federated credential for this purpose and give it Contributor permissions on the subscription level (resource group provisioning is part of the Bicep code, but you can also provision resource group outside of this deployment and then only give the identity permissions on the respective resource group's level).
+
+Please refer following Microsoft documentation on how to set up managed identity with federated credentials for usage in GitHub Actions worfklow: [Use GitHub Actions to connect to Azure](https://learn.microsoft.com/en-us/azure/developer/github/connect-from-azure?tabs=azure-portal%2Clinux)

aca-revision-and-traffic-management/main.bicep

@@ -1,18 +1,28 @@
 targetScope='subscription'
 
+@description('Resource group name where all resources for the deployment will be provisioned.')
 param acaResourceGroupName string
+
+@description('Environment name (dev, test, prod)')
 param environment string
+
+@description('Location where resources will be provisioned')
 param location string
+
+@description('Tags to be applied to all resources in this deployment')
 param tags object
+
+@description('Array that represents desired traffic distribution between container apps revisions')
 param trafficDistribution array
 
 resource rg 'Microsoft.Resources/resourceGroups@2022-09-01' = {
   name: acaResourceGroupName
   location: location
 }
 
+@description('Module that provisions common resources that will be re-used by other resources in the deployment, like managed identities')
 module common 'modules/common.bicep' = {
-  name: 'common'
+  name: 'common-resources'
   scope: rg
   params: {
     environment: environment
@@ -21,29 +31,29 @@ module common 'modules/common.bicep' = {
   }
 }
 
-module acaenvironment 'modules/aca-environment.bicep' = {
-  name: 'aca-environment'
+@description('Module that provisions common overall resources for Azure Container Apps, like Azure Container Apps environment.')
+module aca_common 'modules/aca-common.bicep' = {
+  name: 'aca-common'
   scope: rg
   params: {
     location: location
     managedIdentityId: common.outputs.managedIdentityId
     tags: tags
   }
-  dependsOn: [common]
 }
 
-module aca 'modules/aca.bicep' = {
-  name: 'aca'
+@description('Module that provisions publicly accessible applications as Azure Container Apps.')
+module public_apps 'modules/aca-public-apps.bicep' = {
+  name: 'public-apps'
   scope: rg
   params: {
-    environmentId: acaenvironment.outputs.environmentId
+    environmentId: aca_common.outputs.environmentId
     location: location
     managedIdentityId: common.outputs.managedIdentityId
     tags: tags
     trafficDistribution: trafficDistribution
   }
-  dependsOn: [acaenvironment]
 }
 
-@description('URL for store application')
-output storeUrl string = aca.outputs.helloWorldAppUri
+@description('URL for accessing Hello World application')
+output helloWorldUrl string = public_apps.outputs.helloWorldAppUri

aca-revision-and-traffic-management/modules/aca.bicep → aca-revision-and-traffic-management/modules/aca-public-apps.bicep

@@ -39,7 +39,7 @@ resource helloworld 'Microsoft.App/containerApps@2023-05-02-preview' = {
           env: [
             {
               name: 'TITLE'
-              value: 'Hello World from Azure Container Apps (ACA) - V2!'
+              value: 'Hello World from Azure Container Apps (ACA)!'
             }
           ]
           probes: [

aca-revision-and-traffic-management/parameters/dev.bicepparam

@@ -11,12 +11,12 @@ param tags = {
 param trafficDistribution = [
   {
     latestRevision: true
-    weight: 50
+    weight: 100
   }
-  {
-    revisionName: 'aca-helloworld--f8u0hny'
+  /*{
+    revisionName: ''
     weight: 50
-  }
+  }*/
 ]
 
-// Command to get revision name: az containerapp revision list --name aca-helloworld --resource-group rg-aca-helloworld-neu-dev --query [0].name -o tsv
+// Command to get revision names: az containerapp revision list --name aca-helloworld --resource-group rg-aca-helloworld-neu-dev --query [].name -o tsv

aca-revision-and-traffic-management/parameters/prod.bicepparam

@@ -19,3 +19,5 @@ param trafficDistribution = [
     weight: 50
   }*/
 ]
+
+// Command to get revision names: az containerapp revision list --name aca-helloworld --resource-group rg-aca-helloworld-neu-dev --query [].name -o tsv

aks-store-on-aca/README.md

@@ -1,18 +1,20 @@
 # Implementation of AKS Store Demo App with Azure Container Apps
 
-This folder contains Bicep code for provisioning [aks-store-demo](https://github.com/Azure-Samples/aks-store-demo) but on Azure Container Apps. Deployment also is created in a manner that's closer to an actual production scenario, including security hardening configuration.
+This folder contains Bicep code for provisioning [aks-store-demo](https://github.com/Azure-Samples/aks-store-demo), but on Azure Container Apps. Deployment also is created in a manner that's closer to an actual production scenario, including security hardening configuration.
 
 Below you may find the solution architecture diagram:
 
 TODO
 
-Implementation includes following modules: (TODO: add details)
+Implementation includes following modules:
 
-* ```common```
-* ```azure-monitor```
-* ```network```
-* ```keyvault```
-* ```ai```
-* ```aca-common```
-* ```aca-public-apps```
-* ```aca-internal-apps```
+* ```common```: includes common, shared resources that are used by other resources in the deployment. For example, managed identities or deployment-specific Azure Policy assignments.
+* ```network```: includes network-related resources. For example, virtual networks, subnets and network security groups.
+* ```dns```: includes DNS-related resources. For example, private DNS zones.
+* ```vnet_links```: includes virtual network link resources for mapping of virtual networks with private DNS zones, which is required for the private endpoints to function properly.
+* ```kv```: includes Azure Key Vault resources, with enabled RBAC and configuration for secure access to the resources with private endpoints.
+* ```azure_monitor```: includes observability-related resources, like Log Analytics, Application Insights, etc. It also includes Azure Monitor Private Link Scope (AMPLS) and related resources for configuration of secure access to Azure Monitor services.
+* ```ai```: includes cognitive services, like Azure OpenAI with respective model deployments and configuration for secure access to the resources with private endpoints.
+* ```aca_common```: includes resources that are common for Azure Container Apps, like Azure Container Apps environment and network configuration for secure communication to and between apps.
+* ```internal_apps```: includes container apps that are not publicly accessible, i.e. internal services.
+* ```public_apps```: includes container apps that are publicly accessible.

aks-store-on-aca/functions.bicep

@@ -1,4 +1,6 @@
-// Re-used from https://github.com/Azure/bicep/issues/5703#issuecomment-2004230485 
+// Re-used from https://github.com/Azure/bicep/issues/5703#issuecomment-2004230485
+
+@description('User-defined, re-usable function that can be used to replace multiple strings in a specific string, which is currently not supported out of the box by the replace() function in Bicep.')
 @export()
 func replaceMultipleStrings(input string, replacements { *: string }) string => reduce(
   items(replacements), input, (cur, next) => replace(string(cur), next.key, next.value))