How to install and configure Microsoft Monitoring Agent for use with OMS Gateway (Proxy) using PowerShell

Question

How can you use Powershell to install and configure the Microsoft Monitoring Agent (MMA) for use with the OMS Gateway ? None of the automated examples tell you how to accomplish this for use with an OMS Gateway.

I found this as a walk-through to do this manually: http://azurepost.com/oms-gateway-ga-installation-configuration-walkthrough/

and this: https://learn.microsoft.com/en-us/azure/azure-monitor/platform/gateway

Automating:

this one is for ARM templates, but does not support OMS Gateway: Enabling the Microsoft Monitoring Agent in Windows JSON Templates

this one for Powershell, but does not support OMS Gateway oms-windows.md

None of the automated examples tell you how to accomplish this for use with an OMS Gateway. In fact from the documentation at Property values it appears to not be possible. Only properties documented are workspaceId and workspaceKey. No other properties (ie proxy, userid, password) needed for OMS Gateway configuration are listed.

Answer 1

Solution: To deploy and configure the MMA for use with OMS Gateway via ARM or PS. These properties work with ARM as well as PS. PS usually builds ARM template under the hood. The full set of properties are:

Documented Extension Properties

• workspaceId
• workspaceKey

Undocumented Extension Properties

Control Panel;Microsoft Monitoring Agent app to determine what most of these values mean.

• enableAutomaticManagement: equivalent to "Tab: 'Operations Manager', Automatic update management group assignments for AD DS"

• proxyUri: equivalent to "Tab: 'Proxy Settings', Proxy Server"

• proxyUser: equivalent to "Tab: 'Proxy Settings', Username"
• proxyPassword: #equivalent to "Tab: 'Proxy Settings', Password"

• azureRegionId: Not sure, but I think it may be related to Log Analytics being in a different region. Use Get-AzureRMLocation, Location to determine valid values

• stopOnMultipleConnections : ???

• azureResourceId: ???

Deploy via Powershell:

Import-Module Az.Compute
Connect-AzAccount 
Set-AzContext -Subscription  $subscriptionId

$settings = @{ `
    "workspaceId" = $workspaceId; `
    "proxyUri" = $proxyUri; `
    "azureRegionId" = $azureRegionId `
}
$protectedSettings = @{"workspaceKey" = $workspaceKey}

$extensions = Get-AzVMExtension `
    -ResourceGroupName $resourceGroupName `
    -VMName $vmName 

#If extension was already installed and the ExtensionName is not 'MicrosoftMonitoringAgent',
#re-install will fail. Therefore, we need to remove extension before proceeding.
foreach($extension in $extensions)
{
    if ($extension.ExtensionType -eq "MicrosoftMonitoringAgent")
    {
        Remove-AzVMExtension `
            -ResourceGroupName $resourceGroupName `
            -VMName $vmName `
            -Name $extension.Name `
            -Confirm:$false `
            -Force:$true
    }

}

#install MMA Extension
$guid = New-Guid 
Set-AzVMExtension `
    -ResourceGroupName $resourceGroupName `
    -VMName $vmName `
    -ExtensionType "MicrosoftMonitoringAgent" `
    -ExtensionName "MicrosoftMonitoringAgent" `
    -Publisher "Microsoft.EnterpriseCloud.Monitoring" `
    -TypeHandlerVersion 1.0 `
    -ForceRerun $guid `
    -Settings $settings `
    -ProtectedSettings $protectedSettings `
    -Location $azureRegionId 

Deploy via ARM Template

{
  "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "location": {
      "type": "string"
    },
    "serverName": {
      "type": "string"
    },
    "workspaceId": {
      "type": "string",
      //from the blob's etag property; changes each time update occurs
      "defaultValue": "guid-guid-guid-guid",
      "metadata": {
        "description": "To be provided from keyvault; equivalent to Tab: 'Azure Log Analytics (OMS)', Add or Edit Popup"
      }
    },
    "proxyUri": {
      "type": "string",
      "defaultValue": "101.102.103.104:8080",
      "metadata": {
        "description": "To be provided from keyvault; equivalent to Tab: 'Proxy Settings', Proxy Server"
      }
    },
    "workspaceKey": {
      "type": "securestring",
      "defaultValue": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==",
      "metadata": {
        "description": "To be provided from keyvault; equivalent to Tab: 'Azure Log Analytics (OMS)', Add or Edit Popup"
      }
    },

    "forceUpdateTag": {
      "defaultValue": "[newGuid()]",
      "type": "string",
      "metadata": {
        "description": "Forces extension to deploy every time."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "apiVersion": "2018-10-01",
      "name": "[concat(parameters('serverName'),'/MicrosoftMonitoringAgent')]",
      "location": "[parameters('location')]",
      "properties": {
        "publisher": "Microsoft.EnterpriseCloud.Monitoring",
        "type": "MicrosoftMonitoringAgent",
        "typeHandlerVersion": "1.0",
        "autoUpgradeMinorVersion": "true",
        "forceUpdateTag": "[parameters('forceUpdateTag')]",
        "settings": {
          "workspaceId": "[parameters('workspaceId')]",
          "proxyUri": "[parameters('proxyUri')]",
          "azureRegionId": "[parameters('location')]"
        },
        "protectedSettings": {
          "workspaceKey": "[parameters('workspaceKey')]"
        }
      }
    }
  ]
}

(please somebody tell me I wasted my time and there is a "Interogate Extension" powershell command somewhere...) How did I figure this out ? I used the portal to deploy the MMA Extension. I went to the VM and found the installed extension at : C:\Packages\Plugins\Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent

I decompiled: Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent.ExtensionShared.dll and looked for the exact strings: workspaceId and workspaceKey. I found the classes: MMAExtensionPublicSettings, MMAExtensionProtectedSettings. These classes contain the valid Extension properties.

using Newtonsoft.Json;
using System;
using System.Runtime.CompilerServices;

namespace Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent.Extension.MMADataModels
{
    public class MMAExtensionPublicSettings
    {
        [JsonProperty(PropertyName = "azureRegionId")]
        public string AzureRegionId{ get; set; }

        [JsonProperty(PropertyName = "azureResourceId")]
        public string AzureResourceId { get; set; }

        [JsonProperty(PropertyName = "enableAutomaticManagement")]
        public bool EnableAutomaticManagement { get; set; }

        [JsonProperty(PropertyName = "proxyUri")]
        public string ProxyUri { get; set; }

        [JsonProperty(PropertyName = "proxyUser")]
        public string ProxyUser { get; set; }

        [JsonProperty(PropertyName = "stopOnMultipleConnections")]
        public bool StopOnMultipleConnections { get; set; }

        [JsonProperty(PropertyName = "workspaceId")]
        public string WorkspaceId { get; set; }
        public MMAExtensionPublicSettings()
        {
        }
    }
}

** - MMAExtensionProtectedSettings

using Newtonsoft.Json;
using System;
using System.Runtime.CompilerServices;    
namespace Microsoft.EnterpriseCloud.Monitoring.MicrosoftMonitoringAgent.Extension.MMADataModels
{
    public class MMAExtensionProtectedSettings
    {
        [JsonProperty(PropertyName="proxyPassword")]
        public string ProxyPassword
        {
            get;
            set;
        }

        [JsonProperty(PropertyName="workspaceKey")]
        public string WorkspaceKey
        {
            get;
            set;
        }

        public MMAExtensionProtectedSettings()
        {
        }
    }
}