Rediger

Del via

Enable Azure VM extensions by using Azure PowerShell

  • Artikkel

This article explains how to deploy, update, and uninstall Azure virtual machine (VM) extensions supported by Azure Arc-enabled servers. It shows you how to perform these tasks on a Linux or Windows hybrid machine by using Azure PowerShell.

Note

Azure Arc-enabled servers doesn't support deploying and managing VM extensions to Azure virtual machines. For Azure VMs, see the VM extension overview article.

Prerequisites

  • A computer with Azure PowerShell. For instructions, see Install and configure Azure PowerShell.

  • The Az.ConnectedMachine module. Before you use Azure PowerShell to manage VM extensions on your hybrid server managed by Azure Arc-enabled servers, you need to install this module.

    You can perform these management operations from your workstation. You don't need to run them on the Azure Arc-enabled server.

    Run the following command on your Azure Arc-enabled server:

    Install-Module -Name Az.ConnectedMachine.

    When the installation finishes, it returns the following message:

    The installed extension 'Az.ConnectedMachine' is experimental and not covered by customer support. Please use with discretion.

Enable an extension

To enable a VM extension on your Azure Arc-enabled server, use New-AzConnectedMachineExtension with the -Name, -ResourceGroupName, -MachineName, -Location, -Publisher, -ExtensionType, and -Settings parameters.

The following example enables the Custom Script Extension on an Azure Arc-enabled server:

$Setting = @{ "commandToExecute" = "powershell.exe -c Get-Process" }
New-AzConnectedMachineExtension -Name "custom" -ResourceGroupName "myResourceGroup" -MachineName "myMachineName" -Location "regionName" -Publisher "Microsoft.Compute"  -Settings $Setting -ExtensionType CustomScriptExtension

The following example enables the Microsoft Antimalware extension on an Azure Arc-enabled Windows server:

$Setting = @{ "AntimalwareEnabled" = $true }
New-AzConnectedMachineExtension -Name "IaaSAntimalware" -ResourceGroupName "myResourceGroup" -MachineName "myMachineName" -Location "regionName" -Publisher "Microsoft.Azure.Security" -Settings $Setting -ExtensionType "IaaSAntimalware"

Key Vault VM extension

Warning

Adding \ to " in the settings.json file will cause akvvm_service to fail with the following error: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Although PowerShell users commonly use the \" sequence to escape quotation marks in other code blocks, you should avoid that formatting in the settings.json file.

The following example enables the Key Vault VM extension on an Azure Arc-enabled server:

# Build settings
    $settings = @{
      secretsManagementSettings = @{
       observedCertificates = @(
        "observedCert1"
       )
      certificateStoreLocation = "myMachineName" # For Linux use "/var/lib/waagent/Microsoft.Azure.KeyVault.Store/"
      certificateStore = "myCertificateStoreName"
      pollingIntervalInS = "pollingInterval"
      }
    authenticationSettings = @{
     msiEndpoint = "http://localhost:40342/metadata/identity"
     }
    }

    $resourceGroup = "resourceGroupName"
    $machineName = "myMachineName"
    $location = "regionName"

    # Start the deployment
    New-AzConnectedMachineExtension -ResourceGroupName $resourceGroup -Location $location -MachineName $machineName -Name "KeyVaultForWindows or KeyVaultforLinux" -Publisher "Microsoft.Azure.KeyVault" -ExtensionType "KeyVaultforWindows or KeyVaultforLinux" -Setting $settings

Datadog VM extension

The following example enables the Datadog VM extension on an Azure Arc-enabled server:

$resourceGroup = "resourceGroupName"
$machineName = "machineName"
$location = "machineRegion"
$osType = "Windows" # change to Linux if appropriate
$settings = @{
    # change to your preferred Datadog site
    site = "us3.datadoghq.com"
}
$protectedSettings = @{
    # change to your Datadog API key
    api_key = "APIKEY"
}

New-AzConnectedMachineExtension -ResourceGroupName $resourceGroup -Location $location -MachineName $machineName -Name "Datadog$($osType)Agent" -Publisher "Datadog.Agent" -ExtensionType "Datadog$($osType)Agent" -Setting $settings -ProtectedSetting $protectedSettings

List extensions installed

To get a list of the VM extensions on your Azure Arc-enabled server, use Get-AzConnectedMachineExtension with the -MachineName and -ResourceGroupName parameters.

Here's an example:

Get-AzConnectedMachineExtension -ResourceGroupName myResourceGroup -MachineName myMachineName

Name    Location  PropertiesType        ProvisioningState
----    --------  --------------        -----------------
custom  westus2   CustomScriptExtension Succeeded

Update an extension configuration

To reconfigure an installed extension, you can use the Update-AzConnectedMachineExtension cmdlet with the -Name, -MachineName, -ResourceGroupName, and -Settings parameters.

To understand the methods for providing the changes that you want to the extension, refer to the reference article for the cmdlet.

Upgrade extensions

When a new version of a supported VM extension is released, you can upgrade it to that latest release. To upgrade a VM extension, use Update-AzConnectedExtension with the -MachineName, -ResourceGroupName, and -ExtensionTarget parameters.

For the -ExtensionTarget parameter, you need to specify the extension and the latest version available. To determine the latest version available for an extension, go to the Extensions page for the selected Azure Arc-enabled server in the Azure portal or run Get-AzVMExtensionImage. You can specify multiple extensions in a single upgrade request by providing both:

  • A comma-separated list of extensions, defined by their publisher and type (separated by a period)
  • The target version for each extension

You can review the version of installed VM extensions at any time by running the command Get-AzConnectedMachineExtension. The TypeHandlerVersion property value represents the version of the extension.

Remove extensions

To remove an installed VM extension on your Azure Arc-enabled server, use Remove-AzConnectedMachineExtension with the -Name, -MachineName, and -ResourceGroupName parameters.

Related content