Teilen über

Key Vault-VM-Erweiterung für Linux

  • Artikel

Die Key Vault-VM-Erweiterung ermöglicht die automatische Aktualisierung von Zertifikaten, die in einem Azure-Schlüsseltresor gespeichert sind. Die Erweiterung überwacht insbesondere eine Liste der in Schlüsseltresoren gespeicherten, berücksichtigten Zertifikate. Die Erweiterung ruft die entsprechenden Zertifikate ab und installiert sie, sobald eine Änderung festgestellt wird. Dieses Dokument enthält ausführliche Informationen zu den unterstützten Plattformen, Konfigurationen und Bereitstellungsoptionen für die Key Vault-VM-Erweiterung für Linux.

Betriebssystem

Die Key Vault-VM-Erweiterung unterstützt folgende Linux-Distributionen:

Hinweis

Die VM-Erweiterung des Key Vault lädt die Zertifikate in den Standardspeicherort oder den durch die Eigenschaft „certStoreLocation“ in den Einstellungen der VM-Erweiterung (Version 1/2) oder in den individuellen Zertifikateinstellungen (Version 3) angegebenen Speicherort herunter. Die Key Vault-VM-Erweiterung aktualisiert die Ordnerberechtigung auf „700 (drwx------)“ und erteilt damit nur dem Besitzer des Ordners Lese-, Schreib- und Ausführungsberechtigungen.

Unterstützte Zertifikatsinhaltstypen

  • PKCS #12
  • PEM

Aktualisierungen in Version 3.0+

Die Version 3.0 oder höher der VM-Erweiterung des Key Vault für Linux unterstützt die folgenden Features:

  • Hinzufügen von ACL-Berechtigungen für heruntergeladene Zertifikate, um Lesezugriff für Benutzer und Gruppen zu ermöglichen
  • Konfigurationsstandort der Zertifikatinstallation
  • Unterstützung für benutzerdefinierte symbolische Namen
  • Unterstützung der Integration der VM-Erweiterungsprotokollierung über Fluentd

Voraussetzungen

Key Vault-VM-Erweiterungsversion

  • Benutzer können ihre vorhandene VM-Erweiterungsversion des Key Vault auf eine neuere Version aktualisieren.

  • Wenn Sie ein Upgrade auf eine neuere Version bevorzugen, müssen Sie zuerst die vorherige Version löschen und dann eine neuere Version installieren.

  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

Das Flag „--version 3.0“ ist optional, da standardmäßig die neueste Version installiert wird.

  • Wenn die VM Zertifikate einer früheren Version heruntergeladen hat, werden durch das Löschen der VM-Erweiterung die heruntergeladenen Zertifikate nicht entfernt. Nach der Installation einer neueren Version werden die vorhandenen Zertifikate nicht geändert. Sie müssen die Zertifikat-Dateien oder das Rollover des Zertifikats löschen, um die PEM-Datei mit vollständiger Kette auf der VM zu erhalten.

Erweiterungsschema

Im folgenden JSON-Code ist das Schema für die Key Vault-VM-Erweiterung dargestellt. Für die Erweiterung sind keine geschützten Einstellungen erforderlich. Alle Einstellungen werden als Informationen ohne Sicherheitsauswirkungen angesehen. Für die Erweiterung werden eine Liste mit überwachten Geheimnissen, die Abrufhäufigkeit und ein Zielzertifikatspeicher benötigt. Dies gilt insbesondere in folgenden Fällen:

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

Hinweis

Die URLs der berücksichtigten Zertifikate müssen das folgende Format haben: https://myVaultName.vault.azure.net/secrets/myCertName.

Der Grund hierfür ist, dass der Pfad /secrets das vollständige Zertifikat einschließlich des privaten Schlüssels zurückgibt, der Pfad /certificates hingegen nicht. Weitere Informationen zu Zertifikaten finden Sie hier: Key Vault-Zertifikate

Wichtig

Die Eigenschaft „authenticationSettings“ ist erforderlich, wenn Sie VMs mit beliebigen benutzerseitig zugewiesenen Identitäten verwenden. Selbst wenn Sie eine systemseitig zugewiesene Identität verwenden möchten, ist dies weiterhin erforderlich. Andernfalls weiß die VM-Erweiterung nicht, welche Identität verwendet werden soll. Ohne diesen Abschnitt bewirkt eine VM mit benutzerseitig zugewiesenen Identitäten, dass die Key Vault-Erweiterung fehlschlägt und Zertifikate nicht heruntergeladen werden können. Legen Sie msiClientId auf die Identität fest, die sich bei Key Vault authentifizieren soll.

Ist auch für VMs mit Azure Arc-Unterstützungerforderlich. Legen Sie msiEndpoint auf http://localhost:40342/metadata/identity fest.

Eigenschaftswerte

Name Wert/Beispiel Datentyp
apiVersion 2022-07-01 date
publisher Microsoft.Azure.KeyVault Zeichenfolge
type KeyVaultForLinux Zeichenfolge
typeHandlerVersion 3.0 INT
pollingIntervalInS 3600 Zeichenfolge
certificateStoreName Wird unter Linux ignoriert Zeichenfolge
linkOnRenewal false boolean
requireInitialSync true boolean
aclEnabled true boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store Zeichenfolge
observedCertificates [{...}, {...}] Zeichenfolgenarray
observedCertificates/url "https://myvault.vault.azure.net/secrets/mycertificate1" Zeichenfolge
observedCertificates/certificateStoreLocation "/var/lib/waagent/Microsoft.Azure.KeyVault/app1" Zeichenfolge
observedCertificates/customSymbolicLinkName (optional) "app1Cert1" Zeichenfolge
observedCertificates/acls (optional) "{...}, {...}" Zeichenfolgenarray
authenticationSettings (optional) {...} Objekt
authenticationSettings/msiEndpoint http://169.254.169.254/metadata/identity Zeichenfolge
authenticationSettings/msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 Zeichenfolge
loggingSettings (optional) {...} Objekt
loggingSettings/logger "fluentd" Zeichenfolge
loggingSettings/endpoint "tcp://localhost:24224" Zeichenfolge
loggingSettings/format "forward" Zeichenfolge
loggingSettings/servicename "akvvm_service" Zeichenfolge

Bereitstellung von Vorlagen

Azure-VM-Erweiterungen können mithilfe von Azure Resource Manager-Vorlagen bereitgestellt werden. Vorlagen sind ideal, wenn Sie virtuelle Computer bereitstellen, für die nach der Bereitstellung eine Aktualisierung der Zertifikate erforderlich ist. Die Erweiterung kann auf einzelnen virtuellen Computern oder in VM-Skalierungsgruppen bereitgestellt werden. Das Schema und die Konfiguration sind für beide Vorlagentypen gleich.

Die JSON-Konfiguration für eine VM-Erweiterung muss im VM-Ressourcenfragment der Vorlage geschachtelt sein – genauer gesagt im Objekt "resources": [] für die VM-Vorlage und bei einer VM-Skalierungsgruppe unter dem Objekt "virtualMachineProfile":"extensionProfile":{"extensions" :[].

Hinweis

Die VM-Erweiterung erfordert, dass eine system- oder benutzerverwaltete Identität für die Authentifizierung beim Schlüsseltresor zugewiesen wird. Weitere Informationen finden Sie unter Authentifizieren bei Key Vault und Zuweisen einer Key Vault-Zugriffsrichtlinie.

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

Reihenfolge von Erweiterungsabhängigkeiten

Die Key Vault-VM-Erweiterung unterstützt die Ausführung von Erweiterungen in Reihenfolge, sofern konfiguriert. Standardmäßig meldet die Erweiterung einen erfolgreichen Start, sobald der Abruf beginnt. Sie kann jedoch so konfiguriert werden, dass sie wartet, bis die gesamte Liste der Zertifikate erfolgreich heruntergeladen wurde, bevor sie einen erfolgreichen Start meldet. Wenn andere Erweiterungen davon abhängen, dass Zertifikate vor deren Start installiert werden, können diese Erweiterungen durch Aktivieren dieser Einstellung eine Abhängigkeit von der Key Vault-Erweiterung deklarieren. Dadurch wird verhindert, dass diese Erweiterungen erst gestartet werden, nachdem alle Zertifikate installiert wurden, von denen sie abhängig sind. Die Erweiterung wiederholt den ursprünglichen Download unbegrenzt oft und verbleibt im Status Transitioning.

Legen Sie zum Aktivieren der Erweiterungsabhängigkeit Folgendes fest:

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

Hinweis

Die Verwendung dieses Features ist mit einer ARM-Vorlage, die eine vom System zugewiesene Identität erstellt und eine Key Vault-Zugriffsrichtlinie mit dieser Identität aktualisiert, nicht kompatibel. Dies würde zu einem Deadlock führen, da die Key Vault-Zugriffsrichtlinie erst aktualisiert werden kann, nachdem alle Erweiterungen gestartet wurden. Verwenden Sie stattdessen eine einzelne vom Benutzer zugewiesene MSI-Identität, und wenden Sie vor der Bereitstellung eine Zugriffssteuerungsliste mit dieser Identität auf Ihre Key Vaults an.

Azure PowerShell-Bereitstellung

Warnung

PowerShell-Clients fügen " häufig \ in der Datei „settings.json“ hinzu. Dies verursacht bei akvvm_service folgenden Fehler: [CertificateManagementConfiguration] Failed to parse the configuration settings with:not an object.

Azure PowerShell kann verwendet werden, um die Key Vault-VM-Erweiterung auf einem vorhandenen virtuellen Computer oder in einer VM-Skalierungsgruppe bereitzustellen.

  • Stellen Sie die Erweiterung wie folgt auf einer VM bereit:

Die Azure Key Vault-VM-Erweiterung kann mit Azure PowerShell bereitgestellt werden. Speichern Sie die Key Vault-VM-Erweiterungseinstellungen in einer JSON-Datei (settings.json).

Die folgenden JSON-Codeschnipsel enthalten Beispieleinstellungen für die Bereitstellung der Key Vault-VM-Erweiterung mit 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"
   }      
}
  • So stellen Sie die Erweiterung in einer VM bereit:
# 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
  • So stellen Sie die Erweiterung in einer VM-Skalierungsgruppe bereit
    # 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

Bereitstellung mithilfe der Azure-Befehlszeilenschnittstelle

Die Azure-Befehlszeilenschnittstelle kann verwendet werden, um die Key Vault-VM-Erweiterung auf einem vorhandenen virtuellen Computer oder in einer VM-Skalierungsgruppe bereitzustellen.

  • Stellen Sie die Erweiterung wie folgt auf einer VM bereit:

Die Azure Key Vault-VM-Erweiterung kann mit der Azure CLI bereitgestellt werden. Speichern Sie die Key Vault-VM-Erweiterungseinstellungen in einer JSON-Datei (settings.json).

Die folgenden JSON-Codeschnipsel enthalten Beispieleinstellungen für die Bereitstellung der Key Vault-VM-Erweiterung mit der Azure CLI.

{
   "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"
   }      
}
  • So stellen Sie die Erweiterung in einer VM bereit

    # 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"
  • So stellen Sie die Erweiterung in einer VM-Skalierungsgruppe bereit
    # 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"

Beachten Sie hierbei die folgenden Einschränkungen bzw. Anforderungen:

  • Key Vault-Einschränkungen:
    • Muss zum Zeitpunkt der Bereitstellung vorhanden sein.
    • Die Rolle „Key Vault-Geheimnisbenutzer“ muss zu einem Key Vault für eine VM-Identität zugewiesen werden

Problembehandlung und Support

Daten zum Status von Erweiterungsbereitstellungen können über das Azure-Portal und mithilfe von Azure PowerShell abgerufen werden. Führen Sie über Azure PowerShell den folgenden Befehl aus, um den Bereitstellungsstatus von Erweiterungen für eine bestimmte VM anzuzeigen.

Azure PowerShell

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

Azure-Befehlszeilenschnittstelle

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

Die Azure CLI kann in mehreren Shellumgebungen ausgeführt werden, jedoch mit geringfügigen Formatvariationen. Wenn bei Azure CLI-Befehlen unerwartete Ergebnisse auftreten, lesen Sie diese Tipps für die erfolgreiche Verwendung der Azure CLI.

Protokolle und Konfiguration

Die Key Vault-VM-Erweiterungsprotokolle sind lokal auf dem virtuellen Computer vorhanden und bei der Problembehandlung am informativsten. Sie können optional den Protokollierungsabschnitt verwenden, um den Protokollierungsanbieter über fluentd zu integrieren

Standort BESCHREIBUNG
/var/log/waagent.log Zeigt an, wann ein Update der Erweiterung erfolgt ist.
/var/log/azure/Microsoft.Azure.KeyVault.KeyVaultForLinux/* Untersuchen Sie die Protokolle des Key Vault-VM-Erweiterungsdiensts, um den Status des Diensts „akvvm_service“ und des Zertifikatdownloads zu ermitteln. Sie finden den Downloadspeicherort von PEM-Dateien in Dateien mit einem Eintrag namens „Zertifikatsdateiname“. Wenn „certificateStoreLocation“ nicht angegeben ist, wird standardmäßig „/var/lib/waagent/Microsoft.Azure.KeyVault.Store/“ verwendet.
/var/lib/waagent/Microsoft.Azure.KeyVault.KeyVaultForLinux-<neueste Version>/config/* Die Konfiguration und die Binärdateien für den Key Vault-VM-Erweiterungsdienst.

Symbolische Verknüpfungen, auch als Symlinks bezeichnet, sind erweiterte Verknüpfungen. Damit Sie den Ordner nicht überwachen müssen und automatisch das neueste Zertifikat erhalten, können Sie den Symlink ([VaultName].[CertificateName]) verwenden, um die neueste Version des Zertifikats unter Linux abzurufen.

Häufig gestellte Fragen

  • Gibt es einen Grenzwert für die Anzahl von observedCertificates, die konfiguriert werden können? Nein, die Key Vault-VM-Erweiterung weist keinen Grenzwert für die Anzahl von „observedCertificates“ auf.

Support

Sollten Sie beim Lesen dieses Artikels feststellen, dass Sie weitere Hilfe benötigen, können Sie sich über das MSDN Azure-Forum oder über das Stack Overflow-Forum mit Azure-Experten in Verbindung setzen. Alternativ dazu haben Sie die Möglichkeit, einen Azure-Supportfall zu erstellen. Rufen Sie die Azure-Support-Website auf, und wählen Sie „Support erhalten“ aus. Informationen zur Nutzung von Azure-Support finden Sie unter Microsoft Azure-Support-FAQ.