estensione macchina virtuale Azure Key Vault per Linux

L'estensione macchina virtuale (VM) Azure Key Vault aggiorna automaticamente i certificati archiviati in un Azure key vault. L'estensione monitora un elenco di certificati osservati archiviati negli insiemi di credenziali delle chiavi. Quando l'estensione rileva una modifica, recupera e installa i certificati corrispondenti. Questo articolo descrive le piattaforme, le configurazioni e le opzioni di distribuzione supportate per l'estensione macchina virtuale Key Vault per Linux.

Sistemi operativi

L'estensione macchina virtuale Key Vault per Linux supporta le distribuzioni seguenti, sia in AMD64 che in ARM64:

• Ubuntu 24.04
• Azure Linux 3.0 e 4.0
• Red Hat Enterprise Linux (RHEL) 9

Tipi di contenuto del certificato supportati

L'estensione macchina virtuale Key Vault supporta i tipi di contenuto del certificato seguenti:

• PKCS #12
• PEM

Funzionalità

Estensione macchina virtuale Key Vault per Linux versione 4.x:

• Installa le due versioni più recenti di ogni certificato.
• Installa ogni certificato come file separati: un file .pem della catena completa e un file .keyid separato della chiave privata, ciascuno scritto come file versionato con un collegamento simbolico stabile che punta alla versione più recente.
• Esegue la convalida della catena di certificati prima di installare qualsiasi certificato che contenga l'utilizzo della chiave estesa (EKU) per l'autenticazione del server TLS. La convalida è di tipo fail-open: un certificato viene comunque installato se la convalida non può essere completata a causa di problemi di rete temporanei. I certificati senza L'autenticazione server EKU non sono soggetti a questo controllo.
• Applica gli ACL POSIX per concedere agli utenti e ai gruppi configurati l'accesso in lettura alla chiave privata. L'applicazione dell'ACL è sempre attiva.
• Supporta un override facoltativo dell'autenticazione per certificato, che consente ai singoli certificati osservati di eseguire l'autenticazione a Key Vault con un'identità gestita diversa rispetto all'impostazione predefinita dell'estensione. Per altre informazioni, vedere Schema dell'estensione.
• Supporta l'integrazione della registrazione delle estensioni della macchina virtuale tramite Fluentd. Per altre informazioni, vedere Registrazione con Fluentd.

Aggiornamento dalla versione 3.0

Se si esegue l'aggiornamento dalla versione 3.0, le funzionalità seguenti vengono modificate o rimosse.

Modifiche di rilievo di carattere generale:

• pollingIntervalInS è ora limitato a un intervallo compreso tra 5 e 60 minuti. Per impostazione predefinita, l'estensione esegue il polling una volta all'ora.
• requireInitialSync viene rimosso. L'estensione segnala l'esito positivo solo se installa tutti i certificati configurati.
• Non è più possibile configurare una versione specifica di un certificato. Gli URL dei certificati osservati devono essere senza versione.
• Lo schema legacy in cui observedCertificates è un elenco di stringhe URL non è più supportato. Ogni voce deve essere un oggetto con una proprietà url.

Modifiche di rilievo specifiche di Linux:

• La catena di certificati e la chiave privata vengono ora scritte in file separati. Nella versione 3.0, la catena completa e la chiave privata sono state combinate in un singolo file PEM. Nella versione 4.x l'estensione scrive la catena completa in <vaultname>.<certname>.pem e la chiave privata in un file separato <vaultname>.<certname>.keyid . Questa modifica è di rilievo: le applicazioni che prevedono la chiave e la catena in un file devono essere aggiornate per leggere la catena dal file .pem e la chiave privata dal file .keyid. Il .luma file viene aggiornato dopo l'aggiornamento dei collegamenti simbolici, quindi le applicazioni devono monitorare le modifiche apportate a questo file di metadati.
• customSymbolicLinkName viene rimosso. L'estensione usa sempre il nome <vaultname>.<certname>di collegamento simbolico predefinito .
• aclEnabled viene rimosso. La funzionalità ACL è ora sempre abilitata.
• certificateStoreName viene ignorato in Linux e non ha alcun effetto.

Prerequisiti

Esaminare i prerequisiti seguenti per l'uso dell'estensione vm Key Vault per Linux:

• Istanza di Azure Key Vault con un certificato. Per ulteriori informazioni, vedere Crea un Key Vault usando il portale di Azure.

• Macchina virtuale con un'identità gestita assegnata.

• Assegnare il ruolo Utente dei segreti di Key Vault nell'ambito di Key Vault all'identità gestita per la macchina virtuale o per i set di scalabilità di macchine virtuali di Azure. Questo ruolo recupera la parte segreta di un certificato. Per altre informazioni, vedere gli articoli seguenti:

  • Autenticazione in Azure Key Vault
  • it-IT: Utilizzare le autorizzazioni per segreti, chiavi e certificati di Azure RBAC con Azure Key Vault
  • Assegnazione di ruolo nell'ambito di Key Vault

• Configurare i set di scalabilità di macchine virtuali con la seguente identity configurazione:

  "identity": {
      "type": "UserAssigned",
      "userAssignedIdentities": {
         "[parameters('userAssignedIdentityResourceId')]": {}
      }
  }
  

• Configurare l'estensione macchina virtuale Key Vault con la configurazione seguenteauthenticationSettings:

  "authenticationSettings": {
      "msiEndpoint": "[parameters('userAssignedIdentityEndpoint')]",
      "msiClientId": "[reference(parameters('userAssignedIdentityResourceId'), variables('msiApiVersion')).clientId]"
  }
  

Schema dell'estensione

Il codice JSON seguente mostra lo schema per l'estensione di macchina virtuale Key Vault. Prima di prendere in considerazione le opzioni di implementazione dello schema, esaminare le note importanti seguenti.

• L'estensione non richiede impostazioni protette. Tutte le impostazioni sono informazioni pubbliche.

• Gli URL dei certificati osservati devono usare il modulo https://myVaultName.vault.azure.net/secrets/myCertName.

  Questo modulo è obbligatorio perché il /secrets percorso restituisce il certificato completo, inclusa la chiave privata, ma il /certificates percorso non lo è. Per altre informazioni sui certificati, vedere Panoramica delle chiavi, dei segreti e dei certificati di Azure Key Vault. Non è possibile specificare una versione specifica del certificato.

• L'host URL deve essere un host Azure Key Vault riconosciuto.

• La authenticationSettings proprietà è necessaria per le macchine virtuali con identità assegnate dall'utente e per le macchine virtuali abilitate per Azure Arc.

  Omettere questa proprietà quando si usa un'identità assegnata dal sistema. Per le macchine virtuali con Azure Arc abilitato, impostare msiEndpoint su http://localhost:40342/metadata/identity.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KVVMExtensionForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": <Optional. Polling interval in seconds, between 300 (5 min) and 3600 (60 min). Example: "3600">,
             "certificateStoreLocation": <Optional. Default disk path where certificates are stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault.Store">,
             "observedCertificates": <An array of Key Vault URIs that represent monitored certificates, including per-certificate store location and ACL permissions on the 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 disk path where the certificate is stored. Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app1">,
                    "acls": <Optional. An array of users and groups to grant read access to the certificate private key. Example:
                    [
                       { "user": "app1", "group": "appGroup1" },
                       { "user": "service1" }
                    ]>
                },
                {
                    "url": <Example: "https://myvault.vault.azure.net/secrets/mycertificate2">,
                    "certificateStoreLocation": <Example: "/var/lib/waagent/Microsoft.Azure.KeyVault/app2">,
                    "authenticationOverride": <Optional. Overrides authenticationSettings for this certificate only, so it can authenticate with a different managed identity. Example: {"msiClientId": "11112222-bbbb-3333-cccc-4444dddd5555"}>
                }
             ]>
         },
         "authenticationSettings": {
             "msiEndpoint":  <Required when the msiClientId property is used. Specifies the MSI endpoint. Example for most Azure VMs: "http://169.254.169.254/metadata/identity">,
             "msiClientId":  <Required when the VM has any user assigned identities. Specifies the MSI identity. Example: "00001111-aaaa-2222-bbbb-3333cccc4444">
         }
      }
   }
}

Valori delle proprietà

Lo schema JSON include le proprietà seguenti.

Distribuzione di template

Distribuire le estensioni delle macchine virtuali di Azure tramite i modelli di Azure Resource Manager (ARM). I modelli sono ideali quando si distribuiscono una o più macchine virtuali che richiedono l'aggiornamento post-distribuzione dei certificati. È possibile distribuire l'estensione in singole macchine virtuali o istanze di set di scalabilità di macchine virtuali. Lo schema e la configurazione sono comuni a entrambi i tipi di modello.

La configurazione JSON per un'estensione dell'insieme di credenziali delle chiavi è annidata all'interno del modello VM o dei set di scalabilità di macchine virtuali. Per un'estensione della risorsa di macchina virtuale, la configurazione viene annidata nell'oggetto macchina virtuale "resources": []. Per un'estensione dell'istanza di set di scalabilità di macchine virtuali, la configurazione è annidata sotto l'oggetto "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Il frammento JSON seguente mostra impostazioni di esempio per una distribuzione tramite template ARM dell'estensione della macchina virtuale di Key Vault.

{
   "type": "Microsoft.Compute/virtualMachines/extensions",
   "name": "KeyVaultForLinux",
   "apiVersion": "2025-04-01",
   "location": "<location>",
   "dependsOn": [
      "[concat('Microsoft.Compute/virtualMachines/', <vmName>)]"
   ],
   "properties": {
      "publisher": "Microsoft.Azure.KeyVault",
      "type": "KeyVaultForLinux",
      "typeHandlerVersion": "4.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
         "secretsManagementSettings": {
             "pollingIntervalInS": "3600",
             "certificateStoreLocation": "/var/lib/waagent/Microsoft.Azure.KeyVault.Store",
             "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"
                }
             ]
         },
         "authenticationSettings": {
            "msiEndpoint":  "http://169.254.169.254/metadata/identity",
            "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
         }
      }
   }
}

Aggiornamento automatico dell'estensione

L'estensione macchina virtuale Key Vault supporta l'aggiornamento automatico delle estensioni per le macchine virtuali e i set di scalabilità in Azure. Azure mantiene automaticamente aggiornata l'estensione quando si impostano le proprietà autoUpgradeMinorVersion e enableAutomaticUpgrade su true negli esempi precedenti.

Ordinamento delle dipendenze dell'estensione

L'estensione macchina virtuale Key Vault supporta l'ordinamento delle dipendenze dell'estensione. L'estensione segnala un avvio corretto dopo il download e l'installazione di tutti i certificati.

Se si usano altre estensioni che richiedono l'installazione di certificati prima dell'avvio, è possibile usare l'ordinamento delle dipendenze dell'estensione per dichiarare una dipendenza dall'estensione della macchina virtuale Key Vault.

All'avvio, l'estensione della macchina virtuale Key Vault ritenta il download e l'installazione dei certificati fino a 25 volte con periodi di backoff crescenti, durante i quali rimane in uno stato Transitioning. Se i tentativi vengono esauriti, l'estensione segnala uno stato di errore. Dopo l'installazione di tutti i certificati, l'estensione della macchina virtuale Key Vault segnala un avvio corretto.

Per altre informazioni sulla configurazione delle dipendenze tra le estensioni, vedere Provisioning delle estensioni di sequenza in set di scalabilità di macchine virtuali.

distribuzione Azure PowerShell

Distribuire l'estensione macchina virtuale Azure Key Vault usando Azure PowerShell. Salva le impostazioni dell'estensione della macchina virtuale in Key Vault in un file JSON (settings.json).

Il frammento json seguente fornisce impostazioni di esempio per la distribuzione dell'estensione macchina virtuale Key Vault tramite PowerShell.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Distribuire in una macchina virtuale

# Build settings
$settings = (Get-Content -Raw ".\settings.json")
$extName =  "KeyVaultForLinux"
$extPublisher = "Microsoft.Azure.KeyVault"
$extType = "KeyVaultForLinux"

# Start the deployment
Set-AzVmExtension -TypeHandlerVersion "4.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings

Distribuire in un'istanza di set di scalabilità di macchine virtuali

# 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 "4.0" -Setting $settings

# Start the deployment
Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

distribuzione di interfaccia della riga di comando di Azure

Distribuire l'estensione macchina virtuale Azure Key Vault usando il interfaccia della riga di comando di Azure. Salva le impostazioni dell'estensione della macchina virtuale in Key Vault in un file JSON (settings.json).

Il frammento JSON seguente fornisce impostazioni di esempio per la distribuzione dell'estensione macchina virtuale Key Vault usando il interfaccia della riga di comando di Azure.

{
   "secretsManagementSettings": {
      "pollingIntervalInS": "3600",
      "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"
         }
      ]
   },
   "authenticationSettings": {
      "msiEndpoint":  "http://169.254.169.254/metadata/identity",
      "msiClientId":  "00001111-aaaa-2222-bbbb-3333cccc4444"
   }
}

Distribuire in una macchina virtuale

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

Distribuire in un'istanza di set di scalabilità di macchine virtuali

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

az vm extension delete --name "KeyVaultForLinux" --resource-group "<resourcegroup>" --vm-name "<vmName>"

Registrazione con Fluentd

L'estensione della macchina virtuale Key Vault può inoltrare i log a un agente di raccolta log Fluentd. Verificare che l'agente di raccolta log sia in esecuzione e in ascolto sull'endpoint specificato nelle impostazioni.

Aggiungere la sezione seguente alle impostazioni dell'estensione:

"loggingSettings": {
   "logger": "fluentd",
   "endpoint": "unix:///var/run/azuremonitoragent/sometenant/default_fluent.socket",
   "format": "forward",
   "servicename": "akvvm_service"
}

Risoluzione dei problemi

Usare questi suggerimenti per risolvere i problemi di distribuzione.

Controllare le domande frequenti

Esiste un limite al numero di certificati osservati?

No. L'estensione della macchina virtuale di Key Vault non limita il numero di certificati osservati (observedCertificates).

Qual è il percorso predefinito in cui sono installati i certificati?

Se non si specifica certificateStoreLocation, l'estensione scrive i certificati in /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.

Come si fa a forzare l'estensione a eseguire il pull di un nuovo certificato?

Riavvia il servizio akvvm_service (nome visualizzato: Key Vault VM Extension).

Come si usa un'identità diversa per un certificato specifico?

Aggiungere un oggetto authenticationOverride con msiClientId di destinazione alla voce del certificato in observedCertificates. I certificati senza eccezione usano il livello superiore authenticationSettings.

Visualizzare lo stato dell'estensione

Controllare lo stato della distribuzione dell'estensione nel portale di Azure oppure usando PowerShell o il interfaccia della riga di comando di Azure.

Per visualizzare lo stato di distribuzione delle estensioni per una determinata macchina virtuale, usare i comandi seguenti.

• Azure PowerShell:

  Get-AzVMExtension -ResourceGroupName <myResourceGroup> -VMName <myVM> -Name <myExtensionName>
  

• L’interfaccia della riga di comando di Azure:

  az vm get-instance-view --resource-group <myResourceGroup> --name <myVM> --query "instanceView.extensions"
  

Il interfaccia della riga di comando di Azure può essere eseguito in diversi ambienti della shell, ma con lievi variazioni di formato. Se sono presenti risultati imprevisti con i comandi di interfaccia della riga di comando di Azure, vedere Come usare correttamente il interfaccia della riga di comando di Azure.

Esaminare i log e la configurazione

I log dell'estensione della macchina virtuale Key Vault sono disponibili solo localmente sulla macchina virtuale. Esaminare i dettagli del log per facilitare la risoluzione dei problemi.

Installazione del certificato in Linux

L'estensione macchina virtuale Key Vault per Linux installa i certificati come file PEM. Quando l'estensione scarica un certificato da Key Vault, è possibile:

1. Crea una cartella di archiviazione in base all'impostazione certificateStoreLocation . Se non si specifica questa impostazione, il percorso predefinito è /var/lib/waagent/Microsoft.Azure.KeyVault.Store/.
2. Scrive la catena di certificati (foglia, quindi i certificati intermedi e infine la radice, se presente in Key Vault) in un file .pem della catena completa con versione e scrive la chiave privata corrispondente in un file .keyid con versione.
3. Applica gli ACL POSIX alla chiave privata in base all'oggetto acls specificato nella configurazione, che concede l'accesso in lettura agli utenti e ai gruppi elencati. Altrimenti, i file sono solo del proprietario.
4. Crea o aggiorna un collegamento simbolico stabile (<vaultname>.<certname>.pem e <vaultname>.<certname>.keyid) che punta alla versione più recente del certificato. Il collegamento si verifica sempre.

Percorso dell'archivio del certificato predefinito

Se non si specifica una posizione, l'estensione installa i certificati in /var/lib/waagent/Microsoft.Azure.KeyVault.Store/. L'estensione ignora certificateStoreName in Linux.

File di output del certificato

Per il vault mykv e il segreto server-tls, una sincronizzazione riuscita produce:

/var/lib/waagent/Microsoft.Azure.KeyVault.Store/
├── mykv.server-tls.pem -> mykv.server-tls.<version>.pem.<timestamp>     # symlink to latest full chain
├── mykv.server-tls.keyid -> mykv.server-tls.<version>.keyid.<timestamp> # symlink to latest private key
├── mykv.server-tls.<version>.pem.<timestamp>                            # full chain PEM (mode 600)
├── mykv.server-tls.<version>.keyid.<timestamp>                          # private key (mode 600)
└── mykv.server-tls.luma                                                 # certificate management metadata (mode 644)

Configurare le applicazioni per fare riferimento al percorso di collegamento simbolico stabile ( ad esempio , /var/lib/waagent/Microsoft.Azure.KeyVault.Store/mykv.server-tls.pem) in modo che legga sempre la versione del certificato più recente senza riconfigurare il rinnovo.

Controllo di accesso ai certificati

Per impostazione predefinita, i file di certificato e chiave privata sono leggibili solo dal proprietario. Concedere l'accesso in lettura a utenti e gruppi aggiuntivi usando la acls matrice nella configurazione del certificato:

"acls": [
   { "user": "app1", "group": "appGroup1" },
   { "user": "service1" }
]

Ogni voce può specificare un utente, un gruppo o entrambi. L'imposizione degli elenchi di controllo di accesso è sempre abilitata e attualmente concede l'accesso in lettura.

Rinnovo del certificato

Quando i certificati vengono rinnovati in Key Vault, l'estensione esegue automaticamente le azioni seguenti al polling successivo:

1. Scarica la nuova versione del certificato.
2. Scrive i nuovi file .pem e .keyid con controllo delle versioni.
3. Aggiorna il collegamento simbolico stabile in modo che punti alla nuova versione, in modo che i percorsi dell'applicazione esistenti continuino a essere risolti nel certificato più recente.

Ottenere supporto

Microsoft fornisce supporto solo per la versione principale 3.0 e successive dell'estensione macchina virtuale Key Vault. Se si usa la versione 1.0, eseguire l'aggiornamento alla versione più recente prima di richiedere supporto.

Usare queste altre opzioni per risolvere i problemi di distribuzione:

• Per assistenza, contattare gli esperti Azure in Microsoft Q& A.

• Se non si trova una risposta nel sito, è possibile pubblicare una domanda per l'input di Microsoft o di altri membri della community.

• È anche possibile contattare il supporto tecnico Microsoft. Per informazioni sull'uso di supporto tecnico di Azure, vedere Come creare una richiesta di supporto tecnico di Azure.