مشاركة عبر

ملحق Key Vault Virtual Machine ل Linux

  • مقالة

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

نظام التشغيل

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

إشعار

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

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

  • PKCS #12
  • PEM

التحديثات في الإصدار 3.0+

الإصدار 3.0+ من ملحق Key Vault VM لنظام Linux يضيف دعما للميزات التالية:

  • إضافة أذونات ACL للشهادات التي تم تنزيلها لتوفير الوصول للقراءة للمستخدمين والمجموعات
  • تكوين موقع تثبيت الشهادة
  • دعم الاسم الرمزي المخصص
  • دعم تكامل تسجيل ملحق الجهاز الظاهري من خلال Fluentd

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

إصدار ملحق جهاز ظاهري لـ Key Vault

  • يمكن للمستخدمين اختيار ترقية إصدار ملحق Key Vault 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

العلامة --الإصدار 3.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": "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

هام

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

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

قيم Property

الاسم القيمة / المثال نوع البيانات
apiVersion 2022-07-01 date
publisher Microsoft.Azure.KeyVault سلسلة
type KeyVaultForLinux سلسلة
typeHandlerVersion 3.0 العدد الصحيح
pollingIntervalInS 3600 سلسلة
certificateStoreName يتم تجاهله على Linux سلسلة
linkOnRenewal true boolean
requireInitialSync صحيح boolean
aclEnabled صحيح 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 (اختياري) {...} كائن
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity سلسلة
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 سلسلة
loggingSettings (اختياري) {...} كائن
loggingSettings/logger "بطلاقة" سلسلة
loggingSettings/endpoint "tcp://localhost:24224" سلسلة
loggingSettings/format "إلى الأمام" سلسلة
loggingSettings/servicename "akvvm_service" سلسلة

توزيع قالب

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

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

يمكن نشر ملحق Azure Key Vault VM باستخدام Azure PowerShell. حفظ إعدادات ملحق Key Vault VM إلى ملف JSON (settings.json).

توفر القصاصات البرمجية JSON التالية أمثلة لإعدادات نشر ملحق Key Vault VM مع PowerShell.

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

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

يمكن نشر ملحق Azure Key Vault VM باستخدام Azure CLI. حفظ إعدادات ملحق Key Vault VM إلى ملف JSON (settings.json).

توفر القصاصات البرمجية JSON التالية أمثلة لإعدادات لنشر ملحق Key Vault VM مع Azure CLI.

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

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

  • قيود Key Vault:
    • يجب أن تكون موجودة في وقت التوزيع
    • يجب تعيين دور مستخدم Key Vault Secrets إلى 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 VM محليا على الجهاز الظاهري وهي مفيدة للغاية عندما يتعلق الأمر باستكشاف الأخطاء وإصلاحها. يمكنك استخدام قسم التسجيل الاختياري للتكامل مع موفر التسجيل من خلال fluentd

الموقع ‏‏الوصف
/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.

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

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

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

يدعم

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