Расширение виртуальной машины Key Vault для Linux
Расширение виртуальной машины Key Vault обеспечивает автоматическое обновление секретов, хранящихся в Azure Key Vault. В частности, расширение отслеживает список наблюдаемых сертификатов, хранящихся в хранилищах ключей. После обнаружения изменений расширение получает и устанавливает соответствующие сертификаты. В этом документе подробно описаны поддерживаемые платформы, конфигурации и параметры развертывания для расширения виртуальной машины Key Vault для Linux.
Операционная система
Расширение виртуальной машины Key Vault поддерживает следующие версии Linux:
- Ubuntu 20.04, 22.04
- Azure Linux
Примечание.
Расширение виртуальной машины Key Vault скачивает сертификаты в расположении по умолчанию или в расположение, предоставленное свойством certStoreLocation в параметрах расширения виртуальной машины (версия 1/2), или отдельных параметров сертификата (версия 3). Расширение виртуальной машины Key Vault обновляет разрешение папки на 700 (drwx------), разрешающее чтение, запись и выполнение разрешения только владельцу папки.
Поддерживаемые типы содержимого сертификатов
- PKCS #12
- PEM
Обновления в версии 3.0+
Версия 3.0 расширения виртуальной машины Key Vault для Linux добавляет поддержку следующих функций:
- Добавление разрешений ACL для скачанных сертификатов для предоставления доступа для чтения для пользователей и групп
- Конфигурация расположения установки сертификата
- Поддержка пользовательского символьного имени
- Поддержка интеграции с расширением виртуальной машины с помощью Fluentd
Необходимые компоненты
Экземпляр хранилища ключей с сертификатом. См. Создание хранилища ключей
Назначенное управляемое удостоверение на виртуальной машине или vmSS
Роль пользователя секретов Key Vault на уровне области хранилища ключей для виртуальных машин и управляемого удостоверения Azure Масштабируемые наборы виртуальных машин. Эта роль извлекает часть секрета сертификата. Дополнительные сведения см. в следующих статьях:
VMSS должна иметь следующие настройки удостоверения:
"identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }Расширение AKV должно иметь этот параметр:
"authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }
Версия расширения ВМ Хранилища ключей
Пользователи могут обновить существующую версию расширения виртуальной машины Key Vault до более новой.
Если вы предпочитаете обновить более новую версию, сначала необходимо удалить предыдущую версию, а затем установить более новую версию.
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 3.0
Флаг --version 3.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": "3.0",
"autoUpgradeMinorVersion": true,
"enableAutomaticUpgrade": true,
"settings": {
"loggingSettings": <Optional logging settings, e.g.:
{
"logger": <Logger engine name. e.g.: "fluentd">,
"endpoint": <Logger listening endpoint "tcp://localhost:24224">,
"format": <Logging format. e.g.: "forward">,
"servicename": <Service name used in logs. e.g.: "akvvm_service">
}>,
"secretsManagementSettings": {
"pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
"linkOnRenewal": <Not available on Linux e.g.: false>,
"requireInitialSync": <initial synchronization of certificates e..g: true>,
"aclEnabled": <Enables ACLs for downloaded certificates, e.g.: true>,
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location, ACL permission to certificate private key, and custom symbolic name. e.g.:
[
{
"url": <A Key Vault URI to the secret portion of the certificate. e.g.: "https://myvault.vault.azure.net/secrets/mycertificate1">,
"certificateStoreLocation": <disk path where certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
"customSymbolicLinkName": <symbolic name for the certificate. e.g.: "app1Cert1">,
"acls": [
{
"user": "app1",
"group": "appGroup1"
},
{
"user": "service1"
}
]
},
{
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
"certificateStoreLocation": <disk path where the certificate is stored, e.g.: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
"acls": [
{
"user": "app2",
}
]
}
]>
},
"authenticationSettings": <Optional msi settings, e.g.:
{
"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
Внимание
Свойство authenticationSettings требуется для виртуальных машин с удостоверениями, назначенными пользователем. Даже если вы хотите использовать назначенное системой удостоверение, это по-прежнему необходимо в противном случае расширение виртуальной машины не знает, какое удостоверение следует использовать. Без этого раздела виртуальная машина с назначенными пользователем удостоверениями приведет к сбою расширения Key Vault и не удается скачать сертификаты. Задайте для msiClientId удостоверение, которое будет проходить проверку подлинности в Key Vault.
Также требуется для виртуальных машин с поддержкой Azure Arc.
Задайте для msiEndpoint значение http://localhost:40342/metadata/identity.
Значения свойств
| Имя. | Значение и пример | Тип данных |
|---|---|---|
apiVersion |
2022-07-01 | Дата |
publisher |
Microsoft.Azure.KeyVault | строка |
type |
KeyVaultForLinux | строка |
typeHandlerVersion |
3.0 | INT |
pollingIntervalInS |
3600 | строка |
certificateStoreName |
Он игнорируется в Linux | строка |
linkOnRenewal |
false | boolean |
requireInitialSync |
true | boolean |
aclEnabled |
true | boolean |
certificateStoreLocation |
/var/lib/waagent/Microsoft.Azure.KeyVault.Store | строка |
observedCertificates |
[{...}, {...}] | строка массив |
observedCertificates/url |
"https://myvault.vault.azure.net/secrets/mycertificate1" | строка |
observedCertificates/certificateStoreLocation |
"/var/lib/waagent/Microsoft.Azure.KeyVault/app1" | строка |
observedCertificates/customSymbolicLinkName (необязательно) |
App1Cert1 | строка |
observedCertificates/acls (необязательно) |
"{...}, {...}" | строка массив |
authenticationSettings (необязательно) |
{...} | объект |
authenticationSettings/msiEndpoint |
http://169.254.169.254/metadata/identity | строка |
authenticationSettings/msiClientId |
c7373ae5-91c2-4165-8ab6-7381d6e75619 | строка |
loggingSettings (необязательно) |
{...} | объект |
loggingSettings/logger |
"fluentd" | строка |
loggingSettings/endpoint |
"tcp://localhost:24224" | строка |
loggingSettings/format |
"вперед" | строка |
loggingSettings/servicename |
"akvvm_service" | строка |
Развертывание шаблона
Расширения виртуальной машины 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": "3.0",
"autoUpgradeMinorVersion": true,
"enableAutomaticUpgrade": true,
"settings": {
"secretsManagementSettings": {
"pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
"requireInitialSync": <initial synchronization of certificates e..g: false>,
"aclEnabled": <enables/disables acls on defined certificates e.g.: true>,
"observedCertificates": <An array of KeyVault URIs that represent monitored certificates, including certificate store location and ACL permission to 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 certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
"acls": <Optional. An array of preferred acls with read access to certificate private keys. Example:
[
{
"user": "app1",
"group": "appGroup1"
},
{
"user": "service1"
}
]>
},
{
"url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
"certificateStoreName": <ignored on linux>,
"certificateStoreLocation": <The certificate store location, which currently works locally only. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
"acls": <Optional. An array of preferred acls with read access to certificate private keys. Example:
[
{
"user": "app2"
}
]>
}
]>
},
"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">
}
}
}
}
Упорядочение зависимостей расширений
Расширение виртуальной машины для 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 на имеющейся виртуальной машине или в масштабируемых наборах виртуальных машин.
- Развертывание расширения на виртуальной машине:
Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure PowerShell. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).
В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью PowerShell.
{
"secretsManagementSettings": {
"pollingIntervalInS": "3600",
"linkOnRenewal": true,
"aclEnabled": true,
"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",
"acls":
[
{
"user": "app2"
}
]
}
]},
"authenticationSettings": {
"msiEndpoint": "http://169.254.169.254/metadata/identity/oauth2/token",
"msiClientId": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
}
}
- Чтобы развернуть расширение на виртуальной машине, выполните следующие действия.
# Build settings
$settings = (get-content -raw ".\settings.json")
$extName = "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"
# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "3.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 "3.0" -Setting $settings
# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss
Развертывание с помощью Azure CLI
Для развертывания расширения виртуальной машины Key Vault на имеющейся виртуальной машине или в масштабируемом наборе виртуальных машин можно использовать Azure CLI.
- Развертывание расширения на виртуальной машине:
Расширение виртуальной машины Azure Key Vault можно развернуть с помощью Azure CLI. Сохраните параметры расширения виртуальной машины Key Vault в JSON-файл (settings.json).
В следующих фрагментах JSON приведены примеры параметров для развертывания расширения виртуальной машины Key Vault с помощью Azure CLI.
{
"secretsManagementSettings": {
"pollingIntervalInS": "3600",
"linkOnRenewal": true,
"aclEnabled": true,
"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",
"acls":
[
{
"user": "app2"
}
]
}
]},
"authenticationSettings": {
"msiEndpoint": "http://169.254.169.254/metadata/identity/oauth2/token",
"msiClientId": "xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
}
}
- Развертывание расширения на виртуальной машине
# Start the deployment
az vm extension set -n "KeyVaultForLinux" `
--publisher Microsoft.Azure.KeyVault `
-g "<resourcegroup>" `
--vm-name "<vmName>" `
--version 3.0 `
--enable-auto-upgrade true `
--settings "@settings.json"
- Чтобы развернуть расширение в масштабируемом наборе виртуальных машин, выполните следующие действия.
# Start the deployment
az vmss extension set -n "KeyVaultForLinux" `
--publisher Microsoft.Azure.KeyVault `
-g "<resourcegroup>" `
--vmss-name "<vmssName>" `
--version 3.0 `
--enable-auto-upgrade true `
--settings "@settings.json"
Ознакомьтесь со следующими ограничениями и требованиями.
- Ограничения Key Vault:
- оно должно существовать во время развертывания;
- Роль пользователя секретов Key Vault должна быть назначена Key Vault для удостоверения виртуальной машины.
Устранение неполадок и поддержка
Данные о состоянии развертываний расширения можно получить на портале 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 существуют локально на виртуальной машине и наиболее информативны при устранении неполадок. Вы можете использовать дополнительный раздел ведения журнала для интеграции с поставщиком ведения журнала с помощью fluentd
| Расположение | 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.
Кері байланыс
Жақында қолжетімді болады: 2024 жыл бойы біз GitHub Issues жүйесін мазмұнға арналған кері байланыс механизмі ретінде біртіндеп қолданыстан шығарамыз және оны жаңа кері байланыс жүйесімен ауыстырамыз. Қосымша ақпаратты мұнда қараңыз: https://aka.ms/ContentUserFeedback.
Жіберу және пікірді көру