适用于 Windows 的 Key Vault 虚拟机扩展Key Vault virtual machine extension for Windows

• 09/07/2020
• • 

密钥保管库 VM 扩展可自动刷新 Azure 密钥保管库中存储的证书。The Key Vault VM extension provides automatic refresh of certificates stored in an Azure key vault. 具体而言，该扩展监视一系列观测到存储在 Key Vault 中的证书，并在检测到更改时检索并安装相应的证书。Specifically, the extension monitors a list of observed certificates stored in key vaults, and, upon detecting a change, retrieves, and installs the corresponding certificates. 本文档详细介绍适用于 Windows 的 Key Vault VM 虚拟机扩展支持的平台、配置和部署选项。This document details the supported platforms, configurations, and deployment options for the Key Vault VM extension for Windows.

操作系统Operating system

密钥保管库 VM 扩展支持以下版本的 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

支持的证书内容类型Supported certificate content types

• PKCS #12PKCS #12
• PEMPEM

扩展架构Extension schema

以下 JSON 显示 Key Vault VM 代理扩展的架构。The following JSON shows the schema for the Key Vault VM extension. 该扩展不需要受保护的设置 - 其所有设置都被视为公共信息。The extension does not require protected settings - all its settings are considered public information. 该扩展需要受监视的证书列表、轮询频率和目标证书存储。The extension requires a list of monitored certificates, polling frequency, and the destination certificate store. 具体而言：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 enables auto-rotation of SSL certificates, without necessitating a re-deployment or binding.  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.cn/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">
        }
       }
      }
    }

属性值Property values

模板部署Template deployment

可使用 Azure Resource Manager 模板部署 Azure VM 扩展。Azure VM extensions can be deployed with Azure Resource Manager templates. 部署需要部署后刷新证书的一个或多个虚拟机时，模板是理想选择。Templates are ideal when deploying one or more virtual machines that require post deployment refresh of certificates. 可将该扩展部署到单个 VM 或虚拟机规模集。The extension can be deployed to individual VMs or virtual machine scale sets. 架构和配置对于这两种模板类型通用。The schema and configuration are common to both template types.

虚拟机扩展的 JSON 配置必须嵌套在模板的虚拟机资源片段中，具体来说是嵌套在虚拟机模板的 "resources": [] 对象中，对于虚拟机规模集而言，是嵌套在 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 对象下。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.

    {
      "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.cn/secrets/mycertificate"
        }      
      }
      }
    }

Azure PowerShell 部署Azure PowerShell deployment

可以使用 Azure PowerShell，将 Key Vault VM 扩展部署到现有虚拟机或虚拟机规模集。The Azure PowerShell can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

• 在 VM 上部署该扩展：To deploy the extension on a VM:

  # Build settings
  $settings = '{"secretsManagementSettings": 
      { "pollingIntervalInS": "' + <pollingInterval> + 
      '", "certificateStoreName": "' + <certStoreName> + 
      '", "certificateStoreLocation": "' + <certStoreLoc> + 
      '", "observedCertificates": ["' + <observedCerts> + '"] } }'
  $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
  
  

• 在虚拟机规模集上部署该扩展：To deploy the extension on a virtual machine scale set :

  
  # Build settings
  $settings = '{"secretsManagementSettings": 
      { "pollingIntervalInS": "' + <pollingInterval> + 
      '", "certificateStoreName": "' + <certStoreName> + 
      '", "certificateStoreLocation": "' + <certStoreLoc> + 
      '", "observedCertificates": ["' + <observedCerts> + '"] } }'
  $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 
  
  

Azure CLI 部署Azure CLI deployment

可以使用 Azure CLI，将密钥保管库 VM 扩展部署到现有虚拟机或虚拟机规模集。The Azure CLI can be used to deploy the Key Vault VM extension to an existing virtual machine or virtual machine scale set.

• 在 VM 上部署该扩展：To deploy the extension on a VM:

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

• 在虚拟机规模集上部署该扩展：To deploy the extension on a virtual machine scale set :

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

请注意以下限制/要求：Please be aware of the following restrictions/requirements:

• Key Vault 限制：Key Vault restrictions:
  • 必须在部署时存在It must exist at the time of the deployment
  • 使用 MSI 为 VM/VMSS 标识设置密钥保管库访问策略Key Vault Access Policy is set for VM/VMSS Identity using MSI

故障排除和支持Troubleshoot and support

疑难解答Troubleshoot

有关扩展部署状态的数据可以从 Azure 门户和使用 Azure PowerShell 进行检索。Data about the state of extension deployments can be retrieved from the Azure portal, and by using the Azure PowerShell. 若要查看给定 VM 的扩展部署状态，请使用 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>

Azure CLIAzure CLI

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

扩展执行输出将记录到以下文件：Extension execution output is logged to the following file:

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

支持Support

如果对本文中的任何观点存在疑问，可以联系 Azure 支持上的 Azure 专家。If you need more help at any point in this article, you can contact the Azure experts on the Azure support. 或者，也可以提出 Azure 支持事件。Alternatively, you can file an Azure support incident. 请转到 Azure 支持站点提交请求。Go to the Azure support site and submit your request. 有关使用 Azure 支持的信息，请阅读 Azure 支持常见问题。For information about using Azure Support, read the Azure support FAQ.