Habilitar extensões de VM do Azure usando um modelo do ARM

Artigo
01/17/2025

Este artigo mostra como usar um modelo do ARM (Azure Resource Manager) para implantar extensões de VM (Máquina Virtual) do Azure, que têm o suporte dos servidores habilitados para Azure Arc.

Adicione extensões de VM a um modelo de ARM e execute-as com a implantação do modelo. Com as extensões de VM que têm suporte de servidores habilitados para Azure Arc, implante as extensões em computadores do Linux ou Windows usando o Azure PowerShell. Cada amostra que se segue inclui um arquivo de modelo e um arquivo de parâmetro com valores de amostra para fornecer ao modelo.

Observação

Embora você possa colocar em lote várias extensões e processá-las juntas, elas são instaladas em série. Depois que a primeira instalação da extensão for concluída, a próxima extensão será instalada.

Os servidores habilitados para Azure Arc não dão suporte à implantação e gerenciamento de extensões de VM em máquinas virtuais do Azure. Para VMs do Azure, confira o artigo Visão geral da extensão de VM.

Habilitar a extensão de VM do Log Analytics

Para implantar facilmente o agente do Log Analytics, use um dos exemplos a seguir para instalar o agente no Linux ou no Windows.

Arquivo de modelo para Linux

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "workspaceId": {
            "type": "string"
        },
        "workspaceKey": {
            "type": "string"
        }
    },
    "resources": [
        {
            "name": "[concat(parameters('vmName'),'/OMSAgentForLinux')]",
            "type": "Microsoft.HybridCompute/machines/extensions",
            "location": "[parameters('location')]",
            "apiVersion": "2022-03-10",
            "properties": {
                "publisher": "Microsoft.EnterpriseCloud.Monitoring",
                "type": "OmsAgentForLinux",
                "enableAutomaticUpgrade": true,
                "settings": {
                    "workspaceId": "[parameters('workspaceId')]"
                },
                "protectedSettings": {
                    "workspaceKey": "[parameters('workspaceKey')]"
                }
            }
        }
    ]
}

Arquivo de modelo para Windows

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "workspaceId": {
            "type": "string"
        },
        "workspaceKey": {
            "type": "string"
        }
    },
    "resources": [
        {
            "name": "[concat(parameters('vmName'),'/MicrosoftMonitoringAgent')]",
            "type": "Microsoft.HybridCompute/machines/extensions",
            "location": "[parameters('location')]",
            "apiVersion": "2022-03-10",
            "properties": {
                "publisher": "Microsoft.EnterpriseCloud.Monitoring",
                "type": "MicrosoftMonitoringAgent",
                "autoUpgradeMinorVersion": true,
                "enableAutomaticUpgrade": true,
                "settings": {
                    "workspaceId": "[parameters('workspaceId')]"
                },
                "protectedSettings": {
                    "workspaceKey": "[parameters('workspaceKey')]"
                }
            }
        }
    ]
}

Arquivo de parâmetros

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentParameters.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "value": "<vmName>"
        },
        "location": {
            "value": "<region>"
        },
        "workspaceId": {
            "value": "<MyWorkspaceID>"
        },
        "workspaceKey": {
            "value": "<MyWorkspaceKey>"
        }
    }
}

Salve o modelo e o arquivo de parâmetro no disco e edite o arquivo de parâmetro com os valores apropriados para implantação. Em seguida, você pode instalar a extensão em todos os computadores conectados em um grupo de recursos usando o comando a seguir. O comando usa o parâmetro TemplateFile para especificar o modelo e o parâmetro TemplateParameterFile para especificar um arquivo que contém parâmetros e valores de parâmetro.

New-AzResourceGroupDeployment -ResourceGroupName "ContosoEngineering" -TemplateFile "D:\Azure\Templates\LogAnalyticsAgent.json" -TemplateParameterFile "D:\Azure\Templates\LogAnalyticsAgentParms.json"

Aplicar a Extensão de Script Personalizado

Para usar a Extensão de Script Personalizado, execute um dos exemplos a seguir para Linux e Windows. Caso não esteja familiarizado com a Extensão de Script Personalizado, consulte Extensão de Script Personalizado para Linux ou Extensão de Script Personalizado para Windows. Há algumas características diferentes que você deverá entender ao usar essa extensão com computadores híbridos:

A lista de sistemas operacionais com suporte que têm a Extensão de Script Personalizado da VM do Azure não é aplicável aos servidores habilitados para Azure Arc. Consulte a lista de sistemas operacionais com suporte para servidores habilitados para Azure Arc.
Detalhes de configuração sobre conjuntos de dimensionamento de máquinas virtuais do Azure ou VMs criadas por meio do modelo de implantação clássico não são aplicáveis.
Se seus computadores precisarem baixar um script externamente e só puderem se comunicar por meio de um servidor proxy, você precisará configurar o agente do computador conectado para definir a variável de ambiente do servidor proxy.

A configuração de extensão de script personalizado especifica itens como localização de script e o comando a ser executado. Essa configuração é especificada nos modelos a seguir.

Arquivo de modelo para Linux

{
  "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vmName": {
      "type": "string"
    },
    "location": {
      "type": "string"
    },
    "fileUris": {
      "type": "array"
    },
    "commandToExecute": {
      "type": "securestring"
    }
  },
  "resources": [
    {
      "name": "[concat(parameters('vmName'),'/CustomScript')]",
      "type": "Microsoft.HybridCompute/machines/extensions",
      "location": "[parameters('location')]",
      "apiVersion": "2022-03-10",
      "properties": {
        "publisher": "Microsoft.Azure.Extensions",
        "type": "CustomScript",
        "autoUpgradeMinorVersion": true,
        "settings": {},
        "protectedSettings": {
          "commandToExecute": "[parameters('commandToExecute')]",
          "fileUris": "[parameters('fileUris')]"
        }
      }
    }
  ]
}

Arquivo de modelo para Windows

{
    "$schema": "http://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "fileUris": {
            "type": "string"
        },
        "arguments": {
            "type": "securestring",
            "defaultValue": " "
        }
    },
    "variables": {
        "UriFileNamePieces": "[split(parameters('fileUris'), '/')]",
        "firstFileNameString": "[variables('UriFileNamePieces')[sub(length(variables('UriFileNamePieces')), 1)]]",
        "firstFileNameBreakString": "[split(variables('firstFileNameString'), '?')]",
        "firstFileName": "[variables('firstFileNameBreakString')[0]]"
    },
    "resources": [
        {
            "name": "[concat(parameters('vmName'),'/CustomScriptExtension')]",
            "type": "Microsoft.HybridCompute/machines/extensions",
            "location": "[parameters('location')]",
            "apiVersion": "2022-03-10",
            "properties": {
                "publisher": "Microsoft.Compute",
                "type": "CustomScriptExtension",
                "autoUpgradeMinorVersion": true,
                "settings": {
                    "fileUris": "[split(parameters('fileUris'), ' ')]"
                },
                "protectedSettings": {
                    "commandToExecute": "[concat ('powershell -ExecutionPolicy Unrestricted -File ', variables('firstFileName'), ' ', parameters('arguments'))]"
                }
            }
        }
    ]
}

Arquivo de parâmetro.

{
  "$schema": "https://schema.management.azure.com/schemas/0.1.2-preview/CreateUIDefinition.MultiVm.json#",
  "handler": "Microsoft.Azure.CreateUIDef",
  "version": "0.1.2-preview",
  "parameters": {
    "basics": [
      {}
    ],
    "steps": [
      {
        "name": "customScriptExt",
        "label": "Add Custom Script Extension",
        "elements": [
          {
            "name": "fileUris",
            "type": "Microsoft.Common.FileUpload",
            "label": "Script files",
            "toolTip": "The script files that will be downloaded to the virtual machine.",
            "constraints": {
              "required": false
            },
            "options": {
              "multiple": true,
              "uploadMode": "url"
            },
            "visible": true
          },
          {
            "name": "commandToExecute",
            "type": "Microsoft.Common.TextBox",
            "label": "Command",
            "defaultValue": "sh script.sh",
            "toolTip": "The command to execute, for example: sh script.sh",
            "constraints": {
              "required": true
            },
            "visible": true
          }
        ]
      }
    ],
    "outputs": {
      "vmName": "[vmName()]",
      "location": "[location()]",
      "fileUris": "[steps('customScriptExt').fileUris]",
      "commandToExecute": "[steps('customScriptExt').commandToExecute]"
    }
  }
}

Implantar a extensão do agente de dependência

Para usar a extensão do agente de dependência do Azure Monitor, execute um dos exemplos a seguir para Linux e Windows. Caso não esteja familiarizado com o agente de dependência, consulte Visão geral dos agentes do Azure Monitor.

Arquivo de modelo para Linux

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vmName": {
      "type": "string",
      "metadata": {
        "description": "The name of existing Linux machine."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.HybridCompute/machines/extensions",
      "name": "[concat(parameters('vmName'),'/DAExtension')]",
      "apiVersion": "2022-03-10",
      "location": "[resourceGroup().location]",
      "dependsOn": [
      ],
      "properties": {
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentLinux",
        "enableAutomaticUpgrade": true
      }
    }
  ],
  "outputs": {
  }
}

Arquivo de modelo para Windows

{
  "$schema": "https://schema.management.azure.com/schemas/2015-01-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "vmName": {
      "type": "string",
      "metadata": {
        "description": "The name of existing Windows machine."
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.HybridCompute/machines/extensions",
      "name": "[concat(parameters('vmName'),'/DAExtension')]",
      "apiVersion": "2022-03-10",
      "location": "[resourceGroup().location]",
      "dependsOn": [
      ],
      "properties": {
        "publisher": "Microsoft.Azure.Monitoring.DependencyAgent",
        "type": "DependencyAgentWindows",
        "enableAutomaticUpgrade": true
      }
    }
  ],
  "outputs": {
  }
}

Implantação de modelo

Salve o arquivo de modelo em disco. Em seguida, você pode implantar a extensão no computador conectado usando o comando a seguir:

New-AzResourceGroupDeployment -ResourceGroupName "ContosoEngineering" -TemplateFile "D:\Azure\Templates\DependencyAgent.json"

Implantar a extensão de máquina virtual do Azure Key Vault (versão prévia)

O JSON a seguir mostra o esquema para a extensão da máquina virtual de Key Vault (pré-visualização). A extensão não requer configurações protegidas, porque todas as suas configurações são consideradas informações sem impacto de segurança. A extensão requer uma lista dos certificados monitorados, a frequência de sondagem e o repositório de certificados de destino.

Arquivo de modelo para Linux

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "autoUpgradeMinorVersion":{
            "type": "bool"
        },
        "pollingIntervalInS":{
          "type": "int"
        },
        "certificateStoreName":{
          "type": "string"
        },
        "certificateStoreLocation":{
          "type": "string"
        },
        "observedCertificates":{
          "type": "string"
        },
        "msiEndpoint":{
          "type": "string"
        },
        "msiClientId":{
          "type": "string"
        }
},
"resources": [
   {
      "type": "Microsoft.HybridCompute/machines/extensions",
      "name": "[concat(parameters('vmName'),'/KVVMExtensionForLinux')]",
      "apiVersion": "2022-03-10",
      "location": "[parameters('location')]",
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ignored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
          },
          "authenticationSettings": {
                "msiEndpoint":  "http://localhost:40342/metadata/identity"
        }
      }
    }
  }
 ]
}

Arquivo de modelo para Windows

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "vmName": {
            "type": "string"
        },
        "location": {
            "type": "string"
        },
        "autoUpgradeMinorVersion":{
            "type": "bool"
        },
        "pollingIntervalInS":{
          "type": "int"
        },
        "certificateStoreName":{
          "type": "string"
        },
        "linkOnRenewal":{
          "type": "bool"
        },
        "certificateStoreLocation":{
          "type": "string"
        },
        "requireInitialSync":{
          "type": "bool"
        },
        "observedCertificates":{
          "type": "string"
        },
        "msiEndpoint":{
          "type": "string"
        },
        "msiClientId":{
          "type": "string"
        }
},
"resources": [
   {
      "type": "Microsoft.HybridCompute/machines/extensions",
      "name": "[concat(parameters('vmName'),'/KVVMExtensionForWindows')]",
      "apiVersion": "2022-03-10",
      "location": "[parameters('location')]",
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": "3600",
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "linkOnRenewal": <Only Windows. This feature ensures s-channel binding when certificate renews, without necessitating a re-deployment.  e.g.: false>,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "requireInitialSync": <initial synchronization of certificates e.g.: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net"
        },
        "authenticationSettings": {
                "msiEndpoint": "http://localhost:40342/metadata/identity"
        }
      }
    }
  }
 ]
}

Observação

Os URLs dos seus certificados observados devem estar no formato https://myVaultName.vault.azure.net/secrets/myCertName. O motivo é que o caminho /secrets retorna o certificado completo, incluindo a chave privada, enquanto o caminho /certificates não. É possível encontrar mais informações sobre certificados em visão geral de chaves, segredos e certificados do Azure Key Vault.

Implantação de modelo

Salve o arquivo de modelo em disco. Em seguida, você pode implantar a extensão no computador conectado com o comando a seguir.

Observação

A extensão de máquina virtual exige que seja atribuída a identidade gerenciada do sistema ou do usuário para autenticação no Key Vault. Consulte Autenticar em recursos do Azure com servidores habilitados para Azure Arc para servidores habilitados para Azure Arc do Linux e Windows.

New-AzResourceGroupDeployment -ResourceGroupName "ContosoEngineering" -TemplateFile "D:\Azure\Templates\KeyVaultExtension.json"

É possível implantar, gerenciar e remover extensões de máquina virtual usando o Azure PowerShell, ao portal do Azure ou a CLI do Azure.
Encontre informações de solução de problemas no guia para solucionar problemas de extensões de VM.

Compartilhar via

Habilitar extensões de VM do Azure usando um modelo do ARM

Habilitar a extensão de VM do Log Analytics

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Arquivo de parâmetros

Aplicar a Extensão de Script Personalizado

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Arquivo de parâmetro.

Implantar a extensão do agente de dependência

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Implantação de modelo

Implantar a extensão de máquina virtual do Azure Key Vault (versão prévia)

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Implantação de modelo

Comentários

Recursos adicionais

Compartilhar via

Habilitar extensões de VM do Azure usando um modelo do ARM

Habilitar a extensão de VM do Log Analytics

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Arquivo de parâmetros

Aplicar a Extensão de Script Personalizado

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Arquivo de parâmetro.

Implantar a extensão do agente de dependência

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Implantação de modelo

Implantar a extensão de máquina virtual do Azure Key Vault (versão prévia)

Arquivo de modelo para Linux

Arquivo de modelo para Windows

Implantação de modelo

Conteúdo relacionado

Comentários

Recursos adicionais