Расширение виртуальной машины Key Vault для Windows

Расширение виртуальной машины Key Vault обеспечивает автоматическое обновление секретов, хранящихся в Azure Key Vault. В частности, расширение отслеживает список наблюдаемых сертификатов, хранящихся в хранилищах ключей, и при обнаружении изменения извлекает и устанавливает соответствующие сертификаты. В этом документе подробно описаны поддерживаемые платформы, конфигурации и параметры развертывания для расширения виртуальной машины Key Vault для Windows.

Операционная система

Расширение Key Vault VM поддерживает следующие версии Windows:

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

Расширение Key Vault VM также поддерживается на пользовательской локальной виртуальной машине, которая передается и преобразуется в специализированный образ для использования в Azure с помощью установки основных компонентов Windows Server 2019.

Примечание

Расширение виртуальной машины Key Vault скачивает все сертификаты в хранилище сертификатов Windows или в расположение, предоставленное свойством "certificateStoreLocation" в параметрах расширения виртуальной машины. В настоящее время расширение виртуальной машины Key Vault предоставляет разрешение на доступ к закрытому ключу сертификата только учетной записи администратора локальной системы. Кроме того, в настоящее время невозможно определить расположение хранилища сертификатов. Группа расширения виртуальной машины работает над решением для закрытия этого разрыва возможностей.

Поддерживаемые типы содержимого сертификатов

  • PKCS #12
  • PEM

Предварительные требования

"identity": {
  "type": "UserAssigned",
  "userAssignedIdentities": {
    "[parameters('userAssignedIdentityResourceId')]": {}
  }
}
  • Расширение AKV должно иметь этот параметр:
"authenticationSettings": {
  "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
  "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
}

Схема расширения

В следующем JSON-файле показана схема для расширения виртуальной машины Key Vault. Расширению не требуются защищенные параметры, так как все его параметры считаются открытой информацией. Для расширения необходим список отслеживаемых сертификатов, указание частоты опроса и конечное хранилище сертификатов. В частности:

    {
      "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": <string specifying 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">
        }
       }
      }
    }

Примечание

Наблюдаемые URL-адреса сертификатов должны иметь формат https://myVaultName.vault.azure.net/secrets/myCertName.

Это связано с тем, что путь /secrets возвращает полный сертификат, включая закрытый ключ, а путь /certificates — нет. Дополнительные сведения о сертификатах можно найти в статье Сертификаты Key Vault.

Важно!

Свойство authenticationSettings требуется только для виртуальных машин с назначенными пользователем удостоверениями. В нем указывается удостоверение, используемое для проверки подлинности в Key Vault.

Важно!

При указании "msiClientId" следует обязательно указать свойство "msiEndpoint". Обычно значение должно быть http://169.254.169.254/metadata/identity/oauth2/token.

Значения свойств

Имя Значение и пример Тип данных
версия_API 07.01.2019 Дата
publisher Microsoft.Azure.KeyVault строка
type KeyVaultForWindows строка
typeHandlerVersion 1.0 INT
pollingIntervalInS 3600 строка
certificateStoreName MY строка
linkOnRenewal false Логическое
certificateStoreLocation LocalMachine или CurrentUser (с учетом регистра) строка
requireInitialSync Да Логическое
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] массив строк
msiEndpoint http://169.254.169.254/metadata/identity строка
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 строка

Развертывание шаблона

Расширения виртуальной машины Azure можно развернуть с помощью шаблонов Azure Resource Manager. Шаблоны идеально подходят для развертывания одной или нескольких виртуальных машин, требующих обновления сертификатов, выполняемого после развертывания. Расширение можно развертывать на отдельных виртуальных машинах или в масштабируемых наборах виртуальных машин. Для обоих типов шаблонов используются общие схема и конфигурация.

Файл конфигурации JSON для расширения виртуальной машины должен быть вложен во фрагмент ресурса виртуальной машины в шаблоне, в частности в объект "resources": [] для шаблона виртуальной машины или в объект "virtualMachineProfile":"extensionProfile":{"extensions" :[], если используется масштабируемый набор виртуальных машин.

Примечание

Расширение виртуальной машины требует назначения управляемого удостоверения системы или пользователя для проверки подлинности в Key Vault. См. статью Проверка подлинности в Key Vault и назначение политики доступа в Key Vault.

    {
      "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": <string specifying 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"]>
        }      
      }
      }
    }

Упорядочение зависимостей расширений

Расширение виртуальной машины для Key Vault поддерживает упорядочение расширений, если оно настроено. По умолчанию расширение сообщает о том, что оно успешно запущено, как только начнется опрос. Однако можно настроить ожидание до успешной загрузки полного списка сертификатов, прежде чем сообщать об успешном запуске. Если другие расширения зависят от установки полного набора сертификатов перед запуском, то включение этого параметра позволит этому расширению объявить зависимость от расширения Key Vault. Это предотвратит запуск этих расширений до тех пор, пока не будут установлены все сертификаты, от которых они зависят. Расширение будет повторять начальную загрузку неограниченно долго и останется в состоянии Transitioning.

Чтобы включить эту функцию, установите следующие значения:

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

Примечание

Использование этой функции несовместимо с шаблоном ARM, который создает удостоверение, назначенное системой, и обновляет политику доступа к хранилищу ключей с этим удостоверением. Это приведет к взаимоблокировке, так как политика доступа к хранилищу невозможно обновить до тех пор, пока не будут запущены все расширения. Вместо этого следует использовать одно назначенное пользователем удостоверение MSI и предварительно подготовить список ACL для хранилищ с этим удостоверением перед развертыванием.

Развертывание с помощью Azure PowerShell

Предупреждение

Клиенты PowerShell часто добавляют \ в " в файле settings.json, что приводит к сбою akvvm_service с ошибкой [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.. Дополнительные символы \ и " будут отображаться на портале в группе Расширения раздела Параметры. Чтобы избежать этого, инициализируйте $settings как PowerShell HashTable:

$settings = @{
    "secretsManagementSettings" = @{ 
        "pollingIntervalInS"       = "<pollingInterval>"; 
        "certificateStoreName"     = "<certStoreName>"; 
        "certificateStoreLocation" = "<certStoreLoc>"; 
        "observedCertificates"     = @("<observedCert1>", "<observedCert2>") } }

Azure PowerShell можно использовать для развертывания расширения виртуальной машины Key Vault на имеющейся виртуальной машине или в масштабируемых наборах виртуальных машин.

  • Развертывание расширения на виртуальной машине:

        # 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
    
    
  • Чтобы развернуть расширение в масштабируемом наборе виртуальных машин, сделайте следующее:

    
        # 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 
    
    

Развертывание с помощью Azure CLI

Для развертывания расширения виртуальной машины Key Vault на имеющейся виртуальной машине или в масштабируемом наборе виртуальных машин можно использовать Azure CLI.

  • Развертывание расширения на виртуальной машине:

       # 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> \"] }}'
    
  • Чтобы развернуть расширение в масштабируемом наборе виртуальных машин, сделайте следующее:

          # 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> \"] }}'
    

Ознакомьтесь со следующими ограничениями и требованиями.

  • Ограничения, касающиеся решения Key Vault:

Устранение неполадок и поддержка

Вопросы и ответы

  • Существует ли ограничение на количество сертификатов observedCertificates, которое можно настроить? Нет, расширение виртуальной машины Key Vault не ограничивает число observedCertificates.

Диагностика

Данные о состоянии развертываний расширения можно получить на портале Azure, а также с помощью Azure PowerShell. Чтобы просмотреть состояние развертывания расширений для определенной виртуальной машины, выполните следующую команду в Azure PowerShell.

Azure PowerShell

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

Azure CLI

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

Журналы и конфигурация

Журналы расширения Key Vault для виртуальной машины существуют только локально на виртуальной машине и предоставляют максимум информации для устранения неполадок.

Расположение Описание
C:\WindowsAzure\Logs\WaAppAgent.log Показывает, когда произошло обновление расширения.
C:\WindowsAzure\Logs\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\ Показывает состояние загрузки сертификата. В качестве расположения для загрузки всегда будет использоваться My Store компьютера Windows (certlm.msc).
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\RuntimeSettings\ В журналах службы расширения Key Vault для виртуальной машины отображается состояние службы akvvm_service.
C:\Packages\Plugins\Microsoft.Azure.KeyVault.KeyVaultForWindows<самая последняя версия>\Status\ Расположение конфигурации и двоичных файлов для службы расширения Key Vault для виртуальной машины.

Поддержка

Если в любой момент при изучении этой статьи вам потребуется дополнительная помощь, вы можете обратиться к экспертам по Azure на форумах MSDN Azure и Stack Overflow. Кроме того, можно зарегистрировать обращение в службу поддержки Azure. Перейдите на сайт поддержки Azure и щелкните "Получить поддержку". Дополнительные сведения об использовании службы поддержки Azure см. в статье Часто задаваемые вопросы о поддержке Microsoft Azure.