ملحق Key Vault Virtual Machine ل Linux

يوفر ملحق الجهاز الظاهري لـ Key Vault تحديثا تلقائيا للشهادات المخزنة في Azure Key Vault. على وجه التحديد، يراقب الملحق قائمة بالشهادات المرصودة المخزنة في مخازن المفاتيح. يسترد الملحق الشهادات المقابلة ويثبتها بعد الكشف عن تغيير. يوضح هذا المستند بالتفصيل الأنظمة الأساسية والتكوينات وخيارات التوزيع المدعومة لملحق الأجهزة الظاهرية لـ Key Vault في Linux.

نظام التشغيل

يدعم ملحق جهاز ظاهري لـ Key Vault توزيعات Linux التالية:

• Ubuntu 20.04، 22.04
• Azure Linux

إشعار

يقوم ملحق جهاز ظاهري لـ Key Vault بتنزيل الشهادات في الموقع الافتراضي أو إلى الموقع الذي توفره الخاصية "certStoreLocation" في إعدادات ملحق الجهاز الظاهري. يقوم ملحق الجهاز الظاهري ل Key Vault بتحديث إذن المجلد إلى 700 (drwx------) مما يسمح بإذن القراءة والكتابة والتنفيذ لمالك المجلد فقط

أنواع محتويات الشهادات المعتمدة

• PKCS #12
• PEM

المتطلبات الأساسية

• مثيل Key Vault مع شهادة. راجع إنشاء Key Vault

• الهوية المدارة المعينة على VM/VMSS

• دور مستخدم Key Vault Secrets على مستوى نطاق Key Vault للأجهزة الظاهرية والهوية المدارة لمجموعات مقياس الجهاز الظاهري Azure. يسترد هذا الدور جزء البيانات السرية من الشهادة. لمزيد من المعلومات، راجع المقالات التالية:

  • المصادقة في 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

• يمكن للمستخدمين اختيار ترقية إصدار ملحق الجهاز الظاهري ل Key Vault لاستخدام 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 اختياري لأنه يتم تثبيت أحدث إصدار بشكل افتراضي.

• إذا كان الجهاز الظاهري يحتوي على شهادات تم تنزيلها بواسطة v1.0، فإن حذف ملحق V1.0 AKVVM لا يؤدي إلى حذف الشهادات التي تم تنزيلها. بعد تثبيت الإصدار 2.0، لا يتم تعديل الشهادات الموجودة. ستحتاج إلى حذف ملفات الشهادة أو ترحيل الشهادة للحصول على ملف PEM مع سلسلة كاملة على الجهاز الظاهري.

مخطط الملحق

يعرض JSON التالي المخطط الخاص بملحق الجهاز الظاهري لـ Key Vault. لا يتطلب الملحق إعدادات محمية - تعتبر جميع إعداداته معلومات دون تأثير أمني. يتطلب الملحق قائمة بالبيانات السرية المراقبة وتكرار التحقق ومخزن الشهادات الوجهة. على وجه التحديد:

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

هام

خاصية "المصادقة الإعدادات" مطلوبة للأجهزة الظاهرية مع أي هويات معينة من قبل المستخدم. حتى إذا كنت ترغب في استخدام هوية معينة من قبل النظام، فلا يزال هذا مطلوبا وإلا فإن ملحق الجهاز الظاهري لا يعرف الهوية التي يجب استخدامها. بدون هذا القسم، سينتج عن الجهاز الظاهري الذي له هويات معينة من قبل المستخدم فشل ملحق Key Vault وعدم القدرة على تنزيل الشهادات. عيّن msiClientId إلى الهوية التي ستتم مصادقتها إلى Key Vault.

ومطلوب أيضًا للأجهزة الظاهرية التي تمكن Azure Arc. عيّن msiEndpoint إلى http://localhost:40342/metadata/identity.

قيم Property

الاسم	القيمة / المثال	نوع البيانات
apiVersion	2022-07-01	date
publisher	Microsoft.Azure.KeyVault	سلسلة
النوع	KeyVaultForLinux	سلسلة
typeHandlerVersion	2.0	العدد الصحيح
pollingIntervalInS	3600	سلسلة
certificateStoreName	يتم تجاهله على Linux	سلسلة
linkOnRenewal	true	boolean
certificateStoreLocation	/var/lib/waagent/Microsoft.Azure.KeyVault.Store	سلسلة
requireInitialSync	صحيح	boolean
observedCertificates	["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]	صفيف سلسلة
msiEndpoint	http://169.254.169.254/metadata/identity	سلسلة
msiClientId	c7373ae5-91c2-4165-8ab6-7381d6e75619	سلسلة

توزيع قالب

يمكن توزيع ملحقات جهاز Azure الظاهري باستخدام قوالب Azure Resource Manager. تعد القوالب مثالية عند توزيع جهاز ظاهري واحد أو أكثر يشترط تحديث الشهادات بعد التوزيع. يمكن توزيع الملحق على الأجهزة الظاهرية الفردية أو مجموعات تغيير سعة الجهاز الظاهري. يشيع المخطط والتكوين في كلا النوعين من القوالب.

يجب أن يكون تكوين JSON لملحق الجهاز الظاهري متداخلاً داخل جزء مورد الجهاز الظاهري من القالب، وتحديدًا عنصر "resources": [] لقالب الجهاز الظاهري وفي حالة تعيين مقياس الجهاز الظاهري ضمن العنصر "virtualMachineProfile":"extensionProfile":{"extensions" :[].

إشعار

سيتطلب ملحق الجهاز الظاهري تعيين هوية مُدارة بواسطة النظام أو المستخدم للمصادقة على 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.net/secrets/mycertificate"
        }
      }
      }
    }

ترتيب تبعية الملحق

يدعم ملحق الجهاز الظاهري لـ Key Vault ترتيب الملحقات إذا تم تكوينه. بشكل افتراضي، يبلغ الملحق عن بدء التشغيل الناجح بمجرد بدء الاستقصاء. ومع ذلك، يمكنك تكوينه للانتظار حتى يقوم بتنزيل القائمة الكاملة للشهادات بنجاح قبل الإبلاغ عن بداية ناجحة. إذا كانت الملحقات الأخرى تعتمد على الشهادات المثبتة قبل بدء تشغيلها، فسيسمح تمكين هذا الإعداد لهذه الملحقات بتعريف التبعية على ملحق Key Vault. سيؤدي ذلك إلى منع هذه الملحقات من البدء حتى يتم تثبيت جميع الشهادات التي تعتمد عليها. سيعيد الملحق محاولة التنزيل الأولي إلى أجل غير مسمى، ويبقى في حالة Transitioning.

لتشغيل تبعية الامتداد، قم بتعيين ما يلي:

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

إشعار

لا يتوافق استخدام هذه الميزة مع قالب ARM الذي ينشئ هوية معينة للنظام ويقوم بتحديث نهج الوصول إلى Key Vault بتلك الهوية. سيؤدي القيام بذلك إلى حالة توقف تام، حيث لا يمكن تحديث نهج الوصول إلى المخزن حتى تبدأ جميع الملحقات. يجب عليك بدلاً من ذلك استخدام هوية MSI المعينة من قِبل مستخدم واحد والتحكم بوصول المخازن مسبقًا بتلك الهوية قبل التوزيع.

توزيع Azure PowerShell

تحذير

غالبًا ما يضيف عملاء PowerShell \ إلى " في settings.json مما سيؤدي إلى فشل akvvm_service بسبب الخطأ: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

يمكن استخدام Azure PowerShell لتوزيع ملحق الجهاز الظاهري لـ Key Vault إلى جهاز ظاهري موجود أو مجموعة تغيير سعة الجهاز الظاهري.

• لتوزيع الملحق على جهاز ظاهري:

      # 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 لتوزيع ملحق الجهاز الظاهري لـ Key Vault إلى جهاز ظاهري موجود أو مجموعة تغيير سعة الجهاز الظاهري.

• لتوزيع الملحق على جهاز ظاهري:

     # 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> \"] }}'
  

يرجى الانتباه إلى القيود/المتطلبات التالية:

• قيود Key Vault:
  • يجب أن تكون موجودة في وقت التوزيع
  • يجب تعيين نهج الوصول إلى Key Vault لهوية جهاز ظاهري/VMSS باستخدام هوية مُدارة. راجع كيفية المصادقة على Key Vaultوتعيين نهج الوصول إلى Key Vault.

استكشاف الأخطاء وإصلاحها والدعم

يمكن استرداد البيانات حول حالة عمليات توزيع الملحقات من مدخل Azure وباستخدام Azure PowerShell. لمشاهدة حالة توزيع ملحقات جهاز ظاهري محدد، قم بتشغيل الأمر التالي باستخدام 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 محليًا فقط على الجهاز الظاهري، وهي أكثر إفادة عندما يتعلق الأمر باستكشاف الأخطاء وإصلاحها.

‏‏الموقع	‏‏الوصف
/var/log/waagent.log	يعرض وقت حدوث تحديث للملحق.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/*	افحص سجلات خدمة ملحق جهاز ظاهري لـ Key Vault لتحديد حالة خدمة akvvm_service وتنزيل الشهادة. يمكنك العثور على موقع تنزيل ملفات PEM في الملفات مع إدخال يسمى اسم ملف الشهادة. إذا لم يتم تحديد certificateStoreLocation، فسيتم تعيينه افتراضيًا على /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/*	التكوين والثنائيات لخدمة ملحق الجهاز الظاهري لـ Key Vault.

استخدام Symlink

الارتباطات الرمزية أو Symlinks هي في الأساس اختصارات متقدمة. لتجنب مراقبة المجلد والحصول على أحدث شهادة تلقائيًا، يمكنك استخدام symlink هذا ([VaultName].[CertificateName]) للحصول على أحدث إصدار من الشهادة على Linux.

الأسئلة المتداولة

• هل هناك حد لعدد الشهادات المرصودة التي يمكنك تكوينها؟ لا، لا يحتوي ملحق الجهاز الظاهري لـ Key Vault على حد لعدد observedCertificates.

يدعم

إذا احتجت إلى مزيد من المساعدة بخصوص هذه المقالة في أي وقت، يمكنك الاتصال بخبراء Azure على منتديات MSDN Azure وStack Overflow. بدلاً من ذلك، يمكنك تقديم حدث دعم Azure. انتقل إلى موقع دعم Azure، وحدد Get support. للحصول على معلومات حول استخدام Azure Support، اقرأ الأسئلة المتداولة حول دعم Microsoft Azure.