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

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

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

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

• Ubuntu 24.04
• Azure Linux 3.0 и 4.0
• Red Hat Enterprise Linux (RHEL) 9

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

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

• PKCS #12
• PEM

Функции

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

• Устанавливает две последние версии каждого сертификата.
• Устанавливает каждый сертификат в виде раздельных файлов: файла полной цепочки .pem и отдельного файла закрытого ключа .keyid, каждый из которых записывается как версионируемый файл со стабильной символической ссылкой, указывающей на последнюю версию.
• Выполняет проверку цепочки сертификатов перед установкой любого сертификата с расширенным использованием ключа (EKU) для проверки подлинности TLS-сервера. При сбое проверки сертификат всё равно устанавливается, если проверку невозможно завершить из-за временных проблем с сетью. Сертификаты без EKU проверки подлинности сервера не подлежат этой проверке.
• Применяет списки ACL POSIX, чтобы предоставить настроенным пользователям и группам доступ на чтение к закрытому ключу. Принудительное применение ACL всегда включено.
• Поддерживает необязательное переопределение параметров аутентификации для каждого сертификата отдельно, что позволяет отдельным отслеживаемым сертификатам проходить аутентификацию в Key Vault с использованием управляемого удостоверения, отличного от используемого расширением по умолчанию. Дополнительные сведения см. в разделе "Схема расширения".
• Поддерживает интеграцию ведения журнала расширений виртуальных машин с помощью Fluentd. Дополнительные сведения см. в разделе "Ведение журнала с помощью Fluentd".

Обновление с версии 3.0

При обновлении с версии 3.0 следующие функции изменяются или удаляются.

Общие критические изменения:

• pollingIntervalInS теперь ограничено в диапазоне от 5 до 60 минут. По умолчанию расширение выполняет опрос один раз в час.
• requireInitialSync удален. Расширение сообщает об успешном выполнении только в том случае, если оно устанавливает все настроенные сертификаты.
• Вы больше не можете настроить определенную версию сертификата. Наблюдаемые URL-адреса сертификатов не должны содержать версию.
• Устаревшая схема, в которой observedCertificates представляет собой список строк URL-адресов, больше не поддерживается. Каждая запись должна быть объектом со свойством url .

Критические изменения в Linux:

• Цепочка сертификатов и закрытый ключ теперь записываются в отдельные файлы. В версии 3.0 полная цепочка и закрытый ключ были объединены в один PEM-файл. В версии 4.x расширение записывает полную цепочку сертификатов в <vaultname>.<certname>.pem, а закрытый ключ — в отдельный файл <vaultname>.<certname>.keyid. Это изменение является критическим: приложения, ожидающие, что ключ и цепочка в одном файле должны быть обновлены, чтобы считывать цепочку из .pem файла и закрытый ключ из .keyid файла. Файл .luma обновляется после обновления символьных ссылок, поэтому приложения должны отслеживать изменения этого файла метаданных.
• customSymbolicLinkName удален. Расширение всегда использует имя символической ссылки по умолчанию <vaultname>.<certname>.
• aclEnabled удален. Функция ACL теперь всегда включена.
• certificateStoreName игнорируется в Linux и не влияет.

Предпосылки

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

• Экземпляр Azure Key Vault с сертификатом. Дополнительные сведения см. в статье "Создание хранилища ключей" с помощью портала Azure.

• Виртуальная машина с назначенным управляемым удостоверением.

• Назначьте роль Key Vault Secrets User на уровне области действия Key Vault управляемой идентичности виртуальной машины или масштабируемого набора виртуальных машин Azure. Эта роль извлекает секретную часть сертификата. Дополнительные сведения см. в следующих статьях:

  • Аутентификация в Azure Key Vault
  • Использование секрета, ключа и сертификата Azure RBAC с помощью Azure Key Vault
  • Назначение ролей в контексте Key Vault

• Настройте группы масштабирования виртуальных машин с помощью следующей конфигурации identity:

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• Настройте расширение виртуальной машины Key Vault со следующей authenticationSettings конфигурацией:

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

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

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

• Для расширения не требуются защищенные параметры. Все параметры — это общедоступная информация.

• Url-адреса наблюдаемых сертификатов должны использовать форму https://myVaultName.vault.azure.net/secrets/myCertName.

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

• Узел URL должен соответствовать известному узлу Azure Key Vault.

• Свойство authenticationSettingsявляется обязательным для виртуальных машин с какими-либо назначенными пользователем удостоверениями, а также для виртуальных машин с поддержкой Azure Arc.

  Не указывайте это свойство при использовании удостоверения, назначаемого системой. Для виртуальных машин с поддержкой Azure Arc установите значение msiEndpointhttp://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the certificate private key. Example:
             [
                {
                    "url": <A Key Vault URI to the secret portion of the certificate. Example: "https://myvault.vault.azure.net/secrets/mycertificate1">,
                    "certificateStoreLocation": <The disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

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

Схема JSON содержит следующие свойства.

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

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

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

В следующем фрагменте JSON приведены примеры параметров для развертывания шаблона ARM расширения виртуальной машины Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "observedCertificates": [
                {
                    "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
                    "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
                    "acls": [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]
                },
                {
                    "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
                    "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Автоматическое обновление расширения

Расширение виртуальной машины Key Vault поддерживает автоматическое обновление расширения для виртуальных машин и масштабируемых наборов виртуальных машин в Azure. Azure автоматически поддерживает расширение в актуальном состоянии, если в предыдущих примерах задать свойствам autoUpgradeMinorVersion и enableAutomaticUpgrade значение true.

Порядок зависимостей для расширений

Расширение виртуальной машины Key Vault поддерживает упорядочение зависимостей расширений. Расширение сообщает об успешном запуске после скачивания и установки всех сертификатов.

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

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

Дополнительные сведения о настройке зависимостей между расширениями см. в статье Последовательная подготовка расширений в Масштабируемые наборы виртуальных машин.

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

Разверните расширение виртуальной машины Azure Key Vault с помощью Azure PowerShell. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующем фрагменте JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "observedCertificates": [
         {
            "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
            "acls": [
               { "user": "app1", "group": "appGroup1" },
               { "user": "service1" }
            ]
         },
         {
            "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

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

# Build settings
$settings = (Get-Content -Raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"

# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Развертывание на экземпляре набора масштабируемых виртуальных машин

# Build settings
$settings = (Get-Content -Raw ".\settings.json")
$extName = "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"

# Add extension to Virtual Machine Scale Sets
$vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
Add-AzVmssExtension -VirtualMachineScaleSet $vmss -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

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

Разверните расширение виртуальной машины Azure Key Vault с помощью Azure CLI. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).

В следующем фрагменте JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью Azure CLI.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "observedCertificates": [
         {
            "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate1",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
            "acls": [
               { "user": "app1", "group": "appGroup1" },
               { "user": "service1" }
            ]
         },
         {
            "url": "https://<examplekv>.vault.azure.net/secrets/mycertificate2",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

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

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Развертывание на экземпляре набора масштабируемых виртуальных машин

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "4.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Ведение журнала с помощью Fluentd

Расширение виртуальной машины Key Vault может перенаправить журналы в сборщик журналов Fluentd. Убедитесь, что сборщик журналов запущен и прослушивает конечную точку, указанную в параметрах.

Добавьте следующий раздел в параметры расширения:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}

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

Используйте эти рекомендации для устранения неполадок с развертыванием.

Проверка часто задаваемых вопросов

Существует ли ограничение на количество наблюдаемых сертификатов?

Нет. Расширение виртуальной машины Key Vault не ограничивает количество наблюдаемых сертификатов (observedCertificates).

Что такое расположение по умолчанию, в котором установлены сертификаты?

Если не указать certificateStoreLocation, расширение записывает сертификаты в /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Как принудительно заставить расширение получить новый сертификат?

Перезапустите службу akvvm_service (с отображаемым именем Key Vault VM Extension).

Как использовать другое удостоверение для определенного сертификата?

authenticationOverride Добавьте объект с целевым объектом msiClientId в запись observedCertificatesэтого сертификата. Сертификаты без переопределения используют верхний уровень authenticationSettings.

Просмотр состояния расширения

Проверьте состояние развертывания расширения на портале Azure или с помощью PowerShell или Azure CLI.

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

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• Azure CLI:

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

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

Просмотр журналов и конфигурации

Журналы расширений виртуальной машины Key Vault существуют только локально на виртуальной машине. Просмотрите сведения о журнале, чтобы помочь в устранении неполадок.

Установка сертификата в Linux

Расширение виртуальной машины Key Vault для Linux устанавливает сертификаты в виде PEM-файлов. Когда расширение скачивает сертификат из Key Vault, он:

1. Создает папку хранилища на основе параметра certificateStoreLocation. Если этот параметр не указан, местоположением по умолчанию будет /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Записывает цепочку сертификатов (конечный сертификат, затем промежуточные, затем корневой, если он есть в Key Vault) в версионированный файл полной цепочки .pem и соответствующий закрытый ключ — в версионированный файл .keyid.
3. Применяет списки управления доступом POSIX (ACL) к закрытому ключу на основе acls, указанного в конфигурации, предоставляя доступ на чтение перечисленным пользователям и группам. В противном случае файлы доступны только владельцу.
4. Создает или обновляет стабильную символьную ссылку (<vaultname>.<certname>.pem и <vaultname>.<certname>.keyid), указывающую на последнюю версию сертификата. Связывание всегда осуществляется.

Расположение хранилища сертификатов по умолчанию

Если вы не указываете расположение, расширение устанавливает сертификаты в разделе /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. Расширение игнорирует certificateStoreName в Linux.

Выходные файлы сертификатов

Для хранилища mykv и секрета server-tls успешная синхронизация приводит к следующему результату:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Настройте приложения для ссылки на стабильный путь символьной ссылки (например, /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem), чтобы они всегда считывали самую текущую версию сертификата без перенастройки при продлении.

Управление доступом к сертификату

По умолчанию файлы сертификатов и закрытых ключей доступны только их владельцу. Предоставьте доступ на чтение дополнительным пользователям и группам с помощью массива acls в конфигурации сертификата:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Каждая запись может указывать пользователя, группу или оба. Применение ACL всегда включено и в настоящее время предоставляет доступ для чтения.

Обновление сертификатов

При продлении сертификатов в Key Vault расширение автоматически выполняет следующие действия в следующем опросе:

1. Загружает новую версию сертификата.
2. Записывает новые версии файлов .pem и .keyid.
3. Обновляет стабильную символическую ссылку так, чтобы она указывала на новую версию, а существующие пути к приложению по-прежнему ссылались на актуальный сертификат.

Получите поддержку

Microsoft предоставляет поддержку только для основной версии 3.0 и более поздних версий расширения виртуальной машины Key Vault. Если вы используете версию 1.0, обновите ее до последней версии, прежде чем запрашивать поддержку.

Используйте эти другие параметры, чтобы устранить проблемы с развертыванием:

• Чтобы получить помощь, обратитесь к экспертам Azure в Microsoft Q& A.

• Если вы не найдете ответ на сайте, вы можете задать вопрос, чтобы получить ответ от Microsoft или других членов сообщества.

• Вы также можете связаться с служба поддержки Майкрософт. Сведения об использовании поддержки Azure см. в статье Как создать запрос в поддержку Azure.