Merge pull request #10422 from chrisjlin/patch-7

MCC-E doc updates

windows/deployment/do/mcc-ent-deploy-to-linux.md

@@ -26,6 +26,10 @@ Before deploying Connected Cache to a Linux host machine, ensure that the host m
 1. Within the Azure portal, navigate to the **Provisioning** tab of your cache node and copy the provisioning command.
 1. Download the provisioning package using the option at the top of the Cache Node Configuration page and extract the package onto the host machine.
 1. Open a command line window *as administrator* on the host machine, then change directory to the extracted provisioning package.
+
+    >[!Note]
+    >* If you are deploying your cache node to a Linux host machine that uses a TLS-inspecting proxy (e.g. ZScaler), ensure that you've [configured the proxy settings](mcc-ent-create-resource-and-cache.md#proxy-settings) for your cache node, then place the proxy certificate file (.pem) in the extracted provisioning package directory and add `proxyTlsCertificatePath="/path/to/pem/file"` to the provisioning command.
+
 1. Set access permissions to allow the `provisionmcc.sh` script within the provisioning package directory to execute.
 1. Run the provisioning command on the host machine.
 
@@ -42,6 +46,10 @@ To deploy a cache node programmatically, you'll need to use Azure CLI to get the
 1. Save the resulting output. These values will be passed as parameters within the provisioning command.
 1. Download and extract the [Connected Cache provisioning package for Linux](https://aka.ms/MCC-Ent-InstallScript-Linux) to your host machine.
 1. Open a command line window *as administrator* on the host machine, then change directory to the extracted provisioning package.
+
+    >[!Note]
+    >* If you are deploying your cache node to a host machine that uses a TLS-inspecting proxy (e.g. ZScaler), ensure that you've [configured the proxy settings](mcc-ent-create-resource-and-cache.md#proxy-settings) for your cache node, then place the proxy certificate file (.pem) in the extracted provisioning package directory and add `proxyTlsCertificatePath="/path/to/pem/file"` to the provisioning command.
+
 1. Set access permissions to allow the `provisionmcc.sh` script within the provisioning package directory to execute.
 1. Replace the values in the following provisioning command before running it on the host machine.
 

windows/deployment/do/mcc-ent-deploy-to-windows.md

@@ -17,7 +17,7 @@ appliesto:
 
 This article describes how to deploy Microsoft Connected Cache for Enterprise and Education caching software to a Windows host machine.
 
-Deploying Connected Cache to a Windows host machine requires designating a [Group Managed Service Account (gMSA)](/windows-server/security/group-managed-service-accounts/getting-started-with-group-managed-service-accounts) or a [Local User Account](https://support.microsoft.com/windows/create-a-local-user-or-administrator-account-in-windows-20de74e0-ac7f-3502-a866-32915af2a34d) as the Connected Cache runtime account. This prevents tampering with the Connected Cache container and the cached content on the host machine.
+Deploying Connected Cache to a Windows host machine requires designating a [Group Managed Service Account (gMSA)](/windows-server/security/group-managed-service-accounts/getting-started-with-group-managed-service-accounts) or a [local user account](https://support.microsoft.com/topic/20de74e0-ac7f-3502-a866-32915af2a34d) as the Connected Cache runtime account. This prevents tampering with the Connected Cache container and the cached content on the host machine.
 
 Before deploying Connected Cache to a Windows host machine, ensure that the host machine meets all [requirements](mcc-ent-prerequisites.md), and that you have [created and configured your Connected Cache Azure resource](mcc-ent-create-resource-and-cache.md).
 
@@ -26,14 +26,25 @@ Before deploying Connected Cache to a Windows host machine, ensure that the host
 # [Azure portal](#tab/portal)
 
 1. Within the Azure portal, navigate to the **Provisioning** tab of your cache node and copy the provisioning command.
-1. Download the provisioning package using the option at the top of the Cache Node Configuration page and extract the package onto the host machine. **Note**: The installer should be in a folder that isn't synced to OneDrive, as this will interfere with the installation process.
+1. Download the provisioning package using the option at the top of the Cache Node Configuration page and extract the archive onto the host machine.
+
+   >[!Note]
+   >* The provisioning package should be extracted to a directory that isn't synced to OneDrive, as the sychronization process will interfere with the installation. It is recommended to extract the provisioning package to the root directory of the host machine (e.g. C:\mccInstaller)
+
 1. Open a PowerShell window *as administrator* on the host machine, then change directory to the extracted provisioning package.
+
+   >[!Note]
+   >* If you are deploying your cache node to a Windows host machine that uses a TLS-inspecting proxy (e.g. ZScaler), ensure that you've [configured the proxy settings](mcc-ent-create-resource-and-cache.md#proxy-settings) for your cache node, then place the proxy certificate file (.pem) in the extracted provisioning package directory and add `-proxyTlsCertificatePemFileName "mycert.pem"` to the provisioning command.
+
 1. Set the Execution Policy to *Unrestricted* to allow the provisioning scripts to run.
-1. Create a `$User` environment variable containing the username of the account you intend to designate as the Connected Cache runtime account. 
+1. Create a `$User` PowerShell variable containing the username of the account you intend to designate as the Connected Cache runtime account.
 
-    For gMSAs, the value should be formatted as `"Domain\Username$"`. For Local User accounts, `$User` should be formatted as `"LocalMachineName\Username"`.
+    For gMSAs, the `$User` PowerShell variable should be formatted as `"Domain\Username$"`. For local user accounts, `$User` PowerShell variable should be formatted as `"LocalMachineName\Username"`.
 
-   If you're using a Local User account as the Connected Cache runtime account, you'll also need to create a [PSCredential Object](/dotnet/api/system.management.automation.pscredential) named `$myLocalAccountCredential`. **Note**: You'll need to apply a local security policy to permit the Local User account to `Log on as a batch job`.
+   If you're using a local user account as the Connected Cache runtime account, you'll also need to create a [PSCredential Object](/dotnet/api/system.management.automation.pscredential) named `$myLocalAccountCredential`.
+
+   >[!Note]
+   >* You'll need to apply a local security policy to permit the local user account to `Log on as a batch job`.
 
 1. Run the provisioning command on the host machine.
 
@@ -48,16 +59,27 @@ To deploy a cache node programmatically, you'll need to use Azure CLI to get the
    ```
 
 1. Save the resulting output. These values will be passed as parameters within the provisioning command.
-1. Download and extract the [Connected Cache provisioning package for Windows](https://aka.ms/MCC-Ent-InstallScript-WSL) to your host machine. **Note**: The installer should be in a folder that isn't synced to OneDrive, as this will interfere with the installation process.
+1. Download and extract the [Connected Cache provisioning package for Windows](https://aka.ms/MCC-Ent-InstallScript-WSL) to your host machine.
+
+   >[!Note]
+   >* The provisioning package should be extracted to a directory that isn't synced to OneDrive, as the sychronization process will interfere with the installation. It is recommended to extract the provisioning package to the root directory of the host machine (e.g. C:\mccInstaller)
+
 1. Open a PowerShell window *as administrator* on the host machine, then change directory to the extracted provisioning package.
+
+   >[!Note]
+   >* If you are deploying your cache node to a host machine that uses a TLS-inspecting proxy (e.g. ZScaler), ensure that you've [configured the proxy settings](mcc-ent-create-resource-and-cache.md#proxy-settings) for your cache node, then place the proxy certificate file (.pem) in the extracted provisioning package directory and add `-proxyTlsCertificatePath "path/to/pem/file"` to the provisioning command.
+
 1. Set the Execution Policy to *Unrestricted* to allow the provisioning scripts to run.
-1. Create a `$User` environment variable containing the username of the account you intend to designate as the Connected Cache runtime account. 
+1. Create a `$User` PowerShell variable containing the username of the account you intend to designate as the Connected Cache runtime account.
 
-    For gMSAs, the value should be formatted as `"Domain\Username$"`. For Local User accounts, `$User` should be formatted as `"LocalMachineName\Username"`.
+    For gMSAs, the `$User` PowerShell variable should be formatted as `"Domain\Username$"`. For local user accounts, the `$User` PowerShell variable should be formatted as `"LocalMachineName\Username"`.
 
-   If you're using a Local User account as the Connected Cache runtime account, you'll also need to create a [PSCredential Object](/dotnet/api/system.management.automation.pscredential) named `$myLocalAccountCredential`. **Note**: You'll need to apply a local security policy to permit the Local User account to `Log on as a batch job`.
+   If you're using a local user account as the Connected Cache runtime account, you'll also need to create a [PSCredential Object](/dotnet/api/system.management.automation.pscredential) named `$myLocalAccountCredential`.
 
-1. Replace the values in the following provisioning command before running it on the host machine. **Note**:  `-mccLocalAccountCredential $myLocalAccountCredential` is only needed if you're using a Local User account as the Connected Cache runtime account.
+   >[!Note]
+   >* You'll need to apply a local security policy to permit the local user account to `Log on as a batch job`.
+
+1. Replace the values in the following provisioning command before running it on the host machine.
 
    ```powershell-interactive
    ./provisionmcconwsl.ps1 -installationFolder c:\mccwsl01 -customerid [enter mccResourceId here] -cachenodeid [enter cacheNodeId here] -customerkey [enter customerKey here] -registrationkey [enter registration key] -cacheDrives "/var/mcc,enter drive size"  -shouldUseProxy [enter true if present, enter false if not] -proxyurl "http://[enter proxy host name]:[enter port]"  -mccRunTimeAccount $User -mccLocalAccountCredential $myLocalAccountCredential

windows/deployment/do/mcc-ent-monitoring.md

@@ -18,25 +18,25 @@ ms.date: 10/30/2024
 
 Tracking the status and performance of your Connected Cache node is essential to making sure you're getting the most out of the service.
 
-For basic monitoring, navigate to the **Overview** tab. Here you'll be able to view a collection of predefined metrics and charts. All the monitoring in this section will function right after your Connected Cache node has been deployed.
+For basic monitoring, navigate to the **Overview** tab. Here you can view a collection of predefined metrics and charts. All the monitoring in this section will function right after your Connected Cache node has been deployed. You can view more details about each cache node by navigating to the **Cache Nodes** section under the **Cache Node Management** tab. This page displays cache node information such as Status, Host machine OS, Software Version, and Cache Node ID.
 
-For advanced monitoring, navigate to the **Metrics** section under the **Monitoring** tab. Here you'll be able to access more sampled metrics (hits, misses, inbound traffic) and specify different aggregations (count, avg, min, max, sum). You can then use this data to create customized charts and configure alerts.
+For advanced monitoring, navigate to the **Metrics** section under the **Monitoring** tab. Here you can access more sampled metrics (hits, misses, inbound traffic) and specify different aggregations (count, avg, min, max, sum). You can then use this data to create customized charts and configure alerts.
 
-Between the two monitoring sections, you'll be able to gather essential insights into the health, performance, and efficiency of your Connected Cache nodes.
+Using the two monitoring sections, you can gather essential insights into the health, performance, and efficiency of your Connected Cache nodes.
 
 ## Basic Monitoring
 
 ### Cache node summary
 
-Below are the metrics you'll find in the **Cache Node Summary** dashboard, along with their descriptions. This dashboard only reflects data received from cache nodes in the last 24 hours.
+Below are the metrics found in the **Cache Node Summary** dashboard, along with their descriptions. This dashboard only reflects data received from cache nodes in the last 24 hours.
 
 ![Screenshot of cache node summary in the Azure portal interface.](../images/mcc-ent-cache-node-summary.png)
 
 | Metric | Description |
 | --- | --- |
-| Healthy nodes | Your Connected Cache node will periodically send heartbeat messages to the Connected Cache service. If the Connected Cache service has received a heartbeat message from your Connected Cache node in the last 24 hours, the node will be labeled as healthy. |
-| Unhealthy nodes | If the Connected Cache service hasn't received a heartbeat message from your Connected Cache node in the last 24 hours, the node will be labeled as unhealthy. |
-| Max in | The maximum ingress in Megabits per second (Mbps) that your node has pulled from CDN endpoints in the last 24 hours. |
+| Healthy nodes | Your Connected Cache node will periodically send heartbeat messages to the Connected Cache service. If the Connected Cache service has received a heartbeat message from your Connected Cache node in the last 24 hours, the node is labeled as healthy. |
+| Unhealthy nodes | If the Connected Cache service hasn't received a heartbeat message from your Connected Cache node in the last 24 hours, the node is labeled as unhealthy. |
+| Max in | The maximum ingress in Megabits per second (Mbps) that your node has pulled from Content Delivery Network (CDN) endpoints in the last 24 hours. |
 | Max out | The minimum egress in Mbps that your node has sent to Windows devices in its network over the last 24 hours. |
 | Average in | The average ingress in Mbps that your node has pulled from CDN endpoints in the last 24 hours. |
 | Average out | The average egress in Mbps that your node has sent to Windows devices in its network over the last 24 hours. |
@@ -65,6 +65,20 @@ This chart displays the volume of each supported content type in bytes (B) that
 
 The content types displayed in the chart each have a distinct color and are sorted in descending order of volume. The bar chart is stacked such that you can visually compare total volume being delivered at different points in time.
 
+### Cache node details
+
+The **Cache Nodes** section under the **Cache Node Management** tab displays cache node information such as Status, Host machine OS, Software Version, and Cache Node ID.
+
+![Screenshot of cache node details in the Azure portal interface.](../images/mcc-ent-cache-node-details.png)
+
+| Metric | Description |
+| --- | --- |
+| Cache node name | The user-defined name of the cache node. |
+| Status | The heartbeat status of the cache node. |
+| OS | The host machine OS that this cache node is compatible with. |
+| Software version | The version number of the cache node's Connected Cache container. |
+| Cache node ID | The unique identifier of the cache node. |
+
 ## Advanced Monitoring
 
 To expand upon the metrics shown in the Overview tab, navigate to the **Metrics** tab in the left side toolbar of Azure portal.
@@ -79,13 +93,13 @@ Listed below are the metrics you can access in this section:
 
 ### Customizable Dashboards
 
-Once you select the charts you would like to track, you can save them to a personalized dashboard. You can configure the chart title, filters, range, legend, and more. You can also use this personalized dashboard to set up alerts that will notify you if your Connected Cache node dips in performance.
+Once you select the charts you would like to track, you can save them to a personalized dashboard. You can configure the chart title, filters, range, legend, and more. You can also use this personalized dashboard to set up alerts that notify you if your Connected Cache node dips in performance.
 
 Some example scenarios where you would want to set up a custom alert:
 
 - My Connected Cache node is being shown as unhealthy and I want to know exactly when it stopped egressing last
 - A new Microsoft Word update was released last night and I want to know if my Connected Cache node is helping deliver this content to my Windows devices
 
-## Additional Metrics
+## Client-Side Metrics
 
 Your Connected Cache node can keep track of how much content has been sent to requesting Windows devices, but the node can't track whether the content was successfully received by the device. For more information on accessing client-side data from your Windows devices, see [Monitor Delivery Optimization](waas-delivery-optimization-monitor.md).

windows/deployment/do/mcc-ent-troubleshooting.md

@@ -19,6 +19,18 @@ ms.date: 10/30/2024
 
 This article contains instructions on how to troubleshoot different issues you may encounter while using Connected Cache. These issues are categorized by the task in which they may be encountered.
 
+## Known issues
+
+This section describes known issues with the latest release of Microsoft Connected Cache for Enterprise and Education. See the [Release Notes page](mcc-ent-release-notes.md) for more details on the fixes included in the latest release.
+
+### Cache node monitoring chart in the Azure portal user interface displays incorrect information
+
+### Script provisionmcconwsl.ps1 fails when executed on a Windows 11 host machine configured to use Japanese language
+
+In the Connected Cache installation script (provisionmcconwsl.ps1), the check processing is executed until the value of the last execution code (Last Result) of the installation task becomes 0 in the following processing. However, in Japanese OS, the return value is null because "Last Result" is displayed, and an exception occurs.
+
+As a temporary workaround, the above error doesn't occur by changing the language setting of the local administrator user from Japanese to English and then executing the script.
+
 ## Steps to obtain an Azure subscription ID
 
 <!--Using include file, get-azure-subscription.md, do/mcc-isp.md for shared content-->
@@ -38,7 +50,7 @@ If you're encountering a validation error, check that you have filled out all re
 
 If your configuration doesn't appear to be taking effect, check that you have selected the **Save** option at the top of the configuration page in the Azure portal user interface.
 
-If you have changed the proxy configuration, you will need to re-provision the Connected Cache software on the host machine for the proxy configuration to take effect.
+If you have changed the proxy configuration, you'll need to re-provision the Connected Cache software on the host machine for the proxy configuration to take effect.
 
 ## Troubleshooting cache nodes created during early preview
 
@@ -50,7 +62,7 @@ As such, we strongly recommend you [recreate your existing resources in Azure](m
 
 ### Collecting Windows-hosted installation logs
 
-[Deploying a Connected Cache node to a Windows host machine](mcc-ent-deploy-to-windows.md) involves running a series of PowerShell scripts contained within the Windows provisioning package. These scripts will attempt to write log files to the installation directory specified in the provisioning command (`C:\mccwsl01\InstallLogs` by default).
+[Deploying a Connected Cache node to a Windows host machine](mcc-ent-deploy-to-windows.md) involves running a series of PowerShell scripts contained within the Windows provisioning package. These scripts attempt to write log files to the installation directory specified in the provisioning command (`C:\mccwsl01\InstallLogs` by default).
 
 There are three types of installation log files:
 
@@ -60,9 +72,19 @@ There are three types of installation log files:
 
 The Registered Task Transcript is usually the most useful for diagnosing the installation issue.
 
-### WSL2 fails to install with message "A specified logon session does not exist"
+### Collecting other Windows-hosted logs
 
-If you are encountering this failure message when attempting to run the PowerShell command `wsl.exe --install --no-distribution` on your Windows host machine, verify that you are logged on as a local administrator and running the command from an elevated PowerShell window.
+Once the cache node has been successfully installed on the Windows host machine, it will periodically write log files to the installation directory (`C:\mccwsl01\` by default).
+
+You can expect to see the following types of log files:
+
+1. **WSL_Mcc_Monitor_FromRegisteredTask_Transcript**: This log file records the output of the "MCC_Monitor_Task" scheduled task that is responsible for ensuring that the Connected Cache continues running.
+1. **WSL_Mcc_UserUninstall_Transcript**: This log file records the output of the "uninstallmcconwsl.ps1" script that the user can run to uninstall MCC software from the host machine.
+1. **WSL_Mcc_Uninstall_FromRegisteredTask_Transcript**: This log file records the output of the "MCC_Uninstall_Task" scheduled task that is responsible for uninstalling the MCC software from the host machine when called by the "uninstallmcconwsl.ps1" script.
+
+### WSL2 fails to install with message "A specified logon session doesn't exist"
+
+If you're encountering this failure message when attempting to run the PowerShell command `wsl.exe --install --no-distribution` on your Windows host machine, verify that you're logged on as a local administrator and running the command from an elevated PowerShell window.
 
 ### Updating the WSL2 kernel
 
@@ -94,6 +116,20 @@ You can use Task Scheduler on the host machine to check the status of this sched
 > [!Note]
 > If the password of the runtime account changes, you'll need to update the user in all of the Connected Cache scheduled tasks in order for the Connected Cache node to continue functioning properly.
 
+### Cache node successfully deployed but not serving requests
+
+If your cache node isn't responding to requests outside of localhost, it may be because the host machine's port forwarding rules weren't correctly set during Connected Cache installation.
+
+To check your host machine's port forwarding rules, use the following PowerShell command.
+
+`netsh interface portproxy show v4tov4`
+
+If you don't see any port forwarding rules for port 80 to 0.0.0.0, you can run the following command from an elevated PowerShell instance to set the proper forwarding to WSL.
+
+`netsh interface portproxy add v4tov4 listenport=80 listenaddress=0.0.0.0 connectport=80 connectaddress=<WSL IP Address>`
+
+You can retrieve the WSL IP Address from the `wslip.txt` file that should be present in the installation directory you specified in the Connected Cache provisioning command ("c:\mccwsl01" by default).
+
 ## Troubleshooting cache node deployment to Linux host machine
 
 [Deploying a Connected Cache node to a Linux host machine](mcc-ent-deploy-to-linux.md) involves running a series of Bash scripts contained within the Linux provisioning package.
@@ -106,6 +142,31 @@ If it shows the **edgeAgent** and **edgeHub** containers but doesn't show **MCC*
 
 You can also reboot the IoT Edge runtime using `sudo systemctl restart iotedge`.
 
+## Generating cache node diagnostic support bundle
+
+You can generate a support bundle with detailed diagnostic information by running the `collectMccDiagnostics.sh` script included in the installation package.
+
+For Windows host machines, you'll need to do the following:
+
+1. Launch a PowerShell process as the account specified as the runtime account during the Connected Cache install
+1. Change directory to the "MccScripts" directory within the extracted Connected Cache provisioning package and verify the presence of `collectmccdiagnostics.sh`
+1. Run `wsl bash collectmccdiagnostics.sh` to generate the diagnostic support bundle
+1. Once the script has completed, note the console output describing the location of the diagnostic support bundle
+
+    For example, "Successfully zipped package, please send file created at /etc/mccdiagnostics/support_bundle_2024_12_03__11_05_39__AM.tar.gz"
+
+1. Run the `wsl cp` command to copy the support bundle from the location within the Ubuntu distribution to the Windows host OS
+
+    For example, `wsl cp /etc/mccdiagnostics/support_bundle_2024_12_03__11_05_39__AM.tar.gz /mnt/c/mccwsl01/SupportBundles`
+
+For Linux host machines, you'll need to do the following:
+
+1. Change directory to the "MccScripts" directory within the extracted Connected Cache provisioning package and verify the presence of `collectmccdiagnostics.sh`
+1. Run `collectmccdiagnostics.sh` to generate the diagnostic support bundle
+1. Once the script has completed, note the console output describing the location of the diagnostic support bundle
+
+    For example, "Successfully zipped package, please send file created at /etc/mccdiagnostics/support_bundle_2024_12_03__11_05_39__AM.tar.gz"
+
 ## Troubleshooting cache node monitoring
 
 Connected Cache node status and performance can be [monitored using the Azure portal user interface](mcc-ent-monitoring.md).
@@ -116,4 +177,4 @@ If the issue persists, check that you have configured the Timespan and Cache nod
 
 ## Diagnose and Solve
 
-You can also use the **Diagnose and solve problems** functionality provided by the Azure portal interface. This tab within the Microsoft Connected Cache Azure resource will walk you through a few prompts to help narrow down the solution to your issue.
+You can also use the **Diagnose and solve problems** functionality provided by the Azure portal interface. This tab within the Microsoft Connected Cache Azure resource walks you through a few prompts to help narrow down the solution to your issue.