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

  • Статья

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

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

Расширение виртуальной машины Key Vault поддерживает следующие версии Linux:

Примечание.

Расширение хранилища ключей Key Vault виртуальной машины скачивает сертификаты в расположение по умолчанию или в расположение, предоставленное свойством "certStoreLocation" в параметрах расширения виртуальной машины. Расширение виртуальной машины Key Vault обновляет разрешение папки на 700 (drwx------), разрешающее чтение, запись и выполнение разрешения только владельцу папки.

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

  • PKCS #12
  • PEM

Необходимые компоненты

Версия расширения ВМ Хранилища ключей

  • Пользователи могут обновить версию расширения виртуальной машины Key Vault, чтобы V2.0 использовать функцию скачивания полной цепочки сертификатов. Сертификаты издателя (промежуточные и корневые) включаются в конечный сертификат в PEM-файле.

  • Если вы предпочитаете обновить до v2.0, сначала необходимо удалить v1.0, а затем установить v2.0.

  az vm extension delete --name KeyVaultForLinux --resource-group ${resourceGroup} --vm-name ${vmName}
  az vm extension set -n "KeyVaultForLinux" --publisher Microsoft.Azure.KeyVault --resource-group "${resourceGroup}" --vm-name "${vmName}" –settings .\akvvm.json –version 2.0

Флаг --version 2.0 является необязательным, так как последняя версия установлена по умолчанию.

  • Если у виртуальной машины есть сертификаты, скачанные версией 1.0, удаление расширения AKVVM версии 1.0 не удаляет скачанные сертификаты. После установки версии 2.0 существующие сертификаты не изменяются. Чтобы получить PEM-файл с полной цепочкой на виртуальной машине, необходимо удалить файлы сертификата или перевернуть сертификат.

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

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

    {
      "type": "Microsoft.Compute/virtualMachines/extensions",
      "name": "KVVMExtensionForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It's ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "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", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "authenticationSettings": {
          "msiEndpoint":  <Required when msiClientId is provided. MSI endpoint e.g. for most Azure VMs: "http://169.254.169.254/metadata/identity">,
          "msiClientId":  <Required when VM has any user assigned identities. MSI identity e.g.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
        }
       }
      }
    }

Примечание.

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

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

Внимание

Свойство authentication Параметры требуется для виртуальных машин с удостоверениями, назначенными пользователем. Даже если вы хотите использовать назначенное системой удостоверение, это по-прежнему необходимо в противном случае расширение виртуальной машины не знает, какое удостоверение следует использовать. Без этого раздела виртуальная машина с назначенными пользователем удостоверениями приведет к сбою расширения Key Vault и не удается скачать сертификаты. Задайте для msiClientId удостоверение, которое будет проходить проверку подлинности в Key Vault.

Также требуется для виртуальных машин с поддержкой Azure Arc. Задайте для msiEndpoint значение http://localhost:40342/metadata/identity.

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

Имя. Значение и пример Тип данных
версия_API 2022-07-01 Дата
издатель Microsoft.Azure.KeyVault строка
type KeyVaultForLinux строка
typeHandlerVersion 2.0 INT
pollingIntervalInS 3600 строка
certificateStoreName Он игнорируется в Linux строка
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store строка
requireInitialSync true boolean
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": "KeyVaultForLinux",
      "apiVersion": "2022-11-01",
      "location": "<location>",
      "dependsOn": [
          "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
      ],
      "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored 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"
        }
      }
      }
    }

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

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

Чтобы включить зависимость расширения, установите следующее:

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

Примечание.

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

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

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

Клиенты PowerShell часто добавляют \ в " из settings.js, что приведет к сбою akvvm_service с ошибкой: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

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

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

        # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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 = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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 -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

  • Чтобы развернуть расширение в масштабируемом наборе виртуальных машин, выполните следующие действия.

          # Start the deployment
      az vmss extension set -n "KeyVaultForLinux" `
      --publisher Microsoft.Azure.KeyVault `
      -g "<resourcegroup>" `
      --vmss-name "<vmssName>" `
      --version 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

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

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

Данные о состоянии развертываний расширения можно получить на портале 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"

Azure CLI может выполняться в нескольких средах оболочки, но с небольшими вариантами формата. Если вы столкнулись с непредвиденными результатами команд Azure CLI, см. статью Как успешно использовать Azure CLI.

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

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

Расположение Description
/var/log/waagent.log Показывает, когда произошло обновление расширения.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Изучите журналы службы расширения Key Vault для виртуальной машины, чтобы определить состояние службы akvvm_service и скачивания сертификата. Расположение скачивания ФАЙЛОВ PEM можно найти в файлах с записью с именем файла сертификата. Если значение параметра certificateStoreLocation не задано, по умолчанию будет использоваться /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/* Расположение конфигурации и двоичных файлов для службы расширения Key Vault для виртуальной машины.

Символьные ссылки или Symlinks — это расширенные ярлыки. Чтобы избежать наблюдения за папкой и автоматического получения последнего сертификата, вы можете использовать эту символьную ссылку ([VaultName].[CertificateName]) для получения последней версии сертификата в Linux.

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

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

Поддержка

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