Merge pull request Azure#583 from Azure/canary

Add resourceTags parameter documentation for HCIBox

Author: janegilring

docs/azure_jumpstart_hcibox/AKS/_index.md

@@ -12,7 +12,7 @@ Azure Local can provide host infrastructure for [Azure Kubernetes Service cluste
 
 HCIBox is preconfigured with a network subnet dedicated to AKS deployment. Subnet details are as follows:
 
-  | Network details |                  |
+  | Network detail |        Value          |
   | ---------- | --------------------- |
   | Subnet     | 10.10.0.0/24          |
   | Gateway    | 10.10.0.1             |

docs/azure_jumpstart_hcibox/RB/_index.md

@@ -33,7 +33,7 @@ Before you can create virtual machines on your Azure Local instance from Azure p
 
 HCIBox networking includes a 192.168.200.0/24 subnet tagged to VLAN200. This network is designed for use with Arc-enabled VMs on HCIBox. To use this preconfigured network, you must create a logical network resource that maps to this subnet.
 
-  | Network details |                  |
+  | Network detail |        Value          |
   | ---------- | --------------------- |
   | Subnet     | 192.168.200.0/24      |
   | Gateway    | 192.168.200.1         |

docs/azure_jumpstart_hcibox/cloud_deployment/_index.md

@@ -8,7 +8,7 @@ weight: 5
 
 ## Start post-deployment automation
 
-Once your bicep deployment is complete with Azure CLI or Azure Developer CLI, you can open the Azure portal to see the initial HCIBox resources inside your resource group. Now you must remote into the _HCIBox-Client_ VM to continue the next phase of the deployment.
+Once your Bicep deployment is complete, you can open the Azure portal to see the initial HCIBox resources inside your resource group. Now you must remote into the _HCIBox-Client_ VM to continue the next phase of the deployment.
 
   ![Screenshot showing all deployed resources in the resource group](./deployed_resources.png)
 
@@ -70,27 +70,28 @@ If you already have [Microsoft Defender for Cloud](https://learn.microsoft.com/a
 
 ### The Logon scripts
 
-- Once you log into the _HCIBox-Client_ VM, a PowerShell script will open and start running. This script will take anywhere between 2-3 hours to finish, and once completed, the script window will close automatically. If there are any HCI updates available, we need to add 1 additional hour to the estimated deployment time. 
+- Once you log into the _HCIBox-Client_ VM, a PowerShell script will open and start running. This script will take anywhere between 2-3 hours to finish, and once completed, the script window will close automatically. If there are any HCI updates available, we need to add 1 additional hour to the estimated deployment time.
 At this point, the infrastructure deployment is complete.
 
   ![Screenshot showing _HCIBox-Client_](./automation.png)
 
-- In Azure portal, validate that both Azure Local machines (AzSHOST1 and AzSHOST2) have been created as Arc-enabled servers.
+- In the Azure portal, validate that both Azure Local machines (AzSHOST1 and AzSHOST2) have been created as Arc-enabled servers.
 
 - Verify that both of the Arc-enabled servers have successfully installed the three Azure Local extensions: AzureEdgeTelemetryAndDiagnostics, AzureEdgeLifecycleManager, and AzureEdgeDeviceManagement
 
   ![Screenshot showing extensions successfully installed](./extensions_installed.png)
 
-- If everything looks good, and you did not choose to configure the `autoDeployClusterResource` parameter with the value `true` in your deployment, proceed to the next section to validate and deploy your instance. If you did enable this parameter, you may proceed to the section _Deployment complete_ at the end of this page.
-Visit [troubleshooting](../troubleshooting/) if needed for deployment issues.
-
 ## Azure portal Azure Local instance validation and deployment
 
 Azure Local uses a two-step process to create and register instances in Azure using an ARM template.
 
   1. **Validate** - an ARM template is deployed with a "validate" flag. This begins the final instance validation step and takes around 20 minutes.
   2. **Deploy** - the same ARM template is redeployed with the "deploy" flag. This deploys the instance and Arc infrastructure and registers the instance. This step takes around 2-3 hours.
 
+If you chose to configure the `autoDeployClusterResource` parameter with the value `false` in your deployment, proceed to the next section to validate and deploy your instance. If you did not override this parameter, you may proceed to the section [_Deployment complete_](#deployment-complete) at the end of this page.
+
+Visit [troubleshooting](../troubleshooting/) if needed for deployment issues.
+
 ### Validate instance in Azure portal
 
 - Before submitting the ARM deployment, you need to add your user account as a Key Vault Administrator on the HCIBox resource group. Navigate to the resource group then click "Access Control (IAM)" and then "Add role assignment". Select the "Key Vault Administrator role" then click on to the next screen to select your user account and assign your user the role.
@@ -137,6 +138,10 @@ Azure Local uses a two-step process to create and register instances in Azure us
 
 ## Deployment complete
 
-- Once the HCIBox instance is deployed it's time to start exploring various HCIBox features. Head on to the [Using HCIBox](../using_hcibox/) guide for the next steps.
+In your HCIBox resource group, open the cluster resource `hciboxcluster`, navigate to `Settings` -> `Deployments` and verify that all steps has completed successfully.
+
+  ![Screenshot showing progress of deploying instance](./cluster_deployment_complete.png)
+
+Once the HCIBox instance is deployed it's time to start exploring various HCIBox features. Head on to the [Using HCIBox](../using_hcibox/) guide for the next steps.
 
   ![screenshot showing deployed instance](./cluster_detail.png)

docs/azure_jumpstart_hcibox/cloud_deployment/cluster_deployment_complete.png

@@ -1,15 +1,15 @@
 ---
 type: docs
-linkTitle: "Azure CLI Deployment"
+linkTitle: "Azure Bicep Deployment"
 isGettingStarted: false
 weight: 4
 ---
 
-# Deploy HCIBox infrastructure with Azure CLI
+# Deploy HCIBox infrastructure with Azure Bicep
 
-## Azure CLI
+## Azure Bicep
 
-Azure CLI is used to deploy HCIBox into your Azure subscription. To deploy, you require a service principal by your Azure administrator for use with HCIBox. Read on to learn how to deploy HCIBox with Azure CLI.
+Azure Bicep is used to deploy HCIBox into your Azure subscription. To deploy, you require a service principal by your Azure administrator for use with HCIBox. Read on to learn how to deploy HCIBox with Azure CLI.
 
 ### Prepare the environment
 
@@ -113,19 +113,41 @@ Azure CLI is used to deploy HCIBox into your Azure subscription. To deploy, you
 
 > **Note:** Please avoid using the $ symbol in the `windowsAdminPassword`. Using this symbol can cause the LogonScript to fail.
 
-- Edit the [main.parameters.json](https://github.com/microsoft/azure_arc/blob/main/azure_jumpstart_hcibox/bicep/main.parameters.json) template parameters file and supply some values for your environment.
-  - _`spnClientId`_ - Your Azure service principal id
-  - _`spnClientSecret`_ - Your Azure service principal secret
-  - _`spnTenantId`_ - Your Azure tenant id
-  - _`spnProviderId`_ - Your Azure Local resource provider id, retrieved in an earlier step
-  - _`windowsAdminUsername`_ - Client Windows VM Administrator username
-  - _`windowsAdminPassword`_ - Client Windows VM Password. Password must have 3 of the following: 1 lower case character, 1 upper case character, 1 number, and 1 special character. The value must be between 12 and 123 characters long.
-  - _`logAnalyticsWorkspaceName`_ - Unique name for the HCIBox Log Analytics workspace
-  - _`deployBastion`_ - Option to deploy Azure Bastion which used to connect to the _HCIBox-Client_ VM instead of normal RDP.
-  - _`autoDeployClusterResource`_ - Option to enable automatic deployment of the Azure Arc-enabled Azure Local instance after the client VM deployment and automation script execution is complete.
-  - _`autoUpgradeClusterResource`_ - Option to enable automatic upgrade of the Azure Arc-enabled Azure Local instance after the instance deployment is complete (only applicable if autoDeployClusterResource is set to `true`).
-
-  ![Screenshot showing example parameters](./parameters_bicep.png)
+- Edit the [main.parameters.json](https://github.com/microsoft/azure_arc/blob/main/azure_jumpstart_hcibox/bicep/main.bicepparam) template parameters file and supply values for your environment.
+
+| Name | Type | Description | Default |
+| --- | --- | --- | --- |
+| `autoDeployClusterResource` | bool | Choice to enable automatic deployment of Azure Arc enabled HCI cluster resource after the client VM deployment is complete. | true |
+| `autoUpgradeClusterResource` | bool | Choice to enable automatic upgrade of Azure Arc enabled HCI cluster resource after the client VM deployment is complete. Only applicable when autoDeployClusterResource is true. | false |
+| `deployBastion` | bool | Choice to deploy Bastion to connect to the client VM | false |
+| `githubAccount` | string | Target GitHub account | "microsoft" |
+| `githubBranch` | string | Target GitHub branch | "main" |
+| `governResourceTags` | bool | Setting this parameter to `true` will add the `CostControl` and `SecurityControl` tags to the provisioned resources. These tags are applicable to ONLY Microsoft-internal Azure lab tenants and designed for managing automated governance processes related to cost optimization and security controls | true |
+| `location` | string | Location to deploy resources | Resource group`s location |
+| `logAnalyticsWorkspaceName` | string | Name for your log analytics workspace |  |
+| `natDNS` | string | Public DNS to use for the domain | "8.8.8.8" |
+| `rdpPort` | string | Override default RDP port using this parameter. Default is 3389. No changes will be made to the client VM. | "3389" |
+| `spnClientId` | string | Azure service principal client id |  |
+| `spnClientSecret` | securestring | Azure service principal client secret |  |
+| `spnProviderId` | string | Azure AD object id for your Microsoft.AzureStackHCI resource provider |  |
+| `spnTenantId` | string | Azure AD tenant id for your service principal |  |
+| `tags` | object | Tags to be added to all resources | {"Project": "jumpstart_HCIBox"} |
+| `vmAutologon` | bool | Enable automatic logon into HCIBox Virtual Machine | true |
+| `windowsAdminPassword` | securestring | Password for Windows account. Password must have 3 of the following: 1 lower case character, 1 upper case character, 1 number, and 1 special character. The value must be between 12 and 123 characters long |  |
+| `windowsAdminUsername` | string | Username for Windows account |  |
+
+      > **Disclaimer:** The `governResourceTags` parameter is optional and set to true by default. If not specified, the following tag values will be added:
+
+  ```
+  CostControl: 'Ignore'
+  SecurityControl: 'Ignore'
+  ```
+
+     > Both the `CostControl` and `SecurityControl` tags are applicable to **ONLY Microsoft-internal Azure lab tenants** and designed for managing automated governance processes related to cost optimization and security controls. As mentioned, it will get added to the deployment **only** if the `governResourceTags` parameter was set to true. If you are deploying HCIBox from a Microsoft-internal tenant and Azure subscription, this parameter is required to be set to 'true'. Failure to do so will cause your deployment to have issues and most likely to fail.
+
+Example parameter-file:
+
+![Screenshot showing example parameters](./parameters_bicep.png)
 
 - Create a new resource group and then deploy the Bicep file. Navigate to the local cloned [deployment folder](https://github.com/microsoft/azure_arc/tree/main/azure_jumpstart_hcibox/bicep) and run the following command:
 

docs/azure_jumpstart_hcibox/deployment_az/_index.md

@@ -43,7 +43,7 @@ HCIBox resources generate Azure Consumption charges from the underlying Azure re
 
 ## Deployment Options and Flow
 
-HCIBox supports [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview?tabs=bicep) templates for both Azure CLI and [Azure Developer CLI](https://learn.microsoft.com/azure/developer/azure-developer-cli/overview) to deploy and configure necessary Azure resources.
+HCIBox supports [Bicep](https://learn.microsoft.com/azure/azure-resource-manager/bicep/overview?tabs=bicep) templates to deploy and configure necessary Azure resources.
 
 Deploying HCIBox is a multi-step process that includes:
 
@@ -56,7 +56,7 @@ Deploying HCIBox is a multi-step process that includes:
 
 ## Deploy HCIBox
 
-- [Deploy HCIBox with Azure CLI](../deployment_az/) : Requires pre-configured service principle.
+- [Deploy HCIBox with Azure Bicep](../deployment_az/) : Requires pre-configured service principal.
 
 Looking for something else related to HCIBox?
 

docs/azure_jumpstart_hcibox/deployment_az/parameters_bicep.png

@@ -18,9 +18,9 @@ HCIBox simulates a 2-node physical deployment of Azure Local by using [nested vi
 
 | Computer Name    | Role                                | Domain Joined | Parent Host     | OS                  |
 | ---------------- | ----------------------------------- | ------------- | --------------- | ------------------- |
-| _HCIBox-Client_  | Primary host                        | No            | Azure           | Windows Server 2022 |
-| _AzSHOST1_       | HCI node                            | Yes           | _HCIBox-Client_ | Azure Local     |
-| _AzSHOST2_       | HCI node                            | Yes           | _HCIBox-Client_ | Azure Local     |
+| _HCIBox-Client_  | Primary host                        | No            | Azure           | Windows Server 2025 |
+| _AzSHOST1_       | Azure Local machine                            | Yes           | _HCIBox-Client_ | Azure Local     |
+| _AzSHOST2_       | Azure Local machine                            | Yes           | _HCIBox-Client_ | Azure Local     |
 | _AzSMGMT_        | Nested hypervisor                   | No            | _HCIBox-Client_ | Windows Server 2022 |
 | _JumpstartDC_    | Domain controller                   | Yes (DC)      | _AzSMGMT_       | Windows Server 2022 |
 | _Vm-Router_      | Remote Access Server                | No            | _AzSMGMT_       | Windows Server 2022 |