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 archivi di 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 supporta:

• Ubuntu 22.04 e versioni successive.
• Azure Linux.

Tipi di contenuto del certificato supportati

• PKCS #12
• PEM

Funzionalità

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

• Autorizzazioni ACL per i certificati scaricati per fornire l'accesso in lettura per utenti e gruppi.
• Configurazione del percorso di installazione del certificato.
• Supporto dei nomi simbolici personalizzati.
• Integrazione dei log delle estensioni della macchina virtuale tramite Fluentd.

Prerequisiti

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

• Macchine virtuali o Set di scalabilità di macchine virtuali di Azure a cui è stata assegnata un'identità gestita.

• Il ruolo Utente dei segreti di Key Vault a livello dell'ambito di Key Vault per l'identità gestita su VM e Set di scalabilità di macchine virtuali di Azure. Questo ruolo recupera la parte di un segreto di un certificato. Per altre informazioni, vedere gli articoli seguenti:

  • Autenticazione in Azure Key Vault.
  • Usare le autorizzazioni per segreti, chiavi e certificati di Azure RBAC con Azure Key Vault.
  • Assegnazione di ruolo dell'ambito di Key Vault.

• Set di scalabilità di macchine virtuali di Azure deve avere l'impostazione di identità seguente:

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

• L'estensione Key Vault macchina virtuale deve avere l'impostazione seguente:

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

Aggiornare l'estensione della macchina virtuale Key Vault

• Per eseguire l'aggiornamento da una versione precedente alla versione 3.0 o successiva, eliminare la versione precedente e 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 comporta l'eliminazione dei certificati scaricati. Dopo aver installato la versione più recente, l'estensione non modifica i certificati esistenti. Eliminare i file di certificato o eseguire il rollover del certificato per ottenere il file PEM con la catena completa nella macchina virtuale.

Schema dell'estensione

Il codice JSON seguente fornisce lo schema per l'estensione della macchina virtuale Key Vault. Tutte le impostazioni usano impostazioni semplici e non protette perché le impostazioni non contengono informazioni riservate. Per configurare l'estensione, 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.

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

Valori delle proprietà

Distribuzione di template

Le estensioni macchina virtuale di Azure possono essere distribuite usando i modelli di Azure Resource Manager. 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 Set di scalabilità di macchine virtuali di Azure. Lo schema e la configurazione sono comuni a entrambi i tipi di modello.

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

Ordinamento delle dipendenze dell'estensione

L'estensione della macchina virtuale Key Vault supporta l'ordinamento delle estensioni se viene configurato. Per impostazione predefinita, l'estensione segnala un avvio riuscito non appena viene avviato il polling. È possibile configurarlo in modo da attendere fino a quando non scarica correttamente l'elenco completo dei certificati prima che venga segnalato un avvio riuscito. Se altre estensioni dipendono dai certificati installati prima dell'avvio, abilitare questa impostazione. Tali estensioni possono quindi dichiarare una dipendenza dall'estensione Key Vault. Questa impostazione impedisce l'avvio di tali estensioni fino a quando non vengono installati tutti i certificati da cui dipendono.

L'estensione ritenta il download iniziale fino a 25 volte con intervalli di backoff via via più lunghi, durante i quali rimane in stato di Transitioning. Se i tentativi sono esauriti, l'estensione segnala uno stato Error.

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

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

distribuzione Azure PowerShell

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

Salvare le impostazioni dell'estensione della VM di Key Vault in un file JSON denominato settings.json.

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione macchina virtuale Key Vault tramite 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"
   }
}

Eseguire la distribuzione in una macchina virtuale usando 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

Eseguire la distribuzione in un set di scalabilità di macchine virtuali usando 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

distribuzione di interfaccia della riga di comando di Azure

Usa interfaccia della riga di comando di Azure per distribuire l'estensione VM di Key Vault a una macchina virtuale esistente o a un set di scalabilità di macchine virtuali esistente.

Salvare le impostazioni dell'estensione VM di Key Vault in un file JSON denominato settings.json.

I frammenti di codice JSON seguenti forniscono impostazioni di esempio per la distribuzione dell'estensione macchina virtuale Key Vault usando il 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"
   }
}

Eseguire la distribuzione in una macchina virtuale usando il interfaccia della riga di comando di Azure

# 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"

Eseguire la distribuzione in un set di scalabilità di macchine virtuali usando il interfaccia della riga di comando di Azure

# 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"

Esaminare le restrizioni e i requisiti seguenti:

• Key Vault restrizioni:
  • Il key vault deve esistere al momento della distribuzione.
  • Il ruolo Key Vault Secrets User deve essere assegnato a Key Vault per l'identità della VM.

Risoluzione dei problemi e supporto

Recuperare i dati sullo stato delle distribuzioni di estensioni dal portale di Azure oppure usando Azure 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 -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"

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.

Log e configurazione

I log delle estensioni della macchina virtuale Key Vault esistono localmente nella macchina virtuale e sono più informativi per la risoluzione dei problemi. Usare la sezione di registrazione facoltativa per l'integrazione con un provider di registrazione tramite fluentd.

Usare collegamenti simbolici

I collegamenti simbolici sono scorciatoie avanzate. Per evitare di monitorare la cartella e ottenere automaticamente il certificato più recente, usare il [VaultName].[CertificateName] collegamento simbolico per ottenere la versione più recente del certificato in Linux.

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. Installa la catena di certificati e la chiave privata archiviata in Key Vault. Il file PEM segue l'ordinamento RFC 5246 sezione 7.4.2 :
   • Il certificato foglia, o il certificato di entità finale, viene prima di tutto.
   • I certificati intermedi seguono l'ordine in cui ogni certificato certifica direttamente quello precedente, se presente in Key Vault.
   • Certificato radice, se presente. Il certificato radice non è necessario per la convalida se il sistema lo considera già attendibile.
   • L'estensione inserisce la chiave privata corrispondente al certificato finale alla fine del file.
3. Crea automaticamente un collegamento simbolico denominato [VaultName].[CertificateName] che punta alla versione più recente del certificato.

Questo approccio di installazione garantisce che:

• Le applicazioni hanno accesso alla catena di certificati archiviata in Key Vault.
• La catena di certificati viene ordinata 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.

Struttura del percorso del certificato di esempio

Per un certificato da exampleVault.vault.azure.net con il nome myCertificate, la struttura di directory è 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)

Configurare le applicazioni per l'uso del percorso di collegamento simbolico (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate). Questa configurazione garantisce che le applicazioni accervino 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 al numero di certificati osservati che è possibile configurare?

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

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.

Ecco alcune altre opzioni che consentono di risolvere i problemi di distribuzione:

• Per assistenza, contattare gli esperti Azure in Microsoft Q& A.
• Se non si trova una risposta nel sito, pubblicare una domanda per l'input da Microsoft o da altri membri della community.
• È anche possibile contattare supporto tecnico Microsoft. Per informazioni sull'uso di supporto tecnico di Azure, vedere Come creare una richiesta di supporto tecnico di Azure.