Merge pull request #260788 from EdB-MSFT/install-vminsights-2

updated

Author: v-ccolin

articles/azure-monitor/vm/vminsights-enable-powershell.md

@@ -5,7 +5,7 @@ ms.topic: conceptual
 ms.custom: devx-track-azurepowershell
 author: guywi-ms
 ms.author: guywild
-ms.date: 11/28/2023
+ms.date: 12/13/2023
 ---
 
 # Enable VM insights by using PowerShell
@@ -14,7 +14,7 @@ This article describes how to enable VM insights on Azure virtual machines by us
 - Azure Virtual Machines
 - Azure Virtual Machine Scale Sets
 
-This script installs VM extensions for Log Analytics/Azure Monitoring Agent (AMA) and Dependency Agent if needed for VM Insights. If AMA is onboarded, a Data Collection Rule (DCR) and a User Assigned Managed Identity (UAMI) is also associated with the virtual machines and virtual machine scale sets. 
+This script installs VM extensions for Log Analytics/Azure Monitoring Agent (AMA) and, if necessary, the Dependency Agent to enable VM Insights. If AMA is onboarded, a Data Collection Rule (DCR) and a User Assigned Managed Identity (UAMI) is also associated with the virtual machines and virtual machine scale sets.
 
 [!INCLUDE [Log Analytics agent deprecation](../../../includes/log-analytics-agent-deprecation.md)]
 
@@ -31,51 +31,60 @@ You need to:
 To enable VM insights for multiple VMs or virtual machine scale set, use the PowerShell script [Install-VMInsights.ps1](https://www.powershellgallery.com/packages/Install-VMInsights). The script is available from the Azure PowerShell Gallery. This script iterates through the virtual machines or virtual machine scale sets according to the parameters that you specify. The script can be used to enable VM insights for:
 
 - Every virtual machine and virtual machine scale set in your subscription.
-- The scoped resource group that's specified by `-ResourceGroup`.
-- A single VM or virtual machine scale set that's specified by `-Name`.
+- The scoped resource groups specified by `-ResourceGroup`.
+- A VM or virtual machine scale set specified by `-Name`.
+ You can specify multiple resource groups, VMs, or scale sets by using wildcards.
 
 
-Verify that you're using Az PowerShell module version 1.0.0 or later with `Enable-AzureRM` compatibility aliases enabled. Run `Get-Module -ListAvailable Az` to find the version. If you need to upgrade, see [Install Azure PowerShell module](/powershell/azure/install-azure-powershell). If you're running PowerShell locally, you also need to run `Connect-AzAccount` to create a connection with Azure.
+Verify that you're using Az PowerShell module version 1.0.0 or later with `Enable-AzureRM` compatibility aliases enabled. Run `Get-Module -ListAvailable Az` to find the version. To upgrade, see [Install Azure PowerShell module](/powershell/azure/install-azure-powershell). If you're running PowerShell locally, run `Connect-AzAccount` to create a connection with Azure.
 
 For a list of the script's argument details and example usage, run `Get-Help`.
 
 ```powershell
 Get-Help Install-VMInsights.ps1 -Detailed
 ```
 
-Use the script to enable VM insights using Azure Monitoring Agent and  Dependency Agent, or Log Analytics Agent.
+Use the script to enable VM insights using Azure Monitoring Agent and Dependency Agent, or Log Analytics Agent.
 
 
 
 ### [Azure Monitor Agent](#tab/AMA)
 
-When you enable VM insights using Azure Monitor Agent, the script associates a Data Collection Rule (DCR) and a User Assigned Managed Identity (UAMI) to the VM/VMSS, and passes the UAMI settings to the Azure Monitor Agent extension.   
+When you enable VM insights using Azure Monitor Agent, the script associates a Data Collection Rule (DCR) and a User Assigned Managed Identity (UAMI) to the VM/Virtual Machine Scale Set. The UAMI settings are passed to the Azure Monitor Agent extension.   
 
 ```powershell
 Install-VMInsights.ps1 -SubscriptionId <SubscriptionId> `
 [-ResourceGroup <ResourceGroup>] `
 [-ProcessAndDependencies ] `
-[-Name <MV or VMSS name>] `
+[-Name <VM or Virtual Machine Scale Set name>] `
 -DcrResourceId <DataCollectionRuleResourceId> `
 -UserAssignedManagedIdentityName <UserAssignedIdentityName> `
 -UserAssignedManagedIdentityResourceGroup <UserAssignedIdentityResourceGroup> 
 
 ```
 
 Required Arguments:   
- +   `-SubscriptionId <String>`  Azure subscription ID.  
- +   `-DcrResourceId <String> `  Data Collection Rule (DCR) Azure resource ID identifier. 
- +  `-UserAssignedManagedIdentityResourceGroup <String> `  Name of User Assigned Managed Identity (UAMI) resource group.   
- +   `-UserAssignedManagedIdentityName <String> `  Name of User Assigned Managed Identity (UAMI). 
++  `-SubscriptionId <String>`  Azure subscription ID.  
++  `-DcrResourceId <String> `  Data Collection Rule (DCR) Azure resource ID identifier. You can specify DCRs from different subscriptions to the VMs or virtual machine scale sets being enabled with Vm-Insights.
++  `-UserAssignedManagedIdentityResourceGroup <String> `  Name of User Assigned Managed Identity (UAMI) resource group.   
++  `-UserAssignedManagedIdentityName <String> `  Name of User Assigned Managed Identity (UAMI).  
+
 
 Optional Arguments:   
- +   `-ProcessAndDependencies` Set this flag to onboard the Dependency Agent with Azure Monitoring Agent (AMA) settings.  If not specified, only Azure Monitoring Agent (AMA) will be onboarded.  
- + ` - Name <String>`   Name of the VM or VMSS to be onboarded. If not specified, all VMs and VMSS in the subscription or resource group will be onboarded.
- +    `- ResourceGroup <String>`  Name of the resource group containing the VM or VMSS to be onboarded. If not specified, all VMs and VMSS in the subscription will be onboarded.
++ `-ProcessAndDependencies` Set this flag to onboard the Dependency Agent with Azure Monitoring Agent (AMA) settings.  If not specified, only the Azure Monitoring Agent (AMA)  is onboarded.  
++ `-Name <String>` Name of the VM or Virtual Machine Scale Set to be onboarded. If not specified, all VMs and Virtual Machine Scale Set in the subscription or resource group are onboarded. Use wildcards to specify multiple VMs or Virtual Machine Scale Sets.
++ `-ResourceGroup <String>` Name of the resource group containing the VM or Virtual Machine Scale Set to be onboarded. If not specified, all VMs and Virtual Machine Scale Set in the subscription are onboarded. Use wildcards to specify multiple resource groups.
++ `-PolicyAssignmentName <String>` Only include VMs associated with this policy.   When the PolicyAssignmentName parameter is specified, the VMs part of the parameter SubscriptionId are considered. 
++ `-TriggerVmssManualVMUpdate [<SwitchParameter>]` Trigger the update of VM instances in a scale set whose upgrade policy is set to Manual. 
++ `-WhatIf [<SwitchParameter>]` Get info about expected effect of the commands in the script.         
++ `-Confirm [<SwitchParameter>]` Confirm each action in the script. 
++ `-Approve [<SwitchParameter>]` Provide the approval for the installation to start with no confirmation prompt for the listed VM's/Virtual Machine Scale Sets. 
+ 
+The script supports wildcards for `-Name` and `-ResourceGroup`. For example, `-Name vm*` enables VM insights for all VMs and Virtual Machine Scale Sets that start with "vm". For more information, see [Wildcards in Windows PowerShell](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wildcards). 
 
 Example:
 ```azurepowershell
-Install-VMInsights.ps1  -SubscriptionId 12345678-abcd-abcd-1234-12345678 `
+Install-VMInsights.ps1 -SubscriptionId 12345678-abcd-abcd-1234-12345678 `
 -ResourceGroup rg-AMAPowershell  `
 -ProcessAndDependencies  `
 -Name vmAMAPowershellWindows `
@@ -89,10 +98,10 @@ The output has the following format:
 ```powershell
 Name                                     Account                               SubscriptionName                      Environment                          TenantId
 ----                                     -------                               ----------------                      -----------                          --------
-AzMon001  12345678-abcd-123…             MSI@9876                              AzMon001                              AzureCloud                           abcd1234-9876-abcd-1234-1234abcd5648
+AzMon001 12345678-abcd-123…              MSI@9876                              AzMon001                              AzureCloud                           abcd1234-9876-abcd-1234-1234abcd5648
 
 Getting list of VMs or VM Scale Sets matching specified criteria.
-VMs and VMSS matching selection criteria :
+VMs and Virtual Machine Scale Sets matching selection criteria :
 
 ResourceGroup : rg-AMAPowershell
   vmAMAPowershellWindows
@@ -125,6 +134,40 @@ VMSS Instance Upgrade Failures : 0
 
 ### [Log Analytics Agent](#tab/LogAnalyticsAgent)
 
+
+Required Arguments:
++ `-WorkspaceId <String>` Log Analytics WorkspaceID (GUID). 
++ `-WorkspaceKey <String>` Log Analytics Workspace primary or secondary key. 
+
+Optional Arguments:   
++ `-ReInstall [<SwitchParameter>]` Trigger removal of existing Log analytics extension and reinstallation to migrate log analytics workspaces with Legacy Agent (Linux) - OMSAgent. 
++ `-Name <String>` Name of the VM or Virtual Machine Scale Set to be onboarded. If not specified, all VMs and Virtual Machine Scale Sets in the subscription or resource group are onboarded. Use wildcards to specify multiple VMs or Virtual Machine Scale Sets.
++ `- ResourceGroup <String>` Name of the resource group containing the VM or Virtual Machine Scale Set to be onboarded. If not specified, all VMs and Virtual Machine Scale Sets in the subscription are onboarded. Use wildcards to specify multiple resource groups.
++ `-PolicyAssignmentName <String>` Only include VMs associated with this policy. When the PolicyAssignmentName parameter is specified, the VMs part of the parameter SubscriptionId are considered. 
++ `-TriggerVmssManualVMUpdate [<SwitchParameter>]` Trigger the update of VM instances in a scale set whose upgrade policy is set to Manual. 
++ `-WhatIf [<SwitchParameter>]` Get info about expected effect of the commands in the script.         
++ `-Confirm [<SwitchParameter>]` Confirm each action in the script. 
++ `-Approve [<SwitchParameter>]` Provide the approval for the installation to start with no confirmation prompt for the listed VM's/Virtual Machine Scale Sets. 
+ 
+The script supports wildcards for `-Name` and `-ResourceGroup`. For example, `-Name vm*` enables VM insights for all VMs and Virtual Machine Scale Sets that start with "vm". For more information, see [Wildcards in Windows PowerShell](https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_wildcards). 
+
+
+Example:
+
+```powershell
+Install-VMInsights.ps1 -WorkspaceId \<WorkspaceId\> `
+-WorkspaceKey \<WorkspaceKey\> `
+-SubscriptionId \<SubscriptionId\> `
+-ResourceGroup \<ResourceGroup\>   
+
+Install-VMInsights.ps1 -WorkspaceId \<WorkspaceId\> `
+-WorkspaceKey \<WorkspaceKey\> `
+-SubscriptionId \<SubscriptionId\> `
+-ResourceGroup \<ResourceGroup\> `
+-ReInstall 
+```     
+
+
 Use the following command to enable VM insights using Log Analytics Agent and Dependency Agent.
 
 
@@ -184,7 +227,7 @@ Failed: (0)
 
 ---
 
-Check your VM/VMSS in Azure portal to see if the extensions are installed or use the following command:
+Check your VM/Virtual Machine Scale Set in Azure portal to see if the extensions are installed or use the following command:
 
 ```powershell