共用方式為

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

  • 發行項

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

作業系統

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

注意

金鑰保存庫 VM 擴充功能會將憑證下載到預設位置或 VM 擴充功能設定中 「certStoreLocation」 屬性所提供的位置，或個別憑證設定 （第 3 版）。 Key Vault VM 擴充功能會將資料夾權限更新為 700 (drwx------)，僅允許資料夾擁有者的讀取、寫入和執行權限

支援的憑證內容類型

  • PKCS #12
  • PEM

3.0+ 版中的更新

Linux 金鑰保存庫 VM 擴充功能 3.0+ 版會新增對下列功能的支援：

必要條件

  • 具有憑證的 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 擴充功能版本

  • 用戶可以選擇將其現有的 金鑰保存庫 VM 擴充功能版本升級至較新版本。

  • 如果您想要升級至較新版本，您必須先刪除舊版，然後安裝較新版本。

  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 是選擇性的，因為預設會安裝最新版本。

  • 如果 VM 已由舊版下載憑證，則刪除 VM 擴充功能並不會刪除下載的憑證。 安裝較新版本之後，不會修改現有的憑證。 您必須刪除憑證檔案或變換憑證，以取得 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": "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 憑證

重要

具有任何使用者指派的身分識別的 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 字串
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 (選用) {...} object
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity 字串
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 字串
loggingSettings (選用) {...} object
loggingSettings/logger “fluentd” 字串
loggingSettings/endpoint “tcp://localhost:24224” 字串
loggingSettings/format “forward” 字串
loggingSettings/servicename “akvvm_service” 字串

範本部署

也可以使用 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": "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 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 上部署擴充功能：

您可以使用 Azure PowerShell 來部署 Azure Key Vault VM 擴充功能。 將 Key Vault VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

下列 JSON 程式碼片段提供使用 PowerShell 部署 Key Vault VM 擴充功能的範例設定。

{
   "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 部署

Azure CLI 可以用來將金鑰保存庫 VM 擴充功能部署到現有的虛擬機器或虛擬機器擴展集。

  • 若要在 VM 上部署擴充功能：

您可以使用 Azure CLI 來部署 Azure Key Vault VM 擴充功能。 將 Key Vault VM 擴充功能設定儲存至 JSON 檔案 (settings.json)。

下列 JSON 程式碼片段提供使用 Azure CLI 部署 Key Vault VM 擴充功能的範例設定。

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

請留意下列限制/需求：

  • 金鑰保存庫限制：
    • 部署時必須存在
    • 金鑰保存庫 秘密使用者角色必須指派給 VM 身分識別的 金鑰保存庫

疑難排解與支援

使用 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。

記錄和組態

金鑰保存庫 VM 擴充功能記錄存在於本機 VM 上，而且在疑難解答方面最具資訊性。 您可以使用選擇性的記錄區段，透過 與記錄提供者整合 fluentd

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

常見問題集

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

支援

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