Extensão da máquina virtual key Vault para WindowsKey Vault virtual machine extension for Windows

A extensão Key Vault VM fornece uma atualização automática dos certificados armazenados num cofre de chaves Azure.The Key Vault VM extension provides automatic refresh of certificates stored in an Azure key vault. Especificamente, a extensão monitoriza uma lista de certificados observados armazenados em cofres-chave e, ao detetar uma alteração, recupera e instala os certificados correspondentes.Specifically, the extension monitors a list of observed certificates stored in key vaults, and, upon detecting a change, retrieves, and installs the corresponding certificates. Este documento detalha as plataformas, configurações e opções de implementação suportadas para a extensão VM do Cofre chave para windows.This document details the supported platforms, configurations, and deployment options for the Key Vault VM extension for Windows.

Sistema operativoOperating system

A extensão VM do Cofre-Chave suporta versões abaixo do Windows:The Key Vault VM extension supports below versions of Windows:

  • Windows Server 2019Windows Server 2019
  • Windows Server 2016Windows Server 2016
  • Windows Server 2012Windows Server 2012

A extensão Key Vault VM também é suportada em VM local personalizado que é carregado e convertido em uma imagem especializada para uso em Azure usando a instalação do núcleo do Windows Server 2019.The Key Vault VM extension is also supported on custom local VM that is uploaded and converted into a specialized image for use in Azure using Windows Server 2019 core install.

Tipos de conteúdo de certificado suportadoSupported certificate content types

  • #12 PKCSPKCS #12
  • PEMPEM

Pré-requisitosPrerequisites

"identity": {
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "[parameters('userAssignedIdentityResourceId')]": {}
  }
}
  • A extensão AKV deve ter esta definição:AKV extension should have this setting:
"authenticationSettings": {
  "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
  "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
}

Esquema de extensãoExtension schema

O JSON seguinte mostra o esquema para a extensão VM do Cofre de Chaves.The following JSON shows the schema for the Key Vault VM extension. A extensão não requer configurações protegidas - todas as suas configurações são consideradas informações públicas.The extension does not require protected settings - all its settings are considered public information. A extensão requer uma lista de certificados monitorizados, frequência de sondagens e a loja de certificados de destino.The extension requires a list of monitored certificates, polling frequency, and the destination certificate store. Especificamente:Specifically:

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g: "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/secrets/mycertificate"
        },
        "authenticationSettings": {
                "msiEndpoint":  <Optional MSI endpoint e.g.: "http://169.254.169.254/metadata/identity">,
                "msiClientId":  <Optional MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
        }
       }
      }
    }

Nota

Os seus certificados observados URLs devem ser do formulário https://myVaultName.vault.azure.net/secrets/myCertName .Your observed certificates URLs should be of the form https://myVaultName.vault.azure.net/secrets/myCertName.

Isto porque o /secrets caminho devolve o certificado completo, incluindo a chave privada, enquanto o caminho /certificates não.This is because the /secrets path returns the full certificate, including the private key, while the /certificates path does not. Mais informações sobre certificados podem ser encontradas aqui: Certificados de Cofre ChaveMore information about certificates can be found here: Key Vault Certificates

Importante

A propriedade 'autenticaçõesSettings' só é necessária para VMs com identidades atribuídas pelo utilizador.The 'authenticationSettings' property is required only for VMs with user assigned identities. Especifica a identidade para a autenticação no Cofre de Chaves.It specifies identity to use for authentication to Key Vault.

Valores patrimoniaisProperty values

NameName Valor / ExemploValue / Example Tipo de DadosData Type
apiVersionapiVersion 2019-07-012019-07-01 datadate
publicadorpublisher Microsoft.Azure.KeyVaultMicrosoft.Azure.KeyVault stringstring
tipotype KeyVaultForWindowsKeyVaultForWindows stringstring
typeHandlerVersiontypeHandlerVersion 1.01.0 intint
sondagensIntervalInSpollingIntervalInS 36003600 stringstring
certificadoStoreNamecertificateStoreName MYMY stringstring
linkOnRenewallinkOnRenewal falsefalse booleanboolean
certificaStoreLocalizaçãocertificateStoreLocation LocalMachine ou CurrentUser (sensível a casos)LocalMachine or CurrentUser (case sensitive) stringstring
requerinitialSyncrequireInitialSync truetrue booleanboolean
certificados observadosobservedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate","https://myvault.vault.azure.net/secrets/mycertificate2"]["https://myvault.vault.azure.net/secrets/mycertificate","https://myvault.vault.azure.net/secrets/mycertificate2"] matriz de cordasstring array
msiEndpointmsiEndpoint http://169.254.169.254/metadata/identity stringstring
msiClientIdmsiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619c7373ae5-91c2-4165-8ab6-7381d6e75619 stringstring

Implementação de modelosTemplate deployment

As extensões Azure VM podem ser implementadas com modelos Azure Resource Manager.Azure VM extensions can be deployed with Azure Resource Manager templates. Os modelos são ideais quando se implanta uma ou mais máquinas virtuais que requerem atualização de envio pós-implantação de certificados.Templates are ideal when deploying one or more virtual machines that require post deployment refresh of certificates. A extensão pode ser implantada em VMs individuais ou conjuntos de balanças de máquinas virtuais.The extension can be deployed to individual VMs or virtual machine scale sets. O esquema e a configuração são comuns a ambos os tipos de modelos.The schema and configuration are common to both template types.

A configuração JSON para uma extensão de máquina virtual deve ser aninhada dentro do fragmento de recurso de máquina virtual do modelo, especificamente "resources": [] objeto para o modelo de máquina virtual e em caso de escala de máquina virtual definida sob "virtualMachineProfile":"extensionProfile":{"extensions" :[] objeto.The JSON configuration for a virtual machine extension must be nested inside the virtual machine resource fragment of the template, specifically "resources": [] object for the virtual machine template and in case of virtual machine scale set under "virtualMachineProfile":"extensionProfile":{"extensions" :[] object.

Nota

A extensão VM exigiria que o sistema ou identidade gerida pelo utilizador fosse atribuído para autenticar o cofre key.The VM extension would require system or user managed identity to be assigned to authenticate to Key vault. Veja como autenticar o Key Vault e atribuir uma política de acesso ao Cofre de Chaves.See How to authenticate to Key Vault and assign a Key Vault access policy.

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KeyVaultForWindows",
      "apiVersion": "2019-07-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForWindows",
      "typeHandlerVersion": "1.0",
      "autoUpgradeMinorVersion": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g: "3600">,
          "certificateStoreName": <certificate store name, e.g.: "MY">,
          "certificateStoreLocation": <certificate store location, currently it works locally only e.g.: "LocalMachine">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        }      
      }
      }
    }

Pedido de dependência de extensãoExtension Dependency Ordering

A extensão VM do Cofre-Chave suporta a ordem de extensão se configurada.The Key Vault VM extension supports extension ordering if configured. Por defeito, a extensão informa que começou com sucesso assim que começou a sondagem.By default the extension reports that it has successfully started as soon as it has started polling. No entanto, pode ser configurado para esperar até que tenha descarregado com sucesso a lista completa de certificados antes de reportar um início bem sucedido.However, it can be configured to wait until it has successfully downloaded the complete list of certificates before reporting a successful start. Se outras extensões dependerem de ter o conjunto completo de certificados instalados antes de iniciarem, então permitirá que esta extensão declare uma dependência da extensão do Cofre de Chaves.If other extensions depend on having the full set of certificates install before they start, then enabling this setting will allow those extension to declare a dependency on the Key Vault extension. Isto evitará que as extensões comecem até que todos os certificados de que dependem tenham sido instalados.This will prevent those extensions from starting until all certificates they depend on have been installed. A extensão tentará novamente o download inicial indefinidamente e permanecerá em Transitioning estado.The extension will retry the initial download indefinitely and remain in a Transitioning state.

Para ligar isto, ligue o seguinte:To turn this on set the following:

"secretsManagementSettings": {
    "requireInitialSync": true,
    ...
}

Nota

A utilização desta funcionalidade não é compatível com um modelo ARM que cria uma identidade atribuída ao sistema e atualiza uma política de acesso do Cofre de Chaves com essa identidade.Using this feature is not compatible with an ARM template that creates a system assigned identity and updates a Key Vault access policy with that identity. Ao fazê-lo, a política de acesso ao cofre não poderá ser atualizada até que todas as extensões tenham começado.Doing so will result in a deadlock as the vault access policy cannot be updated until all extensions have started. Em vez disso, deve utilizar uma identidade MSI atribuída a um único utilizador e pré-ACL os seus cofres com essa identidade antes de ser implantado.You should instead use a single user assigned MSI identity and pre-ACL your vaults with that identity before deploying.

Implantação Azure PowerShellAzure PowerShell deployment

Aviso

Os clientes PowerShell muitas vezes \ adicionam-se ao " settings.jssobre o qual causará falhas akvvm_service com erro: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.PowerShell clients often add \ to " in the settings.json which will cause akvvm_service fails with error: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

O Azure PowerShell pode ser utilizado para implantar a extensão VM do Cofre de Chaves a uma máquina virtual ou conjunto de balanças de máquinas virtuais existentes.The Azure PowerShell can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

  • Para implantar a extensão num VM:To deploy the extension on a VM:

        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName =  "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
    
        # Start the deployment
        Set-AzVmExtension -TypeHandlerVersion "1.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
    
    
  • Para implantar a extensão num conjunto de escala de máquina virtual:To deploy the extension on a virtual machine scale set :

    
        # Build settings
        $settings = '{"secretsManagementSettings": 
        { "pollingIntervalInS": "' + <pollingInterval> + 
        '", "certificateStoreName": "' + <certStoreName> + 
        '", "certificateStoreLocation": "' + <certStoreLoc> + 
        '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
        $extName = "KeyVaultForWindows"
        $extPublisher = "Microsoft.Azure.KeyVault"
        $extType = "KeyVaultForWindows"
    
        # Add Extension to VMSS
        $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
        Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "1.0" -Setting $settings
    
        # Start the deployment
        Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss 
    
    

Implantação do Azure CLIAzure CLI deployment

O CLI Azure pode ser utilizado para implantar a extensão VM do Cofre de Chaves a uma máquina virtual ou conjunto de balanças de máquinas virtuais existentes.The Azure CLI can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

  • Para implantar a extensão num VM:To deploy the extension on a VM:

       # Start the deployment
         az vm extension set -name "KeyVaultForWindows" `
         --publisher Microsoft.Azure.KeyVault `
         -resource-group "<resourcegroup>" `
         --vm-name "<vmName>" `
         --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    
  • Para implantar a extensão num conjunto de escala de máquina virtual:To deploy the extension on a virtual machine scale set :

          # Start the deployment
          az vmss extension set -name "KeyVaultForWindows" `
           --publisher Microsoft.Azure.KeyVault `
           -resource-group "<resourcegroup>" `
           --vmss-name "<vmName>" `
           --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'
    

Por favor, esteja ciente das seguintes restrições/requisitos:Please be aware of the following restrictions/requirements:

  • Restrições do Cofre chave:Key Vault restrictions:

Resolução de problemas e apoioTroubleshoot and support

Perguntas Mais FrequentesFrequently Asked Questions

  • Existe um limite para o número de certificados observados que pode configurar?Is there is a limit on the number of observedCertificates you can setup? Não, a extensão VM do cofre não tem limite no número de Certificados observados.No, Key Vault VM Extension doesn’t have limit on the number of observedCertificates.

Resolução de problemasTroubleshoot

Os dados sobre o estado das extensões podem ser recuperados a partir do portal Azure e utilizando o Azure PowerShell.Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure PowerShell. Para ver o estado de implantação das extensões para um determinado VM, executar o seguinte comando utilizando o Azure PowerShell.To see the deployment state of extensions for a given VM, run the following command using the Azure PowerShell.

Azure PowerShellAzure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

CLI do AzureAzure CLI

 az vm get-instance-view --resource-group <resource group name> --name  <vmName> --query "instanceView.extensions"

Registos e configuraçãoLogs and configuration

%windrive%\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows\<version>\akvvm_service_<date>.log

SuporteSupport

Se precisar de mais ajuda em qualquer ponto deste artigo, pode contactar os especialistas da Azure nos fóruns msdn Azure e Stack Overflow.If you need more help at any point in this article, you can contact the Azure experts on the MSDN Azure and Stack Overflow forums. Em alternativa, pode apresentar um incidente de suporte Azure.Alternatively, you can file an Azure support incident. Vá ao site de suporte do Azure e selecione Obter suporte.Go to the Azure support site and select Get support. Para obter informações sobre a utilização do Suporte Azure, leia o suporte do Microsoft Azure FAQ.For information about using Azure Support, read the Microsoft Azure support FAQ.