Bagikan melalui

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 (versi 1/2), atau pengaturan sertifikat individual (versi 3). 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

Pembaruan di Versi 3.0+

Versi 3.0+ dari ekstensi VM Key Vault untuk Linux menambahkan dukungan untuk fitur-fitur berikut:

  • Menambahkan izin ACL untuk sertifikat yang diunduh untuk menyediakan akses baca bagi pengguna dan grup
  • Konfigurasi lokasi penginstalan sertifikat
  • Dukungan nama simbolis kustom
  • Dukungan integrasi pengelogan ekstensi VM melalui Fluentd

Prasyarat

Versi ekstensi VM Key Vault

  • Pengguna dapat memilih untuk meningkatkan versi ekstensi VM Key Vault yang ada ke versi yang lebih baru.

  • Jika Anda lebih suka meningkatkan ke versi yang lebih baru, Anda harus menghapus versi sebelumnya terlebih dahulu, lalu menginstal versi yang lebih baru.

  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

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

  • Jika VM memiliki sertifikat yang diunduh oleh versi sebelumnya, menghapus ekstensi VM tidak menghapus sertifikat yang diunduh. Setelah menginstal versi yang lebih baru, 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": "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".>
        }>
       }
      }
    }

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 'authenticationSettings' 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
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 int
pollingIntervalInS 3600 string
certificateStoreName Ini diabaikan di Linux string
linkOnRenewal salah Boolean
requireInitialSync benar Boolean
aclEnabled benar Boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] array string
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (opsional) "app1Cert1" string
observedCertificates/acls (opsional) "{...}, {...}" array string
authenticationSettings (opsional) {...} object
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (opsional) {...} object
loggingSettings/logger "fasih" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "maju" string
loggingSettings/servicename "akvvm_service" 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": "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">
          }
        } 
      }
    }

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:

Ekstensi VM Azure Key Vault dapat disebarkan dengan Azure PowerShell. Simpan pengaturan ekstensi VM Key Vault ke file JSON (settings.json).

Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan 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"
   }      
}
  • Untuk menyebarkan ekstensi pada komputer virtual:
# 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
  • Untuk menyebarkan ekstensi pada set skala komputer virtual:
    # 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

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:

Ekstensi VM Azure Key Vault dapat disebarkan dengan menggunakan Azure CLI. Simpan pengaturan ekstensi VM Key Vault ke file JSON (settings.json).

Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan 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"
   }      
}
  • Untuk menyebarkan ekstensi pada komputer virtual

    # 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"
  • 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 3.0 `
    --enable-auto-upgrade true `
    --settings "@settings.json"

Harap diperhatikan tentang pembatasan/persyaratan berikut:

  • Pembatasan Key Vault:
    • Batasan ini harus ada pada saat penyebaran
    • Peran Pengguna Rahasia Key Vault harus ditetapkan ke Key Vault untuk identitas VM

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 VM Key Vault ada secara lokal di VM dan paling informatif dalam hal pemecahan masalah. Anda dapat menggunakan bagian pengelogan opsional untuk diintegrasikan dengan penyedia pengelogan melalui fluentd

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.