Condividi tramite

Estensione macchina virtuale di Key Vault per Linux

L'estensione della macchina virtuale di Key Vault offre l'aggiornamento automatico dei certificati archiviati in un insieme di credenziali di Azure. In particolare, l'estensione monitora un elenco di certificati osservati archiviati in insiemi di credenziali delle chiavi. L'estensione recupera e installa i certificati corrispondenti dopo aver rilevato una modifica. Questo documento descrive dettagliatamente le piattaforme, le configurazioni e le opzioni di distribuzione supportate per l'estensione macchina virtuale di Key Vault per Linux.

Sistema operativo

L'estensione della macchina virtuale di Key Vault supporta:

Tipi di contenuto del certificato supportati

  • PKCS #12
  • PEM

Funzionalità

L'estensione macchina virtuale Key Vault per Linux versione 3.0+ supporta:

  • Aggiungere autorizzazioni ACL per i certificati scaricati per fornire l'accesso in lettura per utenti e gruppi
  • Configurazione del percorso di installazione del certificato
  • Supporto del nome simbolico personalizzato
  • Supporto per l'integrazione della registrazione delle estensioni della macchina virtuale tramite Fluentd

Prerequisiti

Aggiornamento dell'estensione della macchina virtuale di Key Vault

  • Se è necessario eseguire l'aggiornamento da una versione precedente alla versione 3.0+, è prima necessario eliminare la versione precedente, quindi installare la versione 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
  • Se la macchina virtuale dispone di certificati scaricati dalla versione precedente, l'eliminazione dell'estensione della macchina virtuale non elimina i certificati scaricati. Dopo aver installato la versione più recente, i certificati esistenti non vengono modificati. È necessario eliminare i file di certificato o eseguire il rollover del certificato per ottenere il file PEM con catena completa nella macchina virtuale.

Schema dell'estensione

Il seguente JSON fornisce lo schema per l'estensione VM del Key Vault. Tutte le impostazioni vengono specificate come impostazioni semplici (non protette), perché nessuno viene considerato sensibile. Per configurare l'estensione, è necessario specificare un elenco di certificati da monitorare, la frequenza con cui eseguire il polling degli aggiornamenti e il percorso di destinazione per l'archiviazione dei certificati. In particolare:

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

Annotazioni

Gli URL dei certificati osservati devono essere nel formato https://myVaultName.vault.azure.net/secrets/myCertName.

Questo perché il /secrets percorso restituisce il certificato completo, inclusa la chiave privata, mentre il /certificates percorso non lo fa. Altre informazioni sui certificati sono disponibili qui: Certificati di Key Vault

Importante

La proprietà 'authenticationSettings' è necessaria per le macchine virtuali con identità assegnate dall'utente. Anche se si vuole usare un'identità assegnata dal sistema, questa operazione è ancora necessaria; in caso contrario, l'estensione della macchina virtuale non conosce l'identità da usare. Senza questa sezione, una macchina virtuale con identità assegnate dall'utente genererà un errore nell'estensione key vault e non sarà in grado di scaricare i certificati. Impostare msiClientId sull'identità che eseguirà l'autenticazione in Key Vault.

Necessario anche per le macchine virtuali abilitate per Azure Arc. Impostare msiEndpoint su http://localhost:40342/metadata/identity.

Valori delle proprietà

Nome Valore/Esempio Tipo di dati
apiVersion 2022-07-01 dattero
publisher Microsoft.Azure.KeyVault corda
type KeyVaultForLinux corda
typeHandlerVersion 3.0 Int
pollingIntervalInS 3600 corda
certificateStoreName Viene ignorato in Linux corda
linkOnRenewal falso booleano
requireInitialSync vero booleano
aclEnabled vero booleano
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store corda
observedCertificates [{...}, {...}] matrice di stringhe
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1"" corda
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" corda
observedCertificates/customSymbolicLinkName (facoltativo) app1Cert1 corda
observedCertificates/acls (facoltativo) {...}, {...} matrice di stringhe
authenticationSettings (facoltativo) {...} oggetto
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity corda
authenticationSettings/msiClientId 00001111-aaaa-2222-bbbb-3333cccc44444 corda
loggingSettings (facoltativo) {...} oggetto
loggingSettings/logger fluentd corda
loggingSettings/endpoint "tcp://localhost:24224" corda
loggingSettings/format avanti corda
loggingSettings/servicename "akvvm_service" corda

Distribuzione di template

Le estensioni macchina virtuale di Azure possono essere distribuite con i modelli di Azure Resource Manager. I modelli sono uno strumento ideale per distribuire una o più macchine virtuali per cui è necessario l'aggiornamento dei certificati successivamente alla distribuzione. L'estensione può essere distribuita in singole macchine virtuali o in set di scalabilità di macchine virtuali. Lo schema e la configurazione sono comuni a entrambi i tipi di modello.

Annotazioni

L'estensione della macchina virtuale richiede l'assegnazione dell'identità gestita dal sistema o dall'utente per l'autenticazione all'insieme di credenziali delle chiavi. Vedere Come eseguire l'autenticazione in Key Vault e assegnare un criterio di accesso a 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">
          }
        } 
      }
    }

Ordinamento delle dipendenze dell'estensione

L'estensione macchina virtuale Key Vault supporta l'ordinamento delle estensioni, se configurato. Per impostazione predefinita, i report dell'estensione vengono avviati non appena viene avviato il polling. Tuttavia, è possibile configurarlo in modo da attendere fino a quando non scarica correttamente l'elenco completo dei certificati prima di segnalare un avvio corretto. Se altre estensioni dipendono dai certificati installati prima dell'avvio, l'abilitazione di questa impostazione consentirà alle estensioni di dichiarare una dipendenza dall'estensione Key Vault. Ciò impedirà l'avvio di tali estensioni fino a quando non sono stati installati tutti i certificati da cui dipendono.

L'estensione tenterà nuovamente il download iniziale fino a 25 volte, aumentando progressivamente i tempi di attesa, durante i quali rimane nello stato Transitioning. Se i tentativi vengono esauriti, l'estensione segnala lo stato Error.

Per attivare la dipendenza dell'estensione, impostare quanto segue:

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

Annotazioni

L'uso di questa funzionalità non è compatibile con un modello di Resource Manager che crea un'identità assegnata dal sistema e aggiorna i criteri di accesso di Key Vault con tale identità. In questo modo si verificherà un deadlock perché i criteri di accesso dell'insieme di credenziali non possono essere aggiornati fino a quando non vengono avviate tutte le estensioni. È invece consigliabile usare un'identità msi assegnata da un singolo utente e pre-ACL gli insiemi di credenziali con tale identità prima della distribuzione.

Distribuzione con Azure PowerShell

Avvertimento

I client PowerShell spesso aggiungono \ a " in settings.json, causando errori di akvvm_service con errore: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

È possibile usare Azure PowerShell per distribuire l'estensione di macchina virtuale Key Vault in una macchina virtuale o un set di scalabilità di macchine virtuali esistente.

  • Per distribuire l'estensione in una macchina virtuale:

L'estensione vm di Azure Key Vault può essere distribuita con Azure PowerShell. Salvare le impostazioni dell'estensione macchina virtuale di Key Vault in un file JSON (settings.json).

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione vm di Key Vault con 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"
   }      
}
  • Per distribuire l'estensione 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 "3.0" -ResourceGroupName <ResourceGroupName> -Location <Location> -VMName <VMName> -Name $extName -Publisher $extPublisher -Type $extType -SettingString $settings
  • Per distribuire l'estensione in un 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 "3.0" -Setting $settings
    
    # Start the deployment
    Update-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName> -VirtualMachineScaleSet $vmss

Distribuzione di Azure CLI

Per distribuire l'estensione macchina virtuale di Key Vault in una macchina virtuale o un set di scalabilità di macchine virtuali esistente è possibile usare l'interfaccia della riga di comando di Azure.

  • Per distribuire l'estensione in una macchina virtuale:

L'estensione vm di Azure Key Vault può essere distribuita usando l'interfaccia della riga di comando di Azure. Salvare le impostazioni dell'estensione macchina virtuale di Key Vault in un file JSON (settings.json).

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione vm di Key Vault con l'interfaccia della riga di comando di Azure.

{
   "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"
   }      
}
  • Per distribuire l'estensione in una macchina virtuale

    # 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"
  • Per distribuire l'estensione in un set di scalabilità di macchine virtuali:
    # 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"

Tenere presenti le restrizioni e i requisiti seguenti:

  • Restrizioni di Key Vault:
    • Deve essere già presente al momento della distribuzione
    • Il ruolo utente Dei segreti dell'insieme di credenziali delle chiavi deve essere assegnato all'insieme di credenziali delle chiavi per l'identità della macchina virtuale

Risolvere i problemi e il supporto

I dati sullo stato delle distribuzioni dell'estensione possono essere recuperati nel portale di Azure e tramite Azure PowerShell. Per visualizzare lo stato di distribuzione delle estensioni per una macchina virtuale specifica, eseguire il comando seguente tramite Azure PowerShell.

Azure PowerShell

Get-AzVMExtension -VMName <vmName> -ResourceGroupname <resource group name>

Interfaccia della riga di comando di Azure

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

L'interfaccia della riga di comando di Azure può essere eseguita in diversi ambienti della shell, ma con lievi variazioni di formato. Se si hanno risultati imprevisti con i comandi dell'interfaccia della riga di comando di Azure, vedere Come usare correttamente l'interfaccia della riga di comando di Azure.

Log e configurazione

I log delle estensioni della macchina virtuale dell'insieme di credenziali delle chiavi sono presenti localmente nella macchina virtuale e sono più informativi per la risoluzione dei problemi. È possibile usare la sezione di registrazione facoltativa per l'integrazione con il provider di registrazione tramite fluentd

Posizione Descrizione
/var/log/waagent.log Indica quando si è verificato un aggiornamento dell'estensione.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Esaminare i log del servizio dell'estensione macchina virtuale di Key Vault per determinare lo stato del servizio e del download del certificato akvvm_service. È possibile trovare il percorso di download dei file PEM nei file con una voce denominata nome file di certificato. Se certificateStoreLocation non è specificato, per impostazione predefinita verrà impostato su /var/lib/waagent/Microsoft.Azure.KeyVault.Store/
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-most< recent version>/config/* Configurazione e file binari per il servizio dell'estensione vm di Key Vault.

I collegamenti simbolici o i collegamenti simbolici sono collegamenti avanzati. Per evitare di monitorare la cartella e ottenere automaticamente il certificato più recente, è possibile usare questo collegamento ([VaultName].[CertificateName]) simbolico per ottenere la versione più recente del certificato in Linux.

Installazione dei certificati in Linux

L'estensione macchina virtuale Key Vault per Linux installa i certificati come file PEM con la catena di certificati completa inclusa. Quando un certificato viene scaricato da Key Vault, l'estensione:

  1. Crea una cartella di archiviazione in base all'impostazione certificateStoreLocation (impostazione predefinita, /var/lib/waagent/Microsoft.Azure.KeyVault.Store/ se non specificata)
  2. Installa la catena di certificati completa e la chiave privata in un file PEM che segue la sezione 5246 RFC 7.4.2 in questo ordine specifico:
    • Il certificato foglia (certificato di entità finale) viene emesso per primo
    • I certificati intermedi seguono nell'ordine, in cui ogni certificato certifica direttamente quello prima
    • Certificato radice, se presente (anche se non è necessario per la convalida se già considerato attendibile dal sistema)
    • La chiave privata, corrispondente al certificato terminale, viene inserita alla fine del file
  3. Crea automaticamente un collegamento simbolico denominato [VaultName].[CertificateName] che punta alla versione più recente del certificato

Questo approccio garantisce che:

  • Le applicazioni hanno sempre accesso alla catena di certificati completa necessaria per la convalida
  • La catena di certificati è ordinata correttamente per gli handshake TLS in base agli standard RFC
  • La chiave privata è disponibile per l'uso da parte del servizio
  • Le applicazioni possono fare riferimento a un percorso di collegamento simbolico stabile che viene aggiornato automaticamente quando vengono rinnovati i certificati
  • Non è necessaria alcuna riconfigurazione dell'applicazione quando i certificati vengono ruotati o rinnovati

Esempio di struttura del percorso del certificato

Per un certificato da exampleVault.vault.azure.net con il nome myCertificate, la struttura di directory sarà simile alla seguente:

/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)

Le applicazioni devono essere configurate per usare il percorso di collegamento simbolico (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate) per assicurarsi che accegano sempre alla versione del certificato più recente.

Quando si usano percorsi personalizzati dell'archivio certificati e l'impostazione customSymbolicLinkName , la struttura segue questo modello:

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

Domande frequenti

  • Esiste un limite per il numero di certificati osservati che è possibile configurare? No, l'estensione della macchina virtuale di Key Vault non ha limiti al numero di certificati osservati.

Assistenza

Per ricevere assistenza in relazione a qualsiasi punto di questo articolo, contattare gli esperti di Azure nei forum MSDN e Stack Overflow relativi ad Azure. In alternativa, è possibile archiviare un evento imprevisto di supporto tecnico di Azure. Accedere al sito del supporto di Azure e selezionare l'opzione desiderata per ottenere supporto. Per informazioni sull'uso del supporto di Azure, leggere le Domande frequenti sul supporto di Azure.