Condividi tramite

Estensione macchina virtuale di Key Vault per Linux

  • Articolo

L'estensione macchina virtuale di Key Vault offre l'aggiornamento automatico dei certificati archiviati in un insieme di credenziali delle chiavi 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 macchina virtuale di Key Vault supporta queste distribuzioni Linux:

Nota

L'estensione macchina virtuale key vault scarica i certificati nel percorso predefinito o nel percorso specificato dalla proprietà "certStoreLocation" nelle impostazioni dell'estensione della macchina virtuale (versione 1/2) o nelle singole impostazioni del certificato (versione 3). L'estensione della macchina virtuale di Key Vault aggiorna l'autorizzazione della cartella a 700 (drwx------) consentendo l'autorizzazione di lettura, scrittura ed esecuzione solo per il proprietario della cartella

Tipi di contenuto del certificato supportati

  • PKCS #12
  • PEM

Aggiornamenti nella versione 3.0+

La versione 3.0+ dell'estensione della macchina virtuale Key Vault per Linux aggiunge il supporto per le funzionalità seguenti:

  • 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

Versione dell'estensione della macchina virtuale di Key Vault

  • Gli utenti possono scegliere di aggiornare la versione esistente dell'estensione della macchina virtuale di Key Vault alla versione più recente.

  • Se si preferisce eseguire l'aggiornamento alla versione più recente, è prima necessario eliminare la versione precedente, quindi installare la versione più recente.

  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

Il flag --version 3.0 è facoltativo perché la versione più recente è installata per impostazione predefinita.

  • Se la macchina virtuale dispone di certificati scaricati dalla versione precedente, l'eliminazione dell'estensione della macchina virtuale non elimina i certificati scaricati. Dopo l'installazione della 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 codice JSON seguente mostra lo schema per l'estensione di macchina virtuale Key Vault. L'estensione non richiede impostazioni protette. Tutte le impostazioni sono considerate informazioni senza alcun impatto sulla sicurezza. L'estensione richiede un elenco di segreti monitorati, la frequenza di polling e l'archivio dei certificati di destinazione. 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.: "c7373ae5-91c2-4165-8ab6-7381d6e75619".>
        }>
       }
      }
    }

Nota

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 data
publisher Microsoft.Azure.KeyVault string
type KeyVaultForLinux string
typeHandlerVersion 3.0 int
pollingIntervalInS 3600 string
certificateStoreName Viene ignorato in Linux string
linkOnRenewal false boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
observedCertificates [{...}, {...}] Matrice di stringhe
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" string
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" string
observedCertificates/customSymbolicLinkName (facoltativo) "app1Cert1" string
observedCertificates/acls (facoltativo) "{...}, {...}" Matrice di stringhe
authenticationSettings (facoltativo) {...} oggetto
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity string
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 string
loggingSettings (facoltativo) {...} oggetto
loggingSettings/logger "fluentd" string
loggingSettings/endpoint "tcp://localhost:24224" string
loggingSettings/format "forward" string
loggingSettings/servicename "akvvm_service" string

Distribuzione del modello

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.

La configurazione JSON per un'estensione macchina virtuale deve essere annidata all'interno del frammento di risorsa della macchina virtuale del modello, in particolare "resources": [] per l'oggetto per il modello di macchina virtuale e per un set di scalabilità di macchine virtuali nell'oggetto "virtualMachineProfile":"extensionProfile":{"extensions" :[] .

Nota

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.: "c7373ae5-91c2-4165-8ab6-7381d6e75619">
          }
        } 
      }
    }

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 ritenta il download iniziale a tempo indeterminato e rimarrà in uno Transitioning stato.

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

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

Nota

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

Avviso

I client PowerShell spesso vengono aggiunti \" alla settings.json che causano 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 dell'interfaccia della riga di comando di Azure

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

Ufficio 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.

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.

Supporto tecnico

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.