適用於 Linux 的金鑰保存庫虛擬機器擴充功能

金鑰保存庫 VM 擴充功能可自動重新整理儲存在 Azure 金鑰保存庫中的憑證。 具體而言，此擴充功能會監視儲存於金鑰保存庫的觀察憑證清單。 在偵測到變更後，擴充功能會擷取並安裝對應的憑證。 本文件詳述適用於 Linux 的金鑰保存庫 VM 擴充功能所支援的平台、組態和部署選項。

作業系統

Key Vault VM 擴充功能支援下列 Linux 發行版本：

• Ubuntu 20.04, 22.04
• Azure Linux

注意

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 秘密使用者角色。 此角色會擷取秘密的憑證部分。 如需詳細資訊，請參閱下列文章：

  • Azure Key Vault 中的驗證
  • 使用 Azure RBAC 秘密、金鑰及憑證權限搭配 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

旗標 --version 2.0 是選擇性，因為預設會安裝最新版本。

• 如果 VM 有 v1.0 下載的憑證，刪除 v1.0 AKVVM 擴充功能不會刪除下載的憑證。 安裝 v2.0 之後，不會修改現有的憑證。 您必須刪除憑證檔案或變換憑證，以取得 VM 上具有完整鏈結的 PEM 檔案。

擴充功能結構描述

下列 JSON 顯示金鑰保存庫 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.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 憑證

重要

具有任何使用者指派的身分識別的 VM，需要 'authenticationSettings' 屬性。 即使您想要使用系統指派的身分識別，仍然需要此身分識別，否則 VM 擴充功能並不知道要使用的身分識別。 如果沒有此區段，具有使用者指派身分識別的 VM 會導致 Key Vault 擴充功能失敗，且無法下載憑證。 將 msiClientId 設定為要向 Key Vault 驗證的身分識別。

Azure 已啟用 Arc 的 VM 也需要此操作。 將 msiEndpoint 設定為 http://localhost:40342/metadata/identity。

屬性值

名稱	值 / 範例	資料類型
apiVersion	2022-07-01	date
publisher	Microsoft.Azure.KeyVault	string
type	KeyVaultForLinux	string
typeHandlerVersion	2.0	int
pollingIntervalInS	3600	string
certificateStoreName	Linux 上會予以忽略	string
linkOnRenewal	false	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	string
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	string
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	string

範本部署

也可以使用 Azure Resource Manager 範本部署 Azure VM 擴充功能。 部署一或多部需要部署後重新整理憑證的虛擬機器時，很適合使用範本。 此擴充功能可以部署到個別的 VM 或虛擬機器擴展集。 結構描述與組態對於這兩種範本類型都是通用的。

虛擬機器擴充功能的 JSON 組態必須在內嵌在範本的虛擬機器資源片段，具體來說，就是虛擬機器範本的 "resources": [] 物件，而若是虛擬機器擴展集，則會在 "virtualMachineProfile":"extensionProfile":{"extensions" :[] 物件下。

注意

VM 延伸模組會要求系統或使用者受控識別指派給金鑰保存庫進行驗證。 請參閱如何驗證 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 VM 延伸模組支援延伸模組排序。 根據預設，擴充功能會在輪詢開始時報告啟動成功。 不過，您可以將其設定為直到成功下載憑證的完整清單，再報告啟動成功。 如果其他延伸模組在開始之前相依於已安裝的憑證，則啟用此設定可讓這些延伸模組宣告 Key Vault 延伸模組的相依性。 這樣可防止這些延伸模組啟動，直到已安裝相依的所有憑證為止。 延伸模組會無限期地重試初始下載，並維持在 Transitioning 狀態。

若要開啟擴充功能相依性，請設定下列項目：

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

注意

使用此功能與建立系統指派身分識別的 ARM 範本不相容，並使用該身分識別更新 金鑰保存庫 存取原則。 這麼做會導致死結，因為保存庫存取原則必須等到所有延伸模組都啟動後才能更新。 您應該改為使用單一使用者指派的 MSI 身分識別，並在部署之前針對您的保存庫預先進行 ACL。

Azure PowerShell 部署

警告

PowerShell 用戶端通常會在 settings.json 中將 \ 新增至 "，這會導致 akvvm_service 失敗並發生錯誤：[CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell 可以用來將金鑰保存庫 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> \"] }}'
  

請留意下列限制/需求：

• 金鑰保存庫限制：
  • 部署時必須存在
  • 必須使用受控識別設定 VM/VMSS 身分識別的金鑰保存庫存取原則。 請參閱如何驗證 Key Vault 和指派 Key Vault 存取原則。

疑難排解與支援

使用 Azure PowerShell，就可以從 Azure 入口網站擷取有關擴充功能部署狀態的資料。 若要查看所指定 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 可以在數個殼層環境中執行，但格式稍有不同。 如果您使用 Azure CLI 命令看到非預期的結果，請參閱如何成功使用 Azure CLI。

記錄和組態

Key Vault VM 擴充功能記錄只會存在於 VM 本機上，而且在進行疑難排解時最能提供資訊。

Location	描述
/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 延伸模組服務的組態和二進位檔。

使用 Symlink

符號連結或 Symlink 是進階快速鍵。 若要避免監視資料夾並自動取得最新的憑證，您可以使用此符號連結 ([VaultName].[CertificateName]) 取得 Linux 上最新版本的憑證。

常見問題集

• 您可以設定的 observedCertificates 數量是否有限制？ 否，Key Vault VM 延伸模組沒有 observedCertificates 數目的限制。

支援

如果您在本文中有任何需要協助的地方，您可以連絡 MSDN Azure 和 Stack Overflow 論壇上的 Azure 專家。 或者，您可以提出 Azure 支援事件。 請移至 Azure 支援網站，然後選取 [取得支援]。 如需使用 Azure 支援的資訊，請參閱 Microsoft Azure 支援常見問題集。