Merge pull request #261394 from KimForss/main

Update main doc

Author: v-dirichards

articles/sap/automation/deployment-framework.md

@@ -73,53 +73,50 @@ The application configuration is performed from the deployment agents in the con
 
 For more information about how to configure and deploy the control plane, see [Configure the control plane](configure-control-plane.md) and [Deploy the control plane](deploy-control-plane.md).
 
-## Software acquisition process
-
-The framework also provides an Ansible playbook that can be used to download the software from SAP and persist it in the storage accounts in the control plane's SAP library resource group.
-
-The software acquisition is using an SAP application manifest file that contains the list of SAP software to be downloaded. The manifest file is a YAML file that contains the:
-
-- List of files to be downloaded.
-- List of the product IDs for the SAP application components.
-- Set of template files used to provide the parameters for the unattended installation.
-
-The SAP software download playbook processes the manifest file and the dependent manifest files and downloads the SAP software from SAP by using the specified SAP user account. The software is downloaded to the SAP library storage account and is available for the installation process.
-
-As part of the download process, the application manifest and the supporting templates are also persisted in the storage account. The application manifest and the dependent manifests are aggregated into a single manifest file that is used by the installation process.
-
 ### Deployer VMs
 
 These VMs are used to run the orchestration scripts that deploy the Azure resources by using Terraform. They're also Ansible controllers and are used to execute the Ansible playbooks on all the managed nodes, that is, the VMs of an SAP deployment.
 
-## About the SAP workload
-
-The SAP workload contains all the Azure infrastructure resources for the SAP deployments. These resources are deployed from the control plane.
-
-The SAP workload has two main components:
-
-- SAP workload zone which is used for the shared resources for the SAP systems
-- SAP systems
 
 ## About the SAP workload zone
 
-The workload zone allows for partitioning of the deployments into different environments, such as development, test, and production. The workload zone provides the shared resources (networking and credentials management) to the SAP systems.
+The workload zone allows for partitioning of the SAP systems deployments into different environments, such as development, test, and production. The workload zone provides the shared resources (networking and credentials management) that are used by the SAP systems. 
+
+You would typically create a workload zone for each unique Azure Virtual network (VNet) that you want to deploy the SAP systems into.
 
 The SAP workload zone provides the following services to the SAP systems:
 
 - Virtual network
 - Azure Key Vault for system credentials (VMs and SAP accounts)
 - Shared storage (optional)
 
+It is recommended to deploy the workload zone into a spoke subscription in a [hub-and-spoke architecture](/azure/architecture/reference-architectures/hybrid-networking/hub-spoke) and use a dedicated deployment credential for each workload zone. 
+
 For more information about how to configure and deploy the SAP workload zone, see [Configure the workload zone](configure-workload-zone.md) and [Deploy the SAP workload zone](deploy-workload-zone.md).
 
-## About the SAP system
+## About the SAP systems
 
-The system deployment consists of the VMs that run the SAP application, including the web, app, and database tiers.
+Each SAP system is deployed into a dedicated resource group and they use the services from the workload zone. 
 
-The SAP system provides VM, storage, and support infrastructure to host the SAP applications.
+The SAP system deployment consists of the VMs and the associated resources required to run the SAP application, including the web, app, and database tiers.
 
 For more information about how to configure and deploy the SAP system, see [Configure the SAP system](configure-system.md) and [Deploy the SAP system](deploy-system.md).
 
+
+## Software acquisition process
+
+The framework also provides an Ansible playbook that can be used to download the software from SAP and persist it in the storage accounts in the control plane's SAP library resource group.
+
+The software acquisition is using an SAP application manifest file that contains the list of SAP software to be downloaded. The manifest file is a YAML file that contains the:
+
+- List of files to be downloaded.
+- List of the product IDs for the SAP application components.
+- Set of template files used to provide the parameters for the unattended installation.
+
+The SAP software download playbook processes the manifest file and the dependent manifest files and downloads the SAP software from SAP by using the specified SAP user account. The software is downloaded to the SAP library storage account and is available for the installation process.
+
+As part of the download process, the application manifest and the supporting templates are also persisted in the storage account. The application manifest and the dependent manifests are aggregated into a single manifest file that is used by the installation process.
+
 ## Glossary
 
 The following terms are important concepts for understanding the automation framework.

articles/sap/automation/tutorial.md

@@ -158,7 +158,7 @@ A valid SAP user account (SAP-User or S-User account) with software download pri
 
     To run the automation framework, update to the following versions:
 
-    - `az` version 2.4.0 or higher.
+    - `az` version 2.5.0 or higher.
     - `terraform` version 1.5 or higher. [Upgrade by using the Terraform instructions](https://www.terraform.io/upgrade-guides/0-12.html), as necessary.
 
 ## Create a service principal
@@ -214,14 +214,56 @@ When you choose a name for your service principal, make sure that the name is un
 > [!IMPORTANT]
 > If you don't assign the User Access Administrator role to the service principal, you can't assign permissions by using the automation.
 
+## Configure the control plane web application credentials
+
+As a part of the SAP automation framework control plane, you can optionally create an interactive web application that assists you in creating the required configuration files and deploying SAP workload zones and systems using Azure Pipelines.
+
+:::image type="content" source="./media/deployment-framework/webapp-front-page.png" alt-text="Screenshot of Web app front page.":::
+
+
+### Create an app registration
+
+If you would like to use the web app, you must first create an app registration for authentication purposes. Open the Azure Cloud Shell and execute the following commands:
+
+Replace MGMT with your environment as necessary.
+
+```bash
+echo '[{"resourceAppId":"00000003-0000-0000-c000-000000000000","resourceAccess":[{"id":"e1fe6dd8-ba31-4d61-89e7-88639da4683d","type":"Scope"}]}]' >> manifest.json
+
+app_registration_app_id=$(az ad app create    \
+    --display-name MGMT-webapp-registration   \
+    --enable-id-token-issuance true           \
+    --sign-in-audience AzureADMyOrg           \
+    --required-resource-access @manifest.json \
+    --query "appId" | tr -d '"')
+
+webapp_client_secret=$(az ad app credential reset \
+    --id $TF_VAR_app_registration_app_id --append \
+    --query "password" | tr -d '"')
+
+echo "App registration ID:  ${app_registration_app_id}"
+echo "App registration password:  ${webapp_client_secret}"
+
+rm manifest.json
+```
+
+Copy down the output details. Make sure to save the values for `appId`, `password`, and `Tenant`.
+
+The output maps to the following parameters. You use these parameters in later steps, with automation commands.
+
+| Parameter input name      | Output name                       |
+| ------------------------- | --------------------------------- |
+| `app_registration_app_id` | `App registration ID`             |
+| `webapp_client_secret`    | `App registration password`       |
+
 ## View configuration files
 
 1. Open Visual Studio Code from Cloud Shell.
 
-    ```cloudshell-interactive
-    cd ~/Azure_SAP_Automated_Deployment/WORKSPACES
-    code .
-    ```
+```cloudshell-interactive
+cd ~/Azure_SAP_Automated_Deployment/WORKSPACES
+code .
+```
 
 1. Expand the `WORKSPACES` directory. There are five subfolders: `CONFIGURATION`, `DEPLOYER`, `LANDSCAPE`, `LIBRARY`, `SYSTEM`, and `BOMS`. Expand each of these folders to find regional deployment configuration files.
 
@@ -376,7 +418,7 @@ You need to note some values for upcoming steps. Look for this text block in the
 #########################################################################################
 ```
 
-1. Go to the [Azure portal](https://portal.azure.com).
+2. Go to the [Azure portal](https://portal.azure.com).
 
     Select **Resource groups**. Look for new resource groups for the deployer infrastructure and library. For example, you might see `MGMT-[region]-DEP00-INFRASTRUCTURE` and `MGMT-[region]-SAP_LIBRARY`.