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 della macchina virtuale dell'insieme di credenziali delle chiavi scarica i certificati nel percorso predefinito o nel percorso fornito dalla proprietà "certStoreLocation" nelle impostazioni dell'estensione della macchina virtuale. 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

Prerequisiti

Versione dell'estensione della macchina virtuale di Key Vault

  • Gli utenti possono scegliere di aggiornare la versione dell'estensione vm di Key Vault per V2.0 usare la funzionalità di download completa della catena di certificati. I certificati dell'autorità di certificazione (intermedio e radice) sono inclusi nel certificato foglia nel file PEM.

  • Se si preferisce eseguire l'aggiornamento a v2.0, è necessario prima eliminare v1.0 , quindi installare v2.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 2.0

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

  • Se la macchina virtuale dispone di certificati scaricati dalla versione 1.0, l'eliminazione dell'estensione AKVVM v1.0 non elimina i certificati scaricati. Dopo l'installazione della versione 2.0, 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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
        "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <It's ignored on Linux>,
          "linkOnRenewal": <Not available on Linux e.g.: false>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "requireInitialSync": <initial synchronization of certificates e..g: true>,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"]>
        },
        "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".>
        }
       }
      }
    }

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à 'authentication Impostazioni' è 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 2.0 int
pollingIntervalInS 3600 string
certificateStoreName Viene ignorato in Linux string
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store string
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] Matrice di stringhe
msiEndpoint http://169.254.169.254/metadata/identity string
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 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": "2.0",
      "autoUpgradeMinorVersion": true,
      "enableAutomaticUpgrade": true,
      "settings": {
          "secretsManagementSettings": {
          "pollingIntervalInS": <polling interval in seconds, e.g. "3600">,
          "certificateStoreName": <ingnored on linux>,
          "certificateStoreLocation": <disk path where certificate is stored, default: "/var/lib/waagent/Microsoft.Azure.KeyVault">,
          "observedCertificates": <list of KeyVault URIs representing monitored certificates, e.g.: "https://myvault.vault.azure.net/secrets/mycertificate"
        }
      }
      }
    }

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 per 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:

        # Build settings
    $settings = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName =  "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"


    # Start the deployment
    Set-AzVmExtension -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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 = '{"secretsManagementSettings":
    { "pollingIntervalInS": "' + <pollingInterval> +
    '", "certificateStoreName": "' + <certStoreName> +
    '", "certificateStoreLocation": "' + <certStoreLoc> +
    '", "observedCertificates": ["' + <observedCert1> + '","' + <observedCert2> + '"] } }'
    $extName = "KeyVaultForLinux"
    $extPublisher = "Microsoft.Azure.KeyVault"
    $extType = "KeyVaultForLinux"

    # Add Extension to VMSS
    $vmss = Get-AzVmss -ResourceGroupName <ResourceGroupName> -VMScaleSetName <VmssName>
    Add-AzVmssExtension -VirtualMachineScaleSet $vmss  -Name $extName -Publisher $extPublisher -Type $extType -TypeHandlerVersion "2.0" -EnableAutomaticUpgrade true -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:

       # Start the deployment
     az vm extension set -n "KeyVaultForLinux" `
     --publisher Microsoft.Azure.KeyVault `
     -g "<resourcegroup>" `
     --vm-name "<vmName>" `
     --version 2.0 `
     --enable-auto-upgrade true `
     --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

  • 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 2.0 `
      --enable-auto-upgrade true `
      --settings '{\"secretsManagementSettings\": { \"pollingIntervalInS\": \"<pollingInterval>\", \"certificateStoreName\": \"<certStoreName>\", \"certificateStoreLocation\": \"<certStoreLoc>\", \"observedCertificates\": [\" <observedCert1> \", \" <observedCert2> \"] }}'

Tenere presenti le restrizioni e i requisiti seguenti:

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 dell'estensione della macchina virtuale di Key Vault esistono solo in locale nella macchina virtuale e sono più informativi per la risoluzione dei problemi.

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