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 Key Vault-VM-Erweiterung lädt die Zertifikate in den Standardspeicherort oder den durch die Eigenschaft „certStoreLocation“ in den Einstellungen der VM-Erweiterung 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

Voraussetzungen

Key Vault-VM-Erweiterungsversion

  • Benutzer*innen können ein Upgrade ihrer Key Vault-VM-Erweiterungsversion auf V2.0 durchführen, um das Feature für den Download der vollständigen Zertifikatkette zu verwenden. Ausstellerzertifikate (Zwischen- und Stammzertifikate) sind mit ihren Blattzertifikaten in der PEM-Datei enthalten.

  • Wenn Sie ein Upgrade auf v2.0 durchführen möchten, müssen Sie v1.0 zuerst löschen und dann v2.0 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 2.0

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

  • Falls die VM Zertifikate von v1.0 heruntergeladen hat, führt das Löschen der v1.0-AKVVM-Erweiterung nicht zum Löschen der heruntergeladenen Zertifikate. Nach der Installation von v2.0 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": "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".>
        }
       }
      }
    }

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 2,0 INT
pollingIntervalInS 3600 Zeichenfolge
certificateStoreName Wird unter Linux ignoriert Zeichenfolge
linkOnRenewal false boolean
certificateStoreLocation /var/lib/waagent/Microsoft.Azure.KeyVault.Store Zeichenfolge
requireInitialSync true boolean
observedCertificates ["https://myvault.vault.azure.net/secrets/mycertificate", "https://myvault.vault.azure.net/secrets/mycertificate2"] Zeichenfolgenarray
msiEndpoint http://169.254.169.254/metadata/identity Zeichenfolge
msiClientId c7373ae5-91c2-4165-8ab6-7381d6e75619 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": "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"
        }
      }
      }
    }

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:

        # 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

  • So stellen Sie die Erweiterung in einer VM-Skalierungsgruppe bereit

    
    # 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

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:

       # 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> \"] }}'

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

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

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 nur lokal auf dem virtuellen Computer vorhanden und bei der Problembehandlung am informativsten.

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.