Ekstensi komputer virtual Azure Key Vault untuk Linux

  • Artikel

Ekstensi komputer virtual Key Vault menyediakan refresh otomatis untuk sertifikat yang disimpan di brankas kunci Azure. Secara khusus, ekstensi memonitor daftar sertifikat yang diamati yang disimpan dalam key vault. Ekstensi mengambil dan menginstal sertifikat yang sesuai setelah mendeteksi perubahan. Dokumen ini merinci opsi platform, konfigurasi, dan penyebaran yang didukung untuk ekstensi VM Key Vault untuk Linux.

Sistem operasi

Ekstensi VM Key Vault mendukung distribusi Linux ini:

Catatan

Ekstensi VM Key Vault mengunduh sertifikat di lokasi default atau ke lokasi yang disediakan oleh properti "certStoreLocation" di pengaturan Ekstensi VM. Ekstensi VM Key Vault memperbarui izin folder menjadi 700 (drwx------) yang memungkinkan izin baca, tulis, dan jalankan kepada pemilik folder saja

Jenis konten sertifikat yang didukung

  • PKCS #12
  • PEM

Prasyarat

Versi ekstensi VM Key Vault

  • Pengguna dapat memilih untuk meningkatkan versi ekstensi vm Key Vault mereka untuk V2.0 menggunakan fitur unduhan rantai sertifikat lengkap. Sertifikat penerbit (menengah dan akar) disertakan dengan sertifikat daun dalam file PEM.

  • Jika Anda lebih suka meningkatkan ke v2.0, Anda harus menghapus v1.0 terlebih dahulu, lalu instal 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

Bendera --versi 2.0 bersifat opsional karena versi terbaru diinstal secara default.

  • Jika VM memiliki sertifikat yang diunduh oleh v1.0, menghapus ekstensi AKVVM v1.0 tidak menghapus sertifikat yang diunduh. Setelah menginstal v2.0, sertifikat yang ada tidak dimodifikasi. Anda perlu menghapus file sertifikat atau roll-over sertifikat untuk mendapatkan file PEM dengan rantai penuh pada VM.

Skema ekstensi

JSON berikut menunjukkan skema untuk ekstensi Key Vault VM. Ekstensi tidak memerlukan pengaturan yang dilindungi - semua pengaturannya dianggap sebagai informasi tanpa dampak keamanan. Ekstensi ini memerlukan daftar rahasia yang dipantau, frekuensi pemungutan suara, dan penyimpanan sertifikat tujuan. Khususnya:

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

Catatan

URL sertifikat yang Anda amati harus berupa formulir https://myVaultName.vault.azure.net/secrets/myCertName.

Ini karena /secrets jalur mengembalikan sertifikat lengkap, termasuk kunci privat, sementara /certificates jalurnya tidak. Informasi selengkapnya tentang sertifikat dapat ditemukan di sini: Sertifikat Key Vault

Penting

Properti 'autentikasi Pengaturan' diperlukan untuk VM dengan identitas yang ditetapkan pengguna. Bahkan jika Anda ingin menggunakan identitas yang ditetapkan sistem, ini masih diperlukan jika tidak, ekstensi VM tidak tahu identitas mana yang akan digunakan. Tanpa bagian ini, VM dengan identitas yang ditetapkan pengguna akan mengakibatkan ekstensi Key Vault gagal dan tidak dapat mengunduh sertifikat. Atur msiClientId ke identitas yang akan diautentikasi ke Key Vault.

Selain itu, diperlukan untuk Mesin Virtual yang didukung Azure Arc. Atur msiEndpoint ke http://localhost:40342/metadata/identity.

Nilai properti

Nama Nilai / Contoh Jenis Data
apiVersion 2022-07-01 date
penerbit Microsoft.Azure.KeyVault string
jenis KeyVaultForLinux string
typeHandlerVersion 2.0 int
pollingIntervalInS 3600 string
certificateStoreName Ini diabaikan di Linux string
linkOnRenewal salah Boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync benar Boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] array string
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string

Penyebaran templat

Ekstensi Azure VM dapat disebarkan dengan templat Azure Resource Manager. Templat sangat ideal saat menyebarkan satu atau beberapa komputer virtual yang memerlukan refresh pascapenyebaran sertifikat. Ekstensi dapat digunakan ke VM individu atau kumpulan skala komputer virtual. Skema dan konfigurasi umum untuk kedua jenis templat.

Konfigurasi JSON untuk ekstensi mesin virtual harus ditumpuk di dalam fragmen sumber daya mesin virtual dari templat, khususnya objek "resources": [] untuk templat mesin virtual dan untuk skala mesin virtual yang ditetapkan di bawah objek "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Catatan

Ekstensi VM akan mengharuskan sistem atau identitas yang dikelola pengguna ditetapkan untuk mengautentikasi ke Key Vault. Lihat Cara mengautentikasi ke Key Vault dan menetapkan kebijakan akses 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"
        }
      }
      }
    }

Pemesanan Dependensi Ekstensi

Ekstensi Key Vault VM mendukung pemesanan ekstensi jika dikonfigurasi. Secara default laporan ekstensi berhasil dimulai segera setelah polling dimulai. Namun, Anda dapat mengonfigurasinya untuk menunggu hingga berhasil mengunduh daftar lengkap sertifikat sebelum melaporkan awal yang berhasil. Jika ekstensi lain bergantung pada sertifikat yang diinstal sebelum dimulai, maka mengaktifkan pengaturan ini akan memungkinkan ekstensi tersebut untuk mendeklarasikan dependensi pada ekstensi Key Vault. Langkah ini akan mencegah ekstensi tersebut dimulai sampai semua sertifikat yang diandalkan telah diinstal. Ekstensi akan mencoba kembali unduhan awal tanpa batas waktu dan tetap dalam status Transitioning.

Untuk mengaktifkan dependensi ekstensi, atur berikut ini:

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

Catatan

Menggunakan fitur ini tidak kompatibel dengan templat ARM yang membuat identitas yang ditetapkan sistem dan memperbarui kebijakan akses Key Vault dengan identitas tersebut. Melakukan tindakan tersebut akan mengakibatkan kebuntuan karena kebijakan akses vault tidak dapat diperbarui sampai semua ekstensi telah dimulai. Sebagai gantinya, gunakan identitas MSI tunggal yang ditetapkan pengguna dan pra-ACL vault Anda dengan identitas tersebut sebelum menyebarkan.

Penyebaran Azure PowerShell

Peringatan

Klien PowerShell sering menambahkan \ ke " dalam settings.json yang akan menyebabkan akvvm_service gagal dengan kesalahan: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell dapat digunakan untuk menggunakan ekstensi Key Vault VM ke komputer virtual atau kumpulan skala komputer virtual yang ada.

  • Untuk menyebarkan ekstensi pada 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

  • Untuk menyebarkan ekstensi pada set skala komputer virtual:

    
    # 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

Penyebaran Azure CLI

Azure CLI dapat digunakan untuk menyebarkan ekstensi Key Vault VM ke komputer virtual atau kumpulan skala komputer virtual yang ada.

  • Untuk menyebarkan ekstensi pada 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> \"] }}'

  • Untuk menyebarkan ekstensi pada set skala komputer virtual:

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

Harap diperhatikan tentang pembatasan/persyaratan berikut:

Pemecahan masalah dan Dukungan

Data tentang status penyebaran ekstensi dapat diambil dari portal Microsoft Azure dan menggunakan Azure PowerShell. Untuk melihat status penyebaran ekstensi untuk VM tertentu, jalankan perintah berikut menggunakan 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 dapat berjalan di beberapa lingkungan shell, tetapi dengan sedikit variasi format. Jika Anda mendapatkan hasil yang tidak diharapkan dengan perintah Azure CLI, lihat Cara berhasil menggunakan Azure CLI.

Log dan konfigurasi

Log ekstensi mesin virtual Key Vault hanya ada secara lokal di mesin virtual dan paling informatif dalam hal pemecahan masalah.

Location Deskripsi
/var/log/waagent.log Memperlihatkan saat pembaruan ke ekstensi terjadi.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Periksa log layanan Ekstensi mesin virtual Key Vault untuk menentukan status layanan akvvm_service dan pengunduhan sertifikat. Anda dapat menemukan lokasi unduhan file PEM dalam file dengan entri yang disebut nama file sertifikat. Jika certificateStoreLocation tidak ditentukan, defaultnya adalah /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/* Konfigurasi dan binari untuk layanan Ekstensi mesin virtual Key Vault.

Link simbolis atau Symlinks adalah pintasan tingkat lanjut. Untuk menghindari pemantauan folder dan mendapatkan sertifikat terbaru secara otomatis, Anda dapat menggunakan symlink ini ([VaultName].[CertificateName]) untuk mendapatkan versi terbaru sertifikat di Linux.

Pertanyaan Umum

  • Apakah ada batasan jumlah observedCertificates yang dapat Anda konfigurasi? Tidak, Ekstensi VM Key Vault tidak memiliki batasan pada jumlah observedCertificates.

Dukungan

Jika Anda memerlukan bantuan lebih lanjut kapan saja dalam artikel ini, Anda dapat menghubungi pakar Azure di forum Azure MSDN dan Stack Overflow. Atau, Anda dapat mengajukan insiden dukungan Azure. Buka situs dukungan Azure dan pilih Dapatkan dukungan. Untuk mengetahui informasi tentang cara menggunakan Dukungan Azure, baca FAQ dukungan Microsoft Azure.