Azure Key Vault ekstensi komputer virtual untuk Linux

Ekstensi komputer virtual (VM) Azure Key Vault secara otomatis me-refresh sertifikat yang disimpan dalam Azure key vault. Ekstensi memantau daftar sertifikat yang diamati yang disimpan dalam brankas kunci. Saat ekstensi mendeteksi perubahan, ekstensi mengambil dan menginstal sertifikat yang sesuai. Artikel ini menjelaskan platform, konfigurasi, dan opsi penyebaran yang didukung untuk ekstensi VM Key Vault untuk Linux.

Nota

Coba bantuan VM untuk diagnostik yang lebih cepat. Kami menyarankan agar Anda menjalankan VM assist untuk Windows atau VM assist untuk Linux. Alat diagnostik berbasis skrip ini membantu Anda mengidentifikasi masalah umum yang memengaruhi Agen Tamu Azure VM dan kesehatan VM secara keseluruhan.

Jika Anda mengalami masalah performa dengan komputer virtual, sebelum menghubungi dukungan, jalankan alat-alat ini.

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 dan yang lebih baru mendukung:

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

Prasyarat

Meningkatkan ekstensi VM Key Vault

  • Untuk meningkatkan dari versi yang lebih lama ke versi 3.0 atau yang lebih baru, hapus versi sebelumnya, lalu instal 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 Anda menginstal versi yang lebih baru, ekstensi tidak mengubah sertifikat yang ada. Hapus file sertifikat atau ganti sertifikat untuk mendapatkan file PEM dengan rantai sertifikat lengkap di VM.

Skema ekstensi

JSON berikut menyediakan skema untuk ekstensi VM Key Vault. Semua pengaturan menggunakan pengaturan biasa dan tidak terlindungi karena pengaturan tidak berisi informasi sensitif. Untuk mengonfigurasi ekstensi, tentukan daftar sertifikat yang akan dipantau, seberapa sering melakukan polling pembaruan, dan jalur tujuan untuk menyimpan sertifikat.

    {
      "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 Key Vault 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 menggunakan formulir https://myVaultName.vault.azure.net/secrets/myCertName.

Jalur /secrets mengembalikan sertifikat lengkap, termasuk kunci privat, tetapi /certificates jalurnya tidak. Untuk informasi selengkapnya tentang sertifikat, lihat Gambaran umum kunci, rahasia, dan sertifikat Azure Key Vault.

Penting

Properti authenticationSettings hanya diperlukan saat VM Anda menggunakan identitas terkelola yang ditetapkan pengguna, Kumpulan Skala Komputer Virtual Azure Anda menggunakan identitas terkelola yang ditetapkan pengguna, atau Anda menggunakan VM yang diaktifkan Azure Arc. Untuk identitas terkelola yang ditetapkan sistem, hilangkan bagian authenticationSettings . Menyertakan bagian ini menyebabkan deployment gagal. Tanpa bagian ini, VM dengan identitas yang ditetapkan pengguna tidak dapat menggunakan ekstensi Key Vault untuk mengunduh sertifikat. Atur msiClientId ke identitas yang akan mengautentikasi ke Key Vault.

Properti msiEndpoint ini juga diperlukan untuk VM yang mendukung Azure Arc. Atur msiEndpoint ke http://localhost:40342/metadata/identity.

Nilai properti

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

Penyebaran Templat

Anda dapat menyebarkan ekstensi mesin virtual Azure dengan menggunakan templat Azure Resource Manager. Templat sangat ideal ketika Anda menyebarkan satu atau beberapa komputer virtual yang memerlukan refresh sertifikat pasca-penyebaran. Anda dapat menyebarkan ekstensi ke VM individual atau Kumpulan Skala Komputer Virtual Azure. Skema dan konfigurasi umum untuk kedua jenis templat.

Nota

Ekstensi VM memerlukan identitas terkelola yang ditetapkan sistem atau ditetapkan pengguna untuk mengautentikasi ke Key Vault. Untuk informasi selengkapnya, lihat Mengonfigurasi identitas terkelola untuk sumber daya Azure pada VM Azure dengan menggunakan portal Azure.

   {
      "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 or disables ACLs on defined certificates e.g.: true>,
          "observedCertificates": <An array of Key Vault 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">
          }
        }
      }
    }

Pengurutan dependensi ekstensi

Ekstensi VM Key Vault mendukung pemesanan ekstensi jika Anda mengonfigurasinya. Secara default, ekstensi melaporkan keberhasilan dimulai segera setelah polling dimulai. 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, aktifkan pengaturan ini. Ekstensi tersebut kemudian dapat mendeklarasikan dependensi pada ekstensi Key Vault. Pengaturan ini mencegah ekstensi tersebut berjalan sampai semua sertifikat yang diperlukan oleh ekstensi itu terpasang.

Ekstensi mencoba kembali pengunduhan awal hingga 25 kali dengan jeda tunggu yang semakin panjang, selama itu ekstensi tetap berada dalam status Transitioning. Jika percobaan ulang habis, ekstensi akan melaporkan status Error .

Untuk mengaktifkan dependensi ekstensi, atur hal berikut:

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

Nota

Fitur dependensi ekstensi tidak kompatibel dengan templat ARM yang membuat identitas yang ditetapkan sistem dan memperbarui kebijakan akses Key Vault dengan identitas tersebut. Konfigurasi ini membuat kebuntuan karena kebijakan akses vault tidak dapat diperbarui hingga semua ekstensi dimulai. Sebagai gantinya, gunakan satu identitas MSI yang ditetapkan pengguna dan konfigurasikan ACL pada vault Anda terlebih dahulu dengan identitas tersebut sebelum Anda menerapkan.

Penyebaran Azure PowerShell

Peringatan

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

Gunakan Azure PowerShell untuk menyebarkan ekstensi VM Key Vault ke komputer virtual atau set skala komputer virtual yang ada.

Simpan pengaturan ekstensi VM Key Vault ke file JSON bernama settings.json.

Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan menggunakan 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"
   }
}

Menyebarkan pada VM dengan menggunakan Azure PowerShell

# 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

Menerapkan ke kumpulan skala komputer virtual menggunakan Azure PowerShell

# 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

Gunakan Azure CLI untuk menyebarkan ekstensi VM Key Vault ke komputer virtual atau set skala komputer virtual yang ada.

Simpan pengaturan ekstensi VM Key Vault ke file JSON bernama settings.json.

Cuplikan JSON berikut menyediakan pengaturan contoh untuk menyebarkan ekstensi VM Key Vault dengan menggunakan 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"
   }
}

Menyebarkan pada VM dengan menggunakan Azure CLI

# Start the deployment
az vm extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vm-name "<vmName>" \
  --version "3.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Menyebarkan pada set skala komputer virtual dengan menggunakan Azure CLI

# Start the deployment
az vmss extension set --name "KeyVaultForLinux" \
  --publisher Microsoft.Azure.KeyVault \
  --resource-group "<resourcegroup>" \
  --vmss-name "<vmssName>" \
  --version "3.0" \
  --enable-auto-upgrade true \
  --settings "@settings.json"

Tinjau batasan dan persyaratan berikut:

  • Pembatasan Key Vault:
    • Key vault harus sudah ada saat deployment.
    • Peran Pengguna Rahasia Key Vault harus ditetapkan ke Key Vault untuk identitas VM.

Pemecahan masalah dan dukungan

Ambil data tentang status penyebaran ekstensi dari portal Azure, atau dengan menggunakan Azure PowerShell atau Azure CLI. Untuk melihat status penyebaran ekstensi untuk VM tertentu, jalankan perintah berikut.

  • 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 untuk pemecahan masalah. Gunakan bagian pengelogan opsional untuk berintegrasi dengan penyedia pengelogan dengan menggunakan fluentd.

Lokasi Deskripsi
/var/log/waagent.log Memperlihatkan kapan pembaruan terjadi pada ekstensi.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Memperlihatkan status layanan dan unduhan akvvm_service sertifikat. Anda dapat menemukan lokasi unduhan file PEM dalam file dengan entri bernama certificate file name. Jika certificateStoreLocation tidak ditentukan, lokasi akan menggunakan nilai bawaan /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<most recent version>/config/* Berisi konfigurasi dan biner untuk layanan ekstensi VM Key Vault.

Tautan simbolis adalah pintasan tingkat lanjut. Untuk menghindari pemantauan folder dan mendapatkan sertifikat terbaru secara otomatis, gunakan [VaultName].[CertificateName] tautan simbolis untuk mendapatkan versi sertifikat terbaru di Linux.

Penginstalan sertifikat di Linux

Ekstensi VM Key Vault untuk Linux menginstal sertifikat sebagai file PEM. Saat ekstensi mengunduh sertifikat dari Key Vault, ekstensi tersebut:

  1. Membuat folder penyimpanan berdasarkan pengaturan certificateStoreLocation. Jika Anda tidak menentukan pengaturan ini, lokasi akan menggunakan nilai bawaan /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
  2. Menginstal rantai sertifikat dan kunci privat seperti yang disimpan di Key Vault. File PEM mengikuti urutan RFC 5246 bagian 7.4.2 :
    • Sertifikat leaf, atau sertifikat entitas akhir, berada di urutan pertama.
    • Sertifikat perantara diurutkan secara berjenjang, dan setiap sertifikat secara langsung memvalidasi sertifikat yang mendahuluinya, jika tersedia di Key Vault.
    • Sertifikat akar, jika ada. Sertifikat akar tidak diperlukan untuk validasi jika sistem sudah mempercayainya.
    • Ekstensi menempatkan kunci privat yang sesuai dengan sertifikat daun di akhir file.
  3. Secara otomatis membuat tautan simbolis bernama [VaultName].[CertificateName] yang menunjuk ke versi terbaru sertifikat.

Pendekatan penginstalan ini memastikan bahwa:

  • Aplikasi memiliki akses ke rantai sertifikat seperti yang disimpan di Key Vault.
  • Rantai sertifikat disusun untuk handshake TLS sesuai dengan standar RFC.
  • Kunci privat tersedia untuk digunakan oleh layanan.
  • Aplikasi dapat mereferensikan jalur tautan simbolis stabil yang secara otomatis diperbarui 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 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)

Konfigurasikan aplikasi untuk menggunakan jalur tautan simbolis (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate). Konfigurasi ini memastikan bahwa 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 sertifikat yang diamati yang dapat saya konfigurasi?

No. Ekstensi VM Key Vault tidak membatasi jumlah sertifikat yang diamati (observedCertificates).

Dapatkan dukungan

Microsoft hanya menyediakan dukungan untuk ekstensi VM Key Vault versi utama 3.0 dan yang lebih baru. Jika Anda menggunakan versi 1.0, tingkatkan ke versi terbaru sebelum meminta dukungan.

Berikut adalah beberapa opsi lain untuk membantu Anda mengatasi masalah penyebaran:

  • Last updated on