Linux 適用的 Azure Key Vault 虛擬機器擴充功能

Azure Key Vault 虛擬機（VM）擴充功能會自動刷新存放在 Azure key vault 中的憑證。 此擴充功能會監視儲存於金鑰保存庫的觀察憑證清單。 當擴充套件偵測到變更時，會擷取並安裝相應的憑證。 本文說明 Linux 版 金鑰保存庫 VM 擴充套件所支援的平台、設定及部署選項。

作業系統

Linux 版 金鑰保存庫 VM 擴充套件支援以下發行版，適用於 AMD64 與 ARM64：

• Ubuntu 24.04
• Azure Linux 3.0 同 4.0
• Red Hat Enterprise Linux （RHEL） 9

支援的憑證內容類型

金鑰保存庫 VM 擴充功能支援下列憑證內容類型：

• PKCS #12
• PEM

特徵

Linux 4.x 版的 金鑰保存庫 VM 擴充功能：

• 安裝每個憑證的兩個最新版本。
• 將每個憑證安裝為拆分檔案：一個完整憑證鏈 .pem 檔案，以及另一個獨立的 .keyid 私鑰檔案；兩者各自寫入為具版本編號的檔案，並建立指向最新版本的穩定符號連結。
• 在安裝攜帶 TLS 伺服器認證擴展金鑰使用（EKU）的憑證前，執行憑證鏈驗證。 驗證為失敗開啟：若因暫時性網路問題無法完成驗證，仍會安裝憑證。 沒有伺服器認證 EKU 的憑證則不受此檢查。
• 套用 POSIX ACL 授權已設定的使用者和群組對私鑰的讀取權限。 ACL 強制執行一律啟用。
• 支援選擇性每個憑證驗證覆寫，讓個別觀察到的憑證可使用與擴充功能預設值不同的受控身分識別向 金鑰保存庫 進行驗證。 欲了解更多資訊，請參閱 擴充架構。
• 支援透過 Fluentd 進行的 VM 擴充功能記錄整合。 如需更多資訊，請參閱使用 Fluentd 進行記錄。

從 3.0 升級

如果你是從 3.0 更新，以下功能會被更改或移除。

一般性突發變更：

• pollingIntervalInS 現今限制在5至60分鐘之間。 預設情況下，該擴充功能每小時輪詢一次。
• requireInitialSync 已被移除。 只有當擴充功能安裝了所有已設定的憑證時，才會回報成功。
• 你已經無法設定特定版本的憑證了。 觀察到的憑證網址必須是無版本的。
• 舊有結構（其中 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 上會被忽略，且沒有影響。

先決條件

請檢視以下使用 金鑰保存庫 VM 擴充套件 Linux 的前提條件：

• 具有憑證的 Azure Key Vault 實例。 如需詳細資訊，請參閱 使用 Azure 入口網站建立金鑰保存庫。

• 具有指派 受控識別的 VM。

• 將金鑰保存庫範圍層級的金鑰保存庫秘密使用者角色，指派給 VM 或 Azure 虛擬機器擴展集的受控身分識別。 此角色會擷取憑證的私密部分。 如需詳細資訊，請參閱下列文章：

  • Azure Key Vault 中的驗證
  • 搭配 Azure Key Vault 使用 Azure RBAC 秘密、密鑰和憑證許可權
  • 金鑰保存庫的範圍角色分配

• 使用下列 identity 組態設定虛擬機器擴展集：

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

• 請以以下authenticationSettings設定配置 金鑰保存庫 VM 擴充功能：

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

擴展架構

下列 JSON 顯示金鑰保存庫 VM 擴充功能的結構描述。 在考慮架構實作選項之前，請先檢閱下列重要注意事項。

• 延伸模組不需要受保護的設定。 所有設定皆為公開資訊。

• 觀察到的憑證網址必須使用格式 https://myVaultName.vault.azure.net/secrets/myCertName。

  此表單是因為 /secrets 路徑會回傳完整憑證，包括私鑰，但 /certificates 路徑本身不會。 如需憑證的詳細資訊，請參閱 Azure Key Vault 密鑰、秘密和憑證概觀。 你無法指定證書的特定版本。

• URL 主機必須是已認可的 Azure Key Vault 主機。

• authenticationSettings此屬性對於擁有任何使用者指派身份的虛擬機，以及啟用 Azure Arc 的虛擬機都是必要的。

  使用系統指派身份時，請省略此特性。 對於 Azure Arc 啟用的 VMS，請設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.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 Resource Manager （ARM） 範本部署 Azure 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.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"
         }
      }
   }
}

擴充套件自動升級

金鑰保存庫 VM 擴充功能支援 Azure 中虛擬機器與擴展套件的自動升級。 當你在上述範例中將 autoUpgradeMinorVersion 和 enableAutomaticUpgrade 屬性設為 true 時，Azure 會自動將延伸模組維持在最新狀態。

擴充功能相依性排序

金鑰保存庫 VM 擴充套件支援擴充套件相依排序。 擴充套件在下載並安裝所有憑證後會回報成功啟動。

如果你使用其他需要安裝憑證才能啟動的擴充功能，你可以使用擴充套件依賴排序來宣告對 金鑰保存庫 VM 擴充功能的依賴。

啟動時，金鑰保存庫虛擬機擴充功能會重複下載與安裝憑證最多 25 次，且回退時間逐漸增加，期間會維持在 Transitioning 狀態。 如果重試次數用盡，擴充功能會 回報錯誤狀態 。 成功安裝所有憑證之後，金鑰保存庫 VM 擴充功能會回報成功的啟動。

欲了解更多關於建立擴充套件間相依性的資訊，請參閱 虛擬機器擴展集 中的序列擴充配置。

Azure PowerShell 部署

使用 Azure PowerShell 部署 Azure Key Vault VM 擴充功能。 將 VM 擴充金鑰保存庫設定存成 JSON 檔案（settings.json）。

以下 JSON 片段提供了使用 PowerShell 部署 金鑰保存庫 VM 擴充功能的範例設定。

{
   "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"
   }
}

在 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 Key Vault VM 擴充功能。 將 VM 擴充金鑰保存庫設定存成 JSON 檔案（settings.json）。

以下 JSON 片段提供了使用 Azure CLI 部署 金鑰保存庫 VM 擴充功能的範例設定。

{
   "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"
   }
}

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

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

故障排除

利用這些建議來排查部署問題。

檢查常見問題

觀察到的憑證數目是否有限制？

No. 金鑰保存庫 VM 擴充功能不會限制觀察到的憑證數目（observedCertificates）。

憑證安裝的預設位置是什麼？

如果你不指定 certificateStoreLocation，擴充功能會將憑證寫入 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/。

我該如何強制延長申請新的憑證？

重新啟動akvvm_service服務（顯示名稱 金鑰保存庫 VM Extension）。

我該如何為特定證書使用不同的身份？

將目標為 msiClientId 的 authenticationOverride 物件新增至 observedCertificates 中該憑證的項目。 沒有覆寫的憑證使用頂部層級 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 本機上。 檢閱記錄詳細數據以協助進行疑難解答。

Linux 上的憑證安裝

Linux 的 金鑰保存庫 VM 擴充功能會將憑證安裝為 PEM 檔案。 當擴充套件從 金鑰保存庫 下載憑證時，它會：

1. 根據設定 certificateStoreLocation 建立一個儲存資料夾。 如果你沒有指定這個設定，位置預設為 /var/lib/waagent/Microsoft.Azure.KeyVault.Store/。
2. 將憑證鏈（先是葉憑證，接著是中繼憑證，若 金鑰保存庫 中有根憑證則也包含在內）寫入版本化的完整鏈結 .pem 檔案，並將對應的私密金鑰寫入版本化的 .keyid 檔案。
3. 根據設定中指定的私鑰 acls 套用 POSIX ACL，授予列出的使用者與群組讀取權限。 檔案僅限擁有者存取。
4. 建立或更新一個穩定的符號連結（<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強制執行一律啟用，目前授予讀取權限。

憑證更新

當憑證在 金鑰保存庫 中更新時，擴充功能會在下一次輪詢中自動執行以下操作：

1. 下載新的憑證版本。
2. 寫入新的、已加上版本號的 .pem 和 .keyid 檔案。
3. 更新穩定符號連結以指向新版本，使現有的應用程式路徑繼續解析為最新憑證。

取得支援

Microsoft 僅支援 金鑰保存庫 VM 擴充的 3.0 及以後版本。 如果你使用的是版本 1.0，請先升級到最新版本再申請支援。

請使用以下其他選項來協助解決部署問題：

• 如需協助，請聯絡Microsoft Q&A中的Azure專家。

• 如果你在網站上找不到答案，可以發問徵求 Microsoft 或其他社群成員的意見。

• 您也可以連絡 Microsoft 支援服務。 有關使用 Azure 支援 的資訊，請參見 如何建立Azure 支援請求。