Bagikan melalui

Ekstensi komputer virtual Key Vault untuk Linux

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 platform, konfigurasi, dan opsi penyebaran yang didukung untuk ekstensi VM Key Vault untuk Linux.

Sistem operasi

Ekstensi VM Key Vault mendukung:

Tipe isi sertifikat yang didukung

  • PKCS #12
  • PEM

Fitur

Ekstensi VM Key Vault untuk Linux versi 3.0+ mendukung:

  • 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 pencatatan log ekstensi VM melalui Fluentd

Prasyarat

  • Instans Key Vault dengan sertifikat. Lihat Membuat Key Vault

  • Identitas terkelola yang ditetapkan pada komputer virtual/set skala komputer virtual.

  • Peran Pengguna Rahasia Key Vault di tingkat cakupan Key Vault untuk VM dan identitas terkelola Azure Virtual Machine Scale Sets. Fungsi ini mengambil sebagian rahasia dari sertifikat. Untuk informasi lebih lanjut, baca artikel berikut:

  • Kumpulan skala mesin virtual harus memiliki pengaturan identitas berikut: "identity": { "type": "UserAssigned", "userAssignedIdentities": { "[parameters('userAssignedIdentityResourceId')]": {} } }

  • Ekstensi AKV harus memiliki pengaturan ini: "authenticationSettings": { "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]", "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]" }

Peningkatan ekstensi VM Key Vault

  • Jika Anda perlu meningkatkan dari versi yang lebih lama ke versi 3.0+, Anda harus menghapus versi sebelumnya terlebih dahulu, lalu menginstal versi 3.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 3.0
  • 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 mengganti sertifikat untuk mendapatkan file PEM dengan rantai penuh di VM.

Skema ekstensi

JSON berikut menyediakan skema untuk ekstensi VM Key Vault. Semua pengaturan ditentukan sebagai pengaturan biasa (tidak terlindungi), karena tidak ada yang dianggap sensitif. Untuk mengonfigurasi ekstensi, Anda harus menentukan daftar sertifikat yang akan dipantau, seberapa sering melakukan polling untuk pembaruan, dan jalur tujuan untuk menyimpan sertifikat. 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.: "00001111-aaaa-2222-bbbb-3333cccc4444".>
        }>
       }
      }
    }

Nota

URL sertifikat yang Anda amati harus dalam bentuk 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 mengautentikasi ke Key Vault.

Juga diperlukan untuk VM dengan dukungan Azure Arc. Atur msiEndpoint ke http://localhost:40342/metadata/identity.

Nilai properti

Nama Nilai / Contoh Jenis Data
apiVersion 2022-07-01 tanggal
publisher Microsoft.Azure.KeyVault benang
type KeyVaultForLinux benang
typeHandlerVersion 3.0 int (integer)
pollingIntervalInS 3600 benang
certificateStoreName Ini diabaikan di Linux benang
linkOnRenewal tidak benar Boolean
requireInitialSync benar Boolean
aclEnabled benar Boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store benang
observedCertificates [{...}, {...}] larik string
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" benang
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" benang
observedCertificates/customSymbolicLinkName (pilihan) app1Cert1 benang
observedCertificates/acls (pilihan) "{...}, {...}" larik string
authenticationSettings (pilihan) {...} obyek
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity benang
authenticationSettings/msiClientId 00001111-aaaa-2222-bbbb-3333cc4444 benang
loggingSettings (pilihan) {...} obyek
loggingSettings/logger fluentd benang
loggingSettings/endpoint "tcp://localhost:24224" benang
loggingSettings/format "maju" benang
loggingSettings/servicename "akvvm_service" benang

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 disebarkan ke masing-masing VM atau kelompok skala mesin virtual. Skema dan konfigurasi umum untuk kedua jenis templat.

Nota

Ekstensi VM memerlukan identitas yang dikelola oleh sistem atau pengguna untuk ditetapkan dalam rangka 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.: "00001111-aaaa-2222-bbbb-3333cccc4444">
          }
        } 
      }
    }

Urutan Dependensi Ekstensi

Ekstensi VM Key Vault mendukung pemesanan ekstensi jika dikonfigurasi. Pada pengaturan awal, ekstensi melaporkan permulaan berhasil ketika 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. Ini akan mencegah ekstensi tersebut dimulai sampai semua sertifikat yang menjadi ketergantungannya telah diinstal.

Ekstensi akan mengulangi unduhan awal hingga 25 kali dengan periode penundaan peningkatan, selama itu ekstensi tetap dalam keadaan Transitioning. Jika percobaan ulang habis, ekstensi akan melaporkan status Error .

Untuk mengaktifkan dependensi ekstensi, atur hal berikut:

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

Nota

Menggunakan fitur ini tidak kompatibel dengan templat ARM yang membuat identitas yang ditetapkan sistem dan memperbarui kebijakan akses Key Vault dengan identitas tersebut. Melakukannya akan mengakibatkan kebuntuan karena kebijakan akses vault tidak dapat diperbarui sampai semua ekstensi sudah aktif. Sebagai gantinya, Anda harus menggunakan satu pengguna yang ditetapkan identitas MSI 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 menyebarkan ekstensi VM Key Vault ke komputer virtual atau set 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 menerapkan ekstensi pada kumpulan skala mesin 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 VM Key Vault ke komputer virtual atau set 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 menerapkan ekstensi pada kumpulan skala mesin 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 perhatikan pembatasan/persyaratan berikut:

  • Pembatasan Key Vault:
    • 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 dengan 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

Lokasi Deskripsi
/var/log/waagent.log Memperlihatkan kapan pembaruan pada ekstensi terjadi.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Periksa log layanan Ekstensi VM Key Vault untuk menentukan status layanan akvvm_service dan unduhan sertifikat. Anda dapat menemukan lokasi unduhan file PEM dalam file dengan entri yang disebut nama file sertifikat. Jika certificateStoreLocation tidak ditentukan, sertifikat akan default ke /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<versi terbaru>/config/* Konfigurasi dan biner untuk layanan Ekstensi VM Key Vault.

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

Penginstalan Sertifikat di Linux

Ekstensi VM Key Vault untuk Linux menginstal sertifikat sebagai file PEM dengan rantai sertifikat lengkap yang disertakan. Saat sertifikat diunduh dari Key Vault, maka ekstensi:

  1. Membuat folder penyimpanan berdasarkan pengaturan certificateStoreLocation (akan menggunakan /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ secara default jika tidak ditentukan)
  2. Menginstal rantai sertifikat lengkap dan kunci privat dalam file PEM setelah RFC 5246 bagian 7.4.2 dalam urutan khusus ini:
    • Sertifikat daun (sertifikat entitas akhir) adalah yang pertama
    • Sertifikat perantara mengikuti secara berurutan, di mana setiap sertifikat secara langsung mensertifikasi sertifikat sebelumnya.
    • Sertifikat akar, jika ada (meskipun tidak diperlukan untuk validasi jika sudah dipercaya oleh sistem)
    • Kunci privat, sesuai dengan sertifikat daun, ditempatkan di akhir file
  3. Secara otomatis membuat tautan simbolis bernama [VaultName].[CertificateName] yang menunjuk ke versi terbaru sertifikat

Pendekatan ini memastikan bahwa:

  • Aplikasi selalu memiliki akses ke rantai sertifikat lengkap yang diperlukan untuk validasi
  • Rantai sertifikat diurutkan dengan benar untuk handshake TLS sesuai dengan standar RFC
  • Kunci privat tersedia untuk digunakan oleh layanan
  • Aplikasi dapat mereferensikan jalur tautan simbolis stabil yang diperbarui secara otomatis saat sertifikat diperbarui
  • Tidak diperlukan konfigurasi ulang aplikasi saat sertifikat diputar atau diperbarui

Contoh Struktur Jalur Sertifikat

Untuk sertifikat dari exampleVault.vault.azure.net dengan nama myCertificate, struktur direktori akan terlihat seperti:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── exampleVault.myCertificate -> exampleVault.myCertificate.1234567890abcdef
├── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file (current version)
└── exampleVault.myCertificate.0987654321fedcba    # Previous version (if exists)

Aplikasi harus dikonfigurasi untuk menggunakan jalur tautan simbolis (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) untuk memastikan aplikasi selalu mengakses versi sertifikat terbaru.

Saat Anda menggunakan lokasi penyimpanan sertifikat kustom dan customSymbolicLinkName pengaturan, struktur mengikuti pola ini:

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

Tanya Jawab Umum

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

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.