适用于 Linux 的 Key Vault 虚拟机扩展

密钥保管库 VM 扩展可自动刷新 Azure 密钥保管库中存储的证书。 具体而言,该扩展会监视在密钥保管库中存储的观察到的证书列表。 扩展程序在检测到更改后会检索并安装相应的证书。 本文档详细介绍适用于 Linux 的 Key Vault VM 扩展支持的平台、配置和部署选项。

操作系统

Key Vault VM 扩展支持以下 Linux 发行版:

  • Ubuntu 20.04、22.04

注意

Key Vault VM 扩展会将证书下载到默认位置或 VM 扩展设置中“certStoreLocation”属性所提供的位置。 Key Vault VM 扩展会将文件夹权限更新为 700 (drwx------),即仅允许对文件夹所有者的“读取”、“写入”和“执行”权限

支持的证书内容类型

  • PKCS #12
  • PEM

先决条件

  • 具有证书的 Key Vault 实例。 请参阅创建 Key Vault

  • 在 VM/VMSS 上分配的托管标识

  • VM 和 Azure 虚拟机规模集托管标识的 Key Vault 范围级别的“Key Vault 机密用户”角色。 此角色可检索证书的机密部分。 有关详细信息,请参阅以下文章:

  • VMSS 应具有以下标识设置:"identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

  • AKV 扩展应具有此设置:"authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Key Vault VM 扩展版本

  • 用户可以选择将其 Key Vault VM 扩展版本升级到 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

版本 2.0 标志是可选的,因为默认情况下将安装最新版本。

  • 如果 VM 具有 v1.0 下载的证书,删除 v1.0 AKVVM 扩展将不会删除已下载的证书。 安装 v2.0 后,不会修改现有证书。 你需要删除证书文件或滚动更新证书,以获取 VM 上包含完整链的 PEM 文件。

扩展架构

以下 JSON 显示 Key Vault VM 代理扩展的架构。 该扩展不需要受保护的设置 - 其所有设置都被视为没有安全影响的信息。 该扩展需要受监视的密钥列表、轮询频率和目标证书存储。 具体而言:

    {
      "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.cn/secrets/mycertificate", "https://myvault.vault.azure.cn/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.cn/secrets/myCertName

这是因为 /secrets 路径会返回完整证书(包括私钥),但 /certificates 路径不会。 有关证书的详细信息可在此处找到:密钥保管库证书

重要

具有任何“用户分配的标识”的 VM 需要“authenticationSettings”属性。 即使你想使用系统分配的标识,这仍然是必需的;否则 VM 扩展将不知道使用哪个标识。 如果没有此部分,具有用户分配标识的 VM 将导致密钥保管库扩展失败并且无法下载证书。 将 msiClientId 设置为将对 Key Vault 进行身份验证的标识。

对于已启用 Azure Arc 的 VM,也是必需的。 将 msiEndpoint 设置为 http://localhost:40342/metadata/identity

属性值

名称 值/示例 数据类型
apiVersion 2022-07-01 date
publisher Microsoft.Azure.KeyVault 字符串
type KeyVaultForLinux 字符串
typeHandlerVersion 2.0 int
pollingIntervalInS 3600 字符串
certificateStoreName 它在 Linux 上被忽略 string
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync boolean
observedCertificates ["https://myvault.vault.azure.cn/secrets/mycertificate", "https://myvault.vault.azure.cn/secrets/mycertificate2"] 字符串数组
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

模板部署

可使用 Azure Resource Manager 模板部署 Azure VM 扩展。 部署需要部署后刷新证书的一个或多个虚拟机时,模板是理想选择。 可将该扩展部署到单个 VM 或虚拟机规模集。 架构和配置对于这两种模板类型通用。

必须将虚拟机扩展的 JSON 配置嵌套在该模板的虚拟机资源片段中,具体来说是嵌套在虚拟机模板的 "resources": [] 对象和 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 对象下的虚拟机规模集。

注意

VM 扩展需要分配有系统或用户托管标识,才能向 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.cn/secrets/mycertificate"
        }
      }
      }
    }

扩展依赖项排序

Key Vault VM 扩展支持扩展排序(如果已配置)。 默认情况下,扩展在轮询开始后立即报告启动成功。 但是,可以将其配置为等到成功下载证书的完整列表之后再报告成功启动。 如果其他扩展依赖于所安装的证书才能启动,则启用此设置将使那些扩展可以声明 Key Vault 扩展的依赖项。 这将阻止启动那些扩展,直到安装了其所依赖的所有证书为止。 扩展将一直重试初始下载,并保持 Transitioning 状态。

要启用扩展依赖项,请设置以下内容:

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

[注意] 使用此功能与 ARM 模板不兼容(该模板会创建系统分配的标识并使用该标识更新 Key Vault 访问策略)。 这样做将导致死锁,因为在所有扩展启动之前,无法更新保管库访问策略。 应改为在部署之前使用单个用户分配的 MSI 标识,并使用该标识对你的保管库进行预 ACL 操作。

Azure PowerShell 部署

警告

PowerShell 客户端通常会将 \ 添加到 settings.json 中的 ",这会导致 akvvm_service 失败,并出现错误:[CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

可以使用 Azure PowerShell,将 Key Vault VM 扩展部署到现有虚拟机或虚拟机规模集。

  • 在 VM 上部署该扩展:

        # 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 部署

可以使用 Azure CLI,将密钥保管库 VM 扩展部署到现有虚拟机或虚拟机规模集。

  • 在 VM 上部署该扩展:

       # 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 进行检索。 若要查看给定 VM 的扩展部署状态,请使用 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 可以在多个 shell 环境中运行,但格式略有变化。 如果 Azure CLI 命令出现意外结果,请参阅如何成功使用 Azure CLI

日志和配置

Key Vault VM 扩展日志仅存在于本地 VM 上,在进行故障排除时能提供最多信息。

位置 说明
/var/log/waagent.log 显示进行扩展更新的时间。
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* 检查 Key Vault VM 扩展服务日志,以确定 akvvm_service 服务和证书下载的状态。 可以在包含一个名为“证书文件名”的条目的文件中找到 PEM 文件的下载位置。 如果未指定 certificateStoreLocation,它会默认设置为“/var/lib/waagent/Microsoft.Azure.KeyVault.Store/”
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<最新版本>/config/* Key Vault VM 扩展服务的配置和二进制文件。

符号链接是高级快捷方式。 若要避免监视文件夹和自动获取最新证书,可以使用此符号链接 ([VaultName].[CertificateName]) 获取 Linux 上最新版本的证书。

常见问题

  • 可配置的 observedCertificates 数是否有限制? 没有,Key Vault VM 扩展对 observedCertificates 数没有限制。

支持

如果对本文中的任何观点存在疑问,可以联系 Azure 支持上的 Azure 专家。 或者,你也可以提出 Azure 支持事件。 请转到 Azure 支持站点提交请求。 有关使用 Azure 支持的信息,请阅读 Azure 支持常见问题