Azure Key Vault Erweiterung virtueller Computer für Linux

Die Azure Key Vault-Erweiterung für virtuelle Computer (VMs) aktualisiert automatisch im Azure Key Vault gespeicherte Zertifikate. Die Erweiterung überwacht eine Liste der in Schlüsseltresoren gespeicherten, berücksichtigten Zertifikate. Wenn die Erweiterung eine Änderung erkennt, ruft sie die entsprechenden Zertifikate ab und installiert sie. In diesem Artikel werden die unterstützten Plattformen, Konfigurationen und Bereitstellungsoptionen für die Key Vault VM-Erweiterung für Linux beschrieben.

Betriebssysteme

Die Key Vault-VM-Erweiterung unterstützt Folgendes:

• Ubuntu 22.04 und höher.
• Azure Linux.

Unterstützte Zertifikatsinhaltstypen

• PKCS #12
• PEM

Features

Die Key Vault-VM-Erweiterung für Linux, Version 3.0 und höher, unterstützt:

• ACL-Berechtigungen für heruntergeladene Zertifikate, um Lesezugriff für Benutzer und Gruppen bereitzustellen.
• Konfiguration des Installationsorts für Zertifikate.
• Unterstützung für benutzerdefinierte symbolische Namen.
• Integration der Protokollierung von VM-Erweiterungen über Fluentd.

Voraussetzungen

• Eine Azure Key Vault-Instanz mit einem Zertifikat. Weitere Informationen finden Sie unter Einen Schlüsseltresor mit dem Azure-Portal erstellen.

• Virtuelle Maschinen oder Azure Virtual Machine Scale Sets mit zugewiesener verwalteter Identität.

• Die Rolle Key Vault Secrets User auf der Bereichsebene von Key Vault für die verwaltete Identität von virtuellen Computern und Azure Virtual Machine Scale Sets. Diese Rolle ruft den Zertifikatteil eines Geheimnisses ab. Weitere Informationen finden Sie in den folgenden Artikeln:

  • Authentifizierung in Azure Key Vault.
  • Verwenden Sie Azure RBAC-Berechtigungen für Geheimnisse, Schlüssel und Zertifikate mit Azure Key Vault.
  • Rollenzuweisung für den Key Vault-Bereich.

• Azure Virtual Machine Scale Sets sollte die folgende Identitätseinstellung aufweisen:

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

• Die Key Vault VM-Erweiterung sollte die folgende Einstellung haben:

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

Aktualisieren der Key Vault-VM-Erweiterung

• Um ein Upgrade von einer älteren Version auf Version 3.0 oder höher durchzuführen, löschen Sie die vorherige Version, und installieren Sie dann Version 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"

• Wenn der virtuelle Computer Zertifikate enthält, die von der vorherigen Version heruntergeladen wurden, löscht das Löschen der VM-Erweiterung die heruntergeladenen Zertifikate nicht. Nachdem Sie die neuere Version installiert haben, ändert die Erweiterung die vorhandenen Zertifikate nicht. Löschen Sie die Zertifikatdateien, oder führen Sie einen Rollover des Zertifikats durch, um die PEM-Datei mit der vollständigen Kette auf dem virtuellen Computer abzurufen.

Erweiterungsschema

Der folgende JSON-Code stellt das Schema für die Erweiterung "Key Vault VM" bereit. Alle Einstellungen verwenden einfache, nicht geschützte Einstellungen, da die Einstellungen keine vertraulichen Informationen enthalten. Um die Erweiterung zu konfigurieren, geben Sie eine Liste der zu überwachenden Zertifikate an, wie oft Updates abgerufen werden sollen, und den Zielpfad zum Speichern von Zertifikaten.

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

Immobilienwerte

Bereitstellung von Vorlagen

Sie können Azure-VM-Erweiterungen mithilfe von Azure Resource Manager-Vorlagen bereitstellen. Vorlagen sind ideal, wenn Sie einen oder mehrere virtuelle Computer bereitstellen, die eine Aktualisierung von Zertifikaten nach der Bereitstellung erfordern. Sie können die Erweiterung für einzelne VMs oder Azure Virtual Machine Scale Sets bereitstellen. Das Schema und die Konfiguration sind für beide Vorlagentypen gleich.

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

Reihenfolge von Erweiterungsabhängigkeiten

Die Key Vault VM-Erweiterung unterstützt die Erweiterungsbestellung, wenn Sie sie konfigurieren. Standardmäßig meldet die Erweiterung einen erfolgreichen Start, sobald die Abfrage gestartet wird. Sie können sie so konfigurieren, dass gewartet wird, bis sie die vollständige Liste der Zertifikate erfolgreich herunterlädt, bevor sie einen erfolgreichen Start meldet. Wenn andere Erweiterungen von installierten Zertifikaten abhängen, bevor sie beginnen, aktivieren Sie diese Einstellung. Diese Erweiterungen können dann eine Abhängigkeit von der Key Vault Erweiterung deklarieren. Diese Einstellung verhindert, dass diese Erweiterungen gestartet werden, bis alle Zertifikate installiert sind, von denen sie abhängen.

Die Erweiterung wiederholt den anfänglichen Download bis zu 25 Mal mit zunehmenden Backoff-Zeiträumen, in denen sie in einem Transitioning Zustand verbleibt. Wenn alle Wiederholungsversuche aufgebraucht sind, meldet die Erweiterung einen Error-Zustand.

Legen Sie zum Aktivieren der Erweiterungsabhängigkeit Folgendes fest:

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

Azure PowerShell-Bereitstellung

Verwenden Sie Azure PowerShell, um die Key Vault-VM-Erweiterung für einen vorhandenen virtuellen Computer oder eine vorhandene VM-Skalierungsgruppe bereitzustellen.

Speichern Sie Key Vault VM-Erweiterungseinstellungen in einer JSON-Datei namens settings.json.

Die folgenden JSON-Codeausschnitte stellen Beispieleinstellungen für die Bereitstellung der Key Vault-VM-Erweiterung mithilfe von PowerShell bereit.

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

Bereitstellen auf einem virtuellen Computer mithilfe von 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

Bereitstellen in einer VM-Skalierungsgruppe mit 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

Bereitstellung mithilfe der Azure-Befehlszeilenschnittstelle

Verwenden Sie die Azure CLI, um die Key Vault-VM-Erweiterung für einen vorhandenen virtuellen Computer oder eine vorhandene Skalierungsgruppe für virtuelle Computer bereitzustellen.

Speichern Sie Key Vault VM-Erweiterungseinstellungen in einer JSON-Datei namens settings.json.

Die folgenden JSON-Codeausschnitte stellen Beispieleinstellungen für die Bereitstellung der Key Vault VM-Erweiterung mithilfe der Azure CLI bereit.

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

Bereitstellen auf einem virtuellen Computer mithilfe der Azure CLI

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

Bereitstellen in einer Skalierungsgruppe virtueller Computer mithilfe der Azure CLI

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

Überprüfen Sie die folgenden Einschränkungen und Anforderungen:

• Key Vault-Einschränkungen:
  • Der Schlüsseltresor muss zum Zeitpunkt der Bereitstellung vorhanden sein.
  • Die Rolle "Key Vault Geheimer Benutzer" muss Key Vault für die VM-Identität zugewiesen werden.

Problembehandlung und Support

Rufen Sie Daten über den Status der Erweiterungsbereitstellungen aus dem Azure-Portal oder mithilfe von Azure PowerShell oder der Azure CLI ab. Führen Sie 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 CLI:

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

Die Azure CLI kann mit geringfügigen Formatvariationen in verschiedenen Shellumgebungen ausgeführt werden. Wenn Sie unerwartete Ergebnisse mit Azure CLI-Befehlen haben, erfahren Sie, wie Sie die Azure CLI erfolgreich verwenden.

Protokolle und Konfiguration

Die Key Vault VM-Erweiterungsprotokolle sind lokal auf dem virtuellen Computer vorhanden und sind für die Problembehandlung am informativsten. Verwenden Sie den optionalen Abschnitt für die Protokollierung, um mithilfe von fluentd eine Integration mit einem Protokollierungsanbieter vorzunehmen.

Verwenden symbolischer Verknüpfungen

Symbolische Verknüpfungen sind erweiterte Tastenkombinationen. Um die Überwachung des Ordners zu vermeiden und das neueste Zertifikat automatisch abzurufen, verwenden Sie die [VaultName].[CertificateName] symbolische Verknüpfung, um die neueste Zertifikatversion unter Linux abzurufen.

Zertifikatinstallation unter Linux

Die Key Vault VM-Erweiterung für Linux installiert Zertifikate als PEM-Dateien. Wenn die Erweiterung ein Zertifikat von Key Vault herunterlädt, lautet dies:

1. Erstellt einen Speicherordner basierend auf der certificateStoreLocation Einstellung. Wenn Sie diese Einstellung nicht angeben, wird /var/lib/waagent/Microsoft.Azure.KeyVault.Store/standardmäßig der Speicherort verwendet.
2. Installiert die Zertifikatkette und den privaten Schlüssel, wie in Key Vault gespeichert. Die PEM-Datei folgt der in RFC 5246 Abschnitt 7.4.2 festgelegten Reihenfolge:
   • Das Endentitätszertifikat, auch Leaf-Zertifikat genannt, steht an erster Stelle.
   • Zwischenzertifikate folgen in der Reihenfolge, in der jedes Zertifikat direkt das Zertifikat vor ihm zertifiziert, sofern in Key Vault vorhanden.
   • Stammzertifikat, falls vorhanden. Das Stammzertifikat ist für die Überprüfung nicht erforderlich, wenn das System es bereits als vertrauenswürdig angibt.
   • Die Erweiterung platziert den privaten Schlüssel, der dem Blattzertifikat am Ende der Datei entspricht.
3. Erstellt automatisch einen symbolischen Link, [VaultName].[CertificateName] der auf die neueste Version des Zertifikats verweist.

Dieser Installationsansatz stellt Folgendes sicher:

• Anwendungen haben Zugriff auf die Zertifikatkette, wie in Key Vault gespeichert.
• Die Zertifikatkette ist für TLS-Handshakes gemäß den RFC-Standards geordnet.
• Der private Schlüssel steht für die Verwendung durch den Dienst zur Verfügung.
• Anwendungen können auf einen stabilen symbolischen Verknüpfungspfad verweisen, der automatisch aktualisiert wird, wenn Zertifikate erneuert werden.
• Es ist keine Neukonfiguration der Anwendung erforderlich, wenn Zertifikate gedreht oder erneuert werden.

Beispielstruktur des Zertifikatpfads

Für ein Zertifikat exampleVault.vault.azure.net mit dem Namen myCertificatesieht die Verzeichnisstruktur wie folgt aus:

/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)

Konfigurieren Sie Anwendungen für die Verwendung des symbolischen Verknüpfungspfads (/var/lib/waagent/Microsoft.Azure.KeyVault.Store/exampleVault.myCertificate). Diese Konfiguration stellt sicher, dass Anwendungen immer auf die neueste Zertifikatversion zugreifen.

Wenn Sie benutzerdefinierte Speicherorte des Zertifikatspeichers und die customSymbolicLinkName Einstellung verwenden, folgt die Struktur diesem Muster:

/path/to/custom/store/
├── customLinkName -> exampleVault.myCertificate.1234567890abcdef
└── exampleVault.myCertificate.1234567890abcdef    # Full chain PEM file

Häufig gestellte Fragen

Gibt es ein Limit für die Anzahl der beobachteten Zertifikate, die ich konfigurieren kann?

No. Die Vm-Erweiterung "Key Vault" beschränkt nicht die Anzahl der beobachteten Zertifikate (observedCertificates).

Unterstützung erhalten

Microsoft bietet nur Unterstützung für die Hauptversion 3.0 und höher der Key Vault VM-Erweiterung. Wenn Sie Version 1.0 verwenden, führen Sie ein Upgrade auf die neueste Version durch, bevor Sie Support anfordern.

Hier sind einige weitere Optionen, mit denen Sie Bereitstellungsprobleme beheben können:

• Um Hilfe zu erhalten, wenden Sie sich an die Azure Experten in Microsoft Q& A.
• Wenn Sie keine Antwort auf der Website finden, posten Sie eine Frage zur Eingabe von Microsoft oder anderen Mitgliedern der Community.
• Sie können auch Microsoft-Support kontaktieren. Informationen zur Verwendung von Azure-Support finden Sie unter How to create an Azure-Support request.