适用于 Linux 的Azure 密钥保管库虚拟机扩展

Azure 密钥保管库虚拟机（VM）扩展会自动刷新存储在Azure key vault中的证书。该扩展会监视 Key Vault 中存储的已观察到的证书列表。当扩展检测到更改时，它会检索并安装相应的证书。本文介绍适用于 Linux 的密钥保管库 VM 扩展支持的平台、配置和部署选项。

注意

尝试 VM 辅助，以便更快地进行诊断。建议运行 VM assist for Windows 或 VM assist for Linux。这些基于脚本的诊断工具可帮助你识别影响 Azure VM 来宾代理和整体 VM 运行状况的常见问题。

如果在联系支持人员之前遇到虚拟机的性能问题，请运行这些工具。

操作系统

适用于 Linux 的密钥保管库 VM 扩展支持 AMD64 和 ARM64 上的以下分发版：

Ubuntu 24.04
Azure Linux 3.0 和 4.0

注意

该扩展在安装时会从 /etc/os-release 选择特定于发行版的二进制文件。在任何其他发行版上安装都会失败，并且扩展状态中会显示“不支持该发行版”错误。

支持的证书内容类型

密钥保管库 VM 扩展支持以下证书内容类型：

PKCS #12
PEM

注意

密钥保管库 VM 扩展会将所有证书下载到在 VM 扩展设置的属性中指定的certificateStoreLocation位置，或者在未指定证书时下载到默认存储位置/var/lib/waagent/Microsoft.Azure.KeyVault.Store/。

特点

适用于 Linux 版本 4.x 的密钥保管库 VM 扩展：

安装每个证书的两个最新版本。
将每个证书安装为拆分文件：一个全链 .pem 文件和一个单独的 .keyid 私钥文件，每个证书都作为版本控制文件写入，其中包含指向最新版本的稳定符号链接。
在安装携带 TLS 服务器身份验证扩展密钥用法（EKU）的任何证书之前执行证书链验证。验证采用故障开放机制：如果由于暂时的网络问题而无法完成验证，证书仍会被安装。没有服务器身份验证 EKU 的证书不受此检查的约束。
应用 POSIX ACL 以授予配置的用户和组对私钥的读取访问权限。 ACL 强制执行始终启用。
支持可选的按证书身份验证替代，允许单个观察到的证书使用与扩展默认值不同的托管标识密钥保管库进行身份验证。有关详细信息，请参阅扩展架构。
支持通过 Fluentd 实现 VM 扩展日志记录集成。有关详细信息，请参阅使用 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 上忽略，不起作用。

注意

从以前的扩展版本升级不会删除已下载到磁盘的证书。此外，4.x 使用不同的文件名格式，因此任何现有文件保持不变。

先决条件

查看以下使用适用于 Linux 的密钥保管库 VM 扩展的先决条件：

具有证书的 Azure 密钥保管库实例。有关详细信息，请参阅使用 Azure 门户创建密钥保管库。
具有分配的托管标识的 VM。
将 密钥保管库机密用户 角色在密钥保管库作用域级别分配给 VM 或 Azure 虚拟机规模集的托管标识。此角色检索证书的机密部分。有关详细信息，请参阅以下文章：

使用以下identity配置虚拟机规模集：

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

使用以下authenticationSettings配置来配置密钥保管库 VM 扩展：

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

注意

还可以使用旧的访问策略权限模型提供对 VM 和虚拟机规模集的访问权限。此方法需要一个对机密具有获取和列出权限的策略。有关详细信息，请参阅分配密钥保管库访问策略。

扩展架构

以下 JSON 显示了密钥保管库 VM 扩展的架构。在考虑架构实现选项之前，请查看以下重要说明。

扩展不需要受保护的设置。所有设置均为公开信息。
观察到的证书 URL 必须使用表单 https://myVaultName.vault.azure.cn/secrets/myCertName。

此表单是必需的，因为 /secrets 路径返回完整证书，包括私钥，但 /certificates 路径不返回。有关证书的详细信息，请参阅 Azure 密钥保管库密钥、机密和证书概述。不能指定证书的特定版本。
URL 的主机名必须是已识别的 Azure 密钥保管库主机名。
对于具有任何用户分配标识的 VM 和启用Azure Arc的 VM，此属性authenticationSettings是必需的。

使用系统分配的标识时省略此属性。对于已启用 Azure Arc 的 VM，请将 msiEndpoint 设置为 http://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.cn/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.cn/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 架构包括以下属性。

名称	值/示例	数据类型
`apiVersion`	2025-04-01	日期
`publisher`	Microsoft.Azure.KeyVault	字符串
`type`	KeyVaultForLinux	字符串
`typeHandlerVersion`	"4.0"	字符串
`pollingIntervalInS`（可选）	“3600”（限制在 300-3600 之间）	字符串
`certificateStoreLocation`（可选）	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	字符串
`observedCertificates`	[{...}，{...}]	数组
`observedCertificates/url`	“https://myvault.vault.azure.cn/secrets/mycertificate"	字符串
`observedCertificates/certificateStoreLocation`（可选）	“/var/lib/waagent/Microsoft.Azure.KeyVault/app1”	字符串
`observedCertificates/acls`（可选）	[{“user”： “app1”， “group”： “appGroup1”}]	对象数组
`observedCertificates/authenticationOverride`（可选）	{“msiClientId”： “00001111-aaaa-2222-bbbb-3333cccc4444”}	对象
`authenticationSettings/msiEndpoint`	“http://169.254.169.254/metadata/identity"	字符串
`authenticationSettings/msiClientId`	“00001111-aaaa-2222-bbbb-3333cccc4444”	字符串

注意

架构接受 certificateStoreName 兼容性，但 Linux 会忽略它。如果未指定 certificateStoreLocation 证书，系统将使用顶级 secretsManagementSettings.certificateStoreLocation证书，如果未设置，则使用默认值 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/。

模板部署

使用 Azure 资源管理器（ARM）模板部署Azure VM 扩展。部署需要部署证书后刷新的一个或多个虚拟机时，模板是理想的选择。可以将扩展部署到单个 VM 或虚拟机规模集实例。架构和配置对于这两种模板类型通用。

密钥保管库扩展的 JSON 配置嵌套在 VM 或虚拟机规模集模板中。对于 VM 资源扩展，该配置嵌套在 "resources": [] 虚拟机对象下。对于虚拟机规模集实例扩展，该配置嵌套在 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 对象下。

以下 JSON 代码片段提供了密钥保管库 VM 扩展的 ARM 模板部署的示例设置。

{
   "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.cn/secrets/mycertificate1",
                    "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
                    "acls": [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]
                },
                {
                    "url": "https://<examplekv>.vault.azure.cn/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"
         }
      }
   }
}

扩展自动升级

密钥保管库 VM 扩展支持Azure中虚拟机和规模集的自动扩展升级。当你将前面示例中的 autoUpgradeMinorVersion 和 enableAutomaticUpgrade 属性设置为 true 时，Azure 会自动使扩展保持最新状态。

扩展依赖项排序

密钥保管库 VM 扩展支持扩展依赖项排序。扩展会在下载并安装所有证书后报告成功启动。

如果在开始之前使用其他需要安装证书的扩展，则可以使用扩展依赖项排序来声明对密钥保管库 VM 扩展的依赖项。

启动时，密钥保管库 VM 扩展会重试多达 25 次下载和安装证书，并且在每次重试之间增加后退时间，在此期间它仍处于 Transitioning 状态。如果重试次数已用尽，扩展会报告错误状态。成功安装所有证书后，密钥保管库 VM 扩展会报告成功启动。

有关在扩展之间设置依赖项的详细信息，请参阅虚拟机规模集中的序列扩展预配。

重要

扩展依赖项排序功能与 ARM 模板不兼容（该模板会创建系统分配的标识并使用该标识更新密钥保管库访问策略）。如果尝试在此场景中使用该功能，则会发生死锁，因为密钥保管库访问策略只有在所有扩展启动后才能更新。而是使用 单个用户分配的托管标识 ，并在部署之前授予该标识对密钥保管库的访问权限。

Azure PowerShell 部署

使用 Azure PowerShell 部署Azure 密钥保管库 VM 扩展。将密钥保管库 VM 扩展设置保存到 JSON 文件 (settings.json)。

警告

PowerShell 客户端通常会在 settings.json 中于 " 之前添加 \。这种行为会导致 akvvm_service 因报错 [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object. 而失败。使用Azure CLI，或将设置作为原始字符串传递，如以下示例所示。

以下 JSON 代码片段提供了使用 PowerShell 部署密钥保管库 VM 扩展的示例设置。

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "observedCertificates": [
         {
            "url": "https://<examplekv>.vault.azure.cn/secrets/mycertificate1",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
            "acls": [
               { "user": "app1", "group": "appGroup1" },
               { "user": "service1" }
            ]
         },
         {
            "url": "https://<examplekv>.vault.azure.cn/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"
   }
}

在 VM 上部署

# 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 CLI部署Azure 密钥保管库 VM 扩展。将密钥保管库 VM 扩展设置保存到 JSON 文件 (settings.json)。

以下 JSON 代码片段提供了使用 Azure CLI 部署密钥保管库 VM 扩展的示例设置。

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "observedCertificates": [
         {
            "url": "https://<examplekv>.vault.azure.cn/secrets/mycertificate1",
            "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
            "acls": [
               { "user": "app1", "group": "appGroup1" },
               { "user": "service1" }
            ]
         },
         {
            "url": "https://<examplekv>.vault.azure.cn/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"
   }
}

在 VM 上部署

# 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"

Tip

如果扩展部署失败，可能需要先删除现有扩展，然后再重新安装正确的版本。 Azure不允许扩展降级，因此可能需要先删除错误的扩展：

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

使用 Fluentd 进行日志记录

密钥保管库 VM 扩展可以将日志转发到 Fluentd 日志收集器。请确保日志收集器正在运行，并监听你在设置中指定的端点。

将以下部分添加到扩展设置：

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

名称	值/示例	数据类型
`loggingSettings/logger`	“fluentd”	字符串
`loggingSettings/endpoint`	“unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket”或“tcp://localhost:24224”	字符串
`loggingSettings/format`	"前进"	字符串
`loggingSettings/servicename`	“akvvm_service”	字符串

故障排查

使用这些建议排查部署问题。

查看常见问题

观察到的证书数量有限制吗？

No. 密钥保管库 VM 扩展不会限制观察到的证书数（observedCertificates）。

安装证书的默认位置是什么？

如果不指定 certificateStoreLocation，扩展会将证书写入 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/。

如何强制让扩展拉取新的证书？

重启 akvvm_service 服务（显示名称为 密钥保管库 VM Extension）。

如何为特定证书使用不同的身份？

在observedCertificates中，向该证书的条目添加一个目标为msiClientId的authenticationOverride对象。不使用替代的证书使用顶级 authenticationSettings证书。

查看扩展状态

在 Azure 门户中或使用 PowerShell 或 Azure CLI 检查扩展部署的状态。

若要查看给定 VM 的扩展部署状态，请运行以下命令。

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 可以在多个 shell 环境中运行，但格式略有变化。如果 Azure CLI 命令出现意外结果，请参阅如何成功使用 Azure CLI。

查看日志和配置

密钥保管库 VM 扩展日志仅存在于 VM 本地。查看日志详细信息以帮助进行故障排除。

日志文件	说明
`/var/log/waagent.log`	显示扩展更新的时间。
`/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*`	显示 `akvvm_service` 服务和证书下载的状态。 PEM 文件下载位置显示在名为证书文件名的条目中。
`/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/*`	密钥保管库 VM 扩展服务的配置和二进制文件。

Linux 上的证书安装

适用于 Linux 的密钥保管库 VM 扩展将证书安装为 PEM 文件。当扩展从密钥保管库下载证书时，它会：

根据 certificateStoreLocation 设置创建存储文件夹。如果未指定此设置，则位置默认为 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/。
将证书链（叶证书、中间证书，以及根证书（如果密钥保管库中存在））写入带版本的完整证书链 .pem 文件，并将相应的私钥写入带版本的 .keyid 文件。
根据 acls 配置中指定的值将 POSIX ACL 应用于私钥，该密钥授予对列出的用户和组的读取访问权限。否则，文件仅所有者可访问。
创建或更新指向最新版本的证书的稳定符号链接（<vaultname>.<certname>.pem 和 <vaultname>.<certname>.keyid）。链接总是会发生。

默认证书存储位置

如果未指定位置，扩展会将证书安装到 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ 下。该扩展在 Linux 上忽略 certificateStoreName 。

证书输出文件

对于保管库 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 强制执行始终处于启用状态，当前授予读访问权限。

证书续订

当证书在密钥保管库中续订时，该扩展会在下一轮轮询中自动执行以下操作：

下载新的证书版本。
写入新的带版本信息的 .pem 和 .keyid 文件。
更新稳定符号链接以指向新版本，以便现有应用程序路径继续解析为最新的证书。

获取支持

如果在阅读本文时需要更多帮助，可以联系 Azure 支持的 Azure 专家。或者，你也可以提出 Azure 支持事件。请转到 Azure 支持站点提交请求。有关使用 Azure 支持的信息，请阅读 Azure 支持常见问题。

Last updated on 2026-09-04

适用于 Linux 的Azure 密钥保管库虚拟机扩展

操作系统

支持的证书内容类型

特点

从 3.0 升级

先决条件

扩展架构

属性值

模板部署

扩展自动升级

扩展依赖项排序

Azure PowerShell 部署

在 VM 上部署

在虚拟机规模集实例上部署

Azure CLI 部署

在 VM 上部署

在虚拟机规模集实例上部署

使用 Fluentd 进行日志记录

故障排查

查看常见问题

观察到的证书数量有限制吗？

安装证书的默认位置是什么？

如何强制让扩展拉取新的证书？

如何为特定证书使用不同的身份？

查看扩展状态

查看日志和配置

Linux 上的证书安装

默认证书存储位置

证书输出文件

证书访问控制

证书续订

获取支持

Recursos adicionais