Azure Key Vault secrets in Unity Catalog

Important

Dieses Feature befindet sich in der Betaversion.

Verknüpfe ein Unity-Catalog-Schema mit Azure Key Vault, um deine Azure Key Vault-Geheimnisse in Notizbüchern, Jobs und UDFs zu verwenden, ohne sie zu kopieren. Die Werte bleiben in Key Vault, und die Unity Catalog-Privilegien steuern, wer jedes Geheimnis lesen oder verwenden kann.

Im Gegensatz zu einem von Azure Key Vault unterstützten Secret Scope, der einen gesamten Azure Key Vault für einen Arbeitsbereich verfügbar macht, ist ein von Key Vault unterstütztes Unity-Catalog-Schema in jedem an den Metastore angeschlossenen Arbeitsbereich verfügbar und gewährt separat Zugriff auf jedes Geheimnis.

Um externe Geheimnisse mit von Azure Databricks verwalteten Geheimnissen und Geheimnisbereichen des Arbeitsbereichs zu vergleichen, siehe Auswählen, wo ein Geheimnis gespeichert werden soll.

Wie externe Geheimnisse funktionieren

Ein Schema ist mit einer Verbindung zu deinem Cloud-Secret-Manager verknüpft. Zwei unabhängige Kontrollen entscheiden, wer ein Geheimnis nutzen darf. Die Berechtigungen der Service-Zugangsdaten in Ihrem Secret-Manager bestimmen, welche Geheimnisse Unity Catalog importieren und lesen kann, und die Unity Catalog-Rechte bestimmen, welche Principals sie verwenden dürfen.

Jeder Key Vault verwendet sein eigenes Schema. UC-Privilegien entscheiden, wer die Geheimnisse nutzen darf.

Nachdem Sie ein Schema gesichert haben, verhalten sich externe Geheimnisse wie folgt:

  • Jeder Lesevorgang ruft den aktuellen Wert ab: Ein Wert, den du in deinem Secret-Manager rotierst, wird beim nächsten Lesevorgang wirksam, ohne Änderungen in Azure Databricks. Code, der bereits einen Wert enthält, behält ihn, bis er das Secret erneut liest. Abgerufene Werte können wie bei anderen Geheimnissen auf dem berechneten Algorithmus zwischengespeichert werden, der sie angefordert hat.
  • Verwalte Geheimnisse in deinem Secret-Manager: Erstellen, aktualisieren, erneuern und löschen Sie dort Geheimnisse. Sie sind im Unity Catalog nur lesegeschützt. Wenn Sie ein Geheimnis in Ihrem Secret-Manager dauerhaft löschen, entfernt Azure Databricks das Unity-Katalog-Geheimnis einschließlich seiner Berechtigungen und Tags.
  • Das Auflisten importiert neue Geheimnisse: Das Auflisten des Schemas startet einen asynchronen Import. Ein Geheimnis, das zu deinem Secret-Manager hinzugefügt oder daraus entfernt wurde, erscheint nach einer späteren Auflistung im Unity-Katalog, was bei großen Stores ein paar Minuten dauern kann. Sie können ein Geheimnis anhand des Namens lesen, bevor es in einer Liste erscheint.
  • Überwachungsprotokolle zeichnen beide Seiten auf: Unity Catalog-Überwachungsprotokolle zeichnen den Azure Databricks-Sicherheitsprinzipal auf, der ein Geheimnis gelesen hat. Cloudseitige Protokolle schreiben den Zugriff den Service-Anmeldeinformationen zu.

Anforderungen

  • Erfüllen Sie die Anforderungen für Unity-Kataloggeheimnisse.
  • Die Beta-Funktion „External Secrets“ muss für Ihren Workspace aktiviert sein. Siehe Manage Azure Databricks Previews.
  • Du brauchst eine Unity-Catalog-Service-Credential und eine Unity-Catalog-Verbindung, die sie zur Authentifizierung bei deinem Secret Manager verwendet. Siehe Service-Zugangsdaten erstellen und Verbindung herstellen.
  • Um das Schema zu sichern, brauchen Sie USE CATALOG im Katalog, Eigentum am Schema oder MANAGE daran und USE CONNECTION an der Verbindung. Das Schema darf keine von Azure Databricks verwalteten Geheimnisse enthalten, also löschen Sie diese, bevor Sie es sichern.

Externe Geheimnisse einrichten

Erstellen Sie eine Service-Credential

Die Verbindung authentifiziert sich mit einem Unity Catalog Service-Credential bei Ihrem Secret Manager.

  1. Erstellen Sie eine Service-Anmeldeinformation, die auf einer verwalteten Identität oder einem Dienstprinzipal basieren, wie in Service-Anmeldeinformationen erstellen beschrieben.
  2. Erteile der Identität die Erlaubnis, Geheimnisse im Key Vault aufzulisten und zu lesen. Zum Beispiel kann man die Rolle Key Vault Secrets User oder eine Zugriffsrichtlinie mit den Secret-Berechtigungen „Abrufen“ und „Auflisten“ zuweisen.

Verbindung erstellen

Erstellen Sie eine Unity-Katalog-Verbindung, die die Service-Zugangsdaten verwendet und auf Ihren Secret-Manager verweist. Sie brauchen CREATE CONNECTION im Metastore.

Katalog-Explorer

  1. Im Katalogexplorer klicken Sie auf das + Menü und wählen Sie Verbindung erstellen.
  2. Geben Sie einen Verbindungsnamen ein und wählen Sie den Azure Key Vault-Verbindungstyp.
  3. Wählen Sie die Service-Credential aus und legen Sie den Vault-Namen Ihres Key Vault fest.
  4. Klicke auf Erstellen.

Databricks-CLI

Um die Verbindung herzustellen, führen Sie Folgendes aus. Setzen Sie vault_name auf den Namen Ihres Key Vaults und credential auf den Namen der Dienstanmeldeinformationen:

databricks connections create --json '{
  "name": "my_key_vault_connection",
  "connection_type": "AZURE_KEY_VAULT",
  "options": {
    "vault_name": "my-vault",
    "credential": "my_key_vault_credential"
  }
}'

REST API

Um die Verbindung herzustellen, führen Sie Folgendes aus. Azure Databricks löst vault_name in https://<vault_name>.vault.azure.net auf:

curl -X POST \
  -H "Authorization: Bearer $DATABRICKS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "my_key_vault_connection",
    "connection_type": "AZURE_KEY_VAULT",
    "options": {
      "vault_name": "my-vault",
      "credential": "my_key_vault_credential"
    }
  }' \
  "$DATABRICKS_HOST/api/2.1/unity-catalog/connections"

Untermauern Sie ein Schema mit der Verbindung

  1. Wechseln Sie im Katalog-Explorer zum Schema.
  2. In den Details des Schemas finden Sie die Einstellung für den externen Geheimnismanager und klicken Sie auf Aktivieren. Enable bleibt deaktiviert, bis das Schema keine Geheimnisse mehr hat.
  3. Wählen Sie die von Ihnen erstellte Verbindung aus und bestätigen Sie dann.

Um das Schema auf eine andere Verbindung zu richten, klicke auf Bearbeiten. Um das Schema an den von Azure Databricks verwalteten Speicher zurückzugeben, bearbeite das Schema und deaktiviere externe Geheimnisse. Jede der beiden Änderungen entfernt die zuvor importierten Geheimnisse aus dem Schema, einschließlich ihrer Berechtigungen und Tags.

Überprüfen des Setups

Um zu bestätigen, dass Unity Catalog deine Secrets auflisten und lesen kann, führe Folgendes in einem Notizbuch durch:

# List the secrets in the schema. This also starts an import of new secrets.
dbutils.secrets.list(catalog="main", schema="orders_app")

# Read one secret by name
dbutils.secrets.get(catalog="main", schema="orders_app", key="example_secret")

Wenn die Liste leer ist, führen Sie dies nach einigen Minuten erneut aus. Wenn ein Lesevorgang fehlschlägt, siehe Fehlerbehebung.

Geheimnisnamen im Unity Catalog

Unity Catalog importiert ein externes Secret nur, wenn sein Name diesen Regeln entspricht:

  • Namen, die länger als 255 Zeichen sind, werden nicht importiert.
  • Bei Namen wird die Groß-/Kleinschreibung nicht berücksichtigt. Wenn sich zwei Geheimnisse nur in der Groß- und Kleinschreibung unterscheiden, behält Unity Catalog das zuerst importierte und ignoriert den Rest.
  • Aus . wird : und aus / wird |. Azure Databricks empfiehlt, diese Zeichen in externen Geheimnamen zu vermeiden.

Um ein Geheimnis zu lesen, bevor es in einer Liste erscheint, verwenden Sie seinen Namen mit diesen Substitutionen.

Troubleshooting

  • Ein Geheimnis wird aufgelistet, aber das Lesen schlägt fehl: Die Identität kann das Geheimnis auflisten, aber seinen Wert nicht lesen, oder das Geheimnis ist in Key Vault deaktiviert. Weisen Sie die Key Vault Secrets User-Rolle oder eine Zugriffsrichtlinie mit der Berechtigung „Abrufen“ zu, oder aktivieren Sie den geheimen Schlüssel erneut.
  • Ein geheimer Schlüssel ist verschwunden: Der Unity-Katalog zeigt keine soft-gelöschten Key Vault-Geheimnisse an. Stellen Sie das Secret im Key Vault wieder her.
  • Ein neues Geheimnis wird nicht angezeigt: Listen Sie das Schema auf, warten Sie ein paar Minuten und listen Sie es erneut auf. Überprüfe die Namensbeschränkungen und die Schema-Quote.
  • Einige Geheimnisse tauchen nie auf: Ein Schema enthält bis zu 1.000 Geheimnisse. Wenn dein Secret-Manager mehr Einträge hat, importiert Unity Catalog das älteste zuerst nach Erstellungsdatum und überspringt den Rest. Stelle nur die Secrets bereit, die du in jedem Schema brauchst. Siehe Geheimnisse danach gruppieren, wer sie benötigt.

Limitations

Zusätzlich zu den Einschränkungen, die für alle Unity-Catalog-Geheimnisse gelten, haben extern gesicherte Geheimnisse folgende Einschränkungen:

  • Cloud-übergreifender Zugriff wird nicht unterstützt: Sichern Sie Schemas mit dem Secret Manager, der nativ in der Cloud des Arbeitsbereichs verfügbar ist.
  • Lese-Latenz und Kosten: Jeder Read holt den Wert vom externen Secret-Manager, was die Latenz erhöht und Kosten für Cloud-Anbieter verursachen kann.
  • Keine Tag-Filterung: Azure Key Vault unterstützt das Filtern importierter Geheimnisse nach Tag nicht.

Note

Wenn sich der externe Secret-Manager, der hinter einem Schema steht, in einer anderen Region befindet als das Metastore oder der Arbeitsbereich, der darauf zugreift, werden Secret-Werte und ihre Metadaten regionsübergreifend übertragen. Azure Databricks garantiert keine Verarbeitung externer Geheimnisse innerhalb der Region.

Externe geheime Namen und Werte können persönliche Daten enthalten. Du bist dafür verantwortlich, persönliche Daten von ihnen fernzuhalten, es sei denn, dein Anwendungsfall erfordert es.

Weitere Ressourcen

Resource Description
Bewährte Methoden für Unity Catalog-Geheimnisse Organisieren Sie Geheimnisse nach Umgebung, Anwendung oder Team und lassen Sie Workloads Geheimnisse verwenden, ohne sie zu lesen.
Geheimnisse im Unity-Katalog Erstellen Sie Unity Catalog-Geheimnisse, vergeben Sie sie und lesen Sie sie.