Zugreifen auf Geheimnisse aus der Onlinebereitstellung mithilfe von Geheimniseinschleusung (Vorschau)

  • Artikel

GILT FÜR:Azure CLI ML-Erweiterung v2 (aktuell)Python SDK azure-ai-ml v2 (aktuell)

In diesem Artikel erfahren Sie, wie Sie die Geheimniseinschleusung mit Onlineendpunkt und Bereitstellung verwenden, um auf Geheimnisse in einem Geheimnisspeicher zuzugreifen.

Sie lernen Folgendes:

  • Einrichten Ihrer Benutzeridentität und der zugehörigen Berechtigungen
  • Erstellen von Arbeitsbereichsverbindungen oder Schlüsseltresoren, die als Geheimnisspeicher verwendet werden sollen
  • Erstellen des Endpunkts und der Bereitstellung mithilfe des Features für Geheimniseinschleusung

Wichtig

Dieses Feature ist zurzeit als öffentliche Preview verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und ist nicht für Produktionsworkloads vorgesehen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar.

Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Voraussetzungen

  • Für die Verwendung von Azure Machine Learning ist ein Azure-Abonnement erforderlich. Wenn Sie nicht über ein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen. Probieren Sie noch heute die kostenlose oder kostenpflichtige Version von Azure Machine Learning aus.

  • Installieren und konfigurieren Sie die Azure Machine Learning-CLI-Erweiterung (v2) oder das Azure Machine Learning Python SDK (v2).

  • Eine Azure-Ressourcengruppe, auf die Sie (oder der von Ihnen verwendete Dienstprinzipal) Zugriff haben müssen User Access Administrator und Contributor. Sie verfügen über eine solche Ressourcengruppe, wenn Sie die Azure Machine Learning-Erweiterung wie bereits erwähnt konfiguriert haben.

  • Ein Azure Machine Learning-Arbeitsbereich. Sie verfügen über einen Arbeitsbereich, wenn Sie die Azure Machine Learning-Erweiterung wie bereits erwähnt konfiguriert haben.

  • Ein trainiertes, für die Bewertung und Bereitstellung bereites Machine Learning-Modell.

Auswählen eines Geheimnisspeichers

Sie können Ihre geheimen Schlüssel (z. B. API-Schlüssel) über eine der folgenden Optionen speichern:

  • Arbeitsbereichsverbindungen unter dem Arbeitsbereich: Wenn Sie diese Art von Geheimnisspeicher verwenden, können Sie der Endpunktidentität später (zum Zeitpunkt der Endpunkterstellung) die Berechtigung erteilen, Geheimnisse automatisch von Arbeitsbereichsverbindungen zu lesen, sofern bestimmte Bedingungen erfüllt sind. Weitere Informationen finden Sie auf der Registerkarte „Systemseitig zugewiesene Identität“ im Abschnitt Erstellen eines Endpunkts.
  • Schlüsseltresore, die nicht unbedingt unter dem Arbeitsbereich liegen: Wenn Sie diese Art von Geheimnisspeicher verwenden, erhält die Endpunktidentität nicht die Berechtigung, geheime Schlüssel automatisch aus den Schlüsseltresoren zu lesen. Wenn Sie daher einen verwalteten Schlüsseltresordienst wie Microsoft Azure Key Vault als Geheimnisspeicher verwenden möchten, müssen Sie später eine entsprechende Rolle zuweisen.

Verwenden einer Arbeitsbereichsverbindung als Geheimnisspeicher

Sie können Arbeitsbereichsverbindungen für die Verwendung in Ihrer Bereitstellung erstellen. Beispielsweise können Sie eine Verbindung mit Microsoft Azure OpenAI Service erstellen, indem Sie Arbeitsbereichsverbindungen – REST-API erstellen verwenden.

Alternativ können Sie eine benutzerdefinierte Verbindung mithilfe von Azure Machine Learning Studio (siehe Erstellen einer benutzerdefinierten Verbindung für den Prompt Flow) oder Azure AI Studio (siehe Erstellen einer benutzerdefinierten Verbindung in AI Studio) erstellen.

  1. Erstellen einer Azure OpenAI-Verbindung:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "ApiKey",
        "category": "AzureOpenAI",
        "credentials": {
            "key": "<key>",
            "endpoint": "https://<name>.openai.azure.com/",
        },
        "expiryTime": null,
        "target": "https://<name>.openai.azure.com/",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "ApiType": "Azure"
        }
    }
}

  2. Alternativ können Sie eine benutzerdefinierte Verbindung erstellen:

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}?api-version=2023-08-01-preview
Authorization: Bearer {{token}}
Content-Type: application/json

{
    "properties": {
        "authType": "CustomKeys",
        "category": "CustomKeys",
        "credentials": {
            "keys": {
                "OPENAI_API_KEY": "<key>",
                "SPEECH_API_KEY": "<key>"
            }
        },
        "expiryTime": null,
        "target": "_",
        "isSharedToAll": false,
        "sharedUserList": [],
        "metadata": {
            "OPENAI_API_BASE": "<oai endpoint>",
            "OPENAI_API_VERSION": "<oai version>",
            "OPENAI_API_TYPE": "azure",
            "SPEECH_REGION": "eastus",
        }
    }
}

  3. Stellen Sie sicher, dass die Benutzeridentität die Geheimnisse von der Arbeitsbereichsverbindung lesen kann, indem Sie Arbeitsbereichsverbindungen – REST-API zum Auflisten von Geheimnissen (Vorschau) verwenden.

    POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.MachineLearningServices/workspaces/{{workspaceName}}/connections/{{connectionName}}/listsecrets?api-version=2023-08-01-preview
Authorization: Bearer {{token}}

Hinweis

Die vorherigen Codeschnipsel verwenden beim Ausführen von REST-API-Aufrufen ein Token im Authorization-Header. Sie können das Token abrufen, indem Sie az account get-access-token ausführen. Weitere Informationen zum Abrufen eines Tokens finden Sie unter Abrufen eines Zugriffstokens.

(Optional:) Verwenden von Azure Key Vault als Geheimnisspeicher

Erstellen Sie den Schlüsseltresor, und legen Sie ein Geheimnis fest, das in Ihrer Bereitstellung verwendet werden soll. Weitere Informationen zum Erstellen des Schlüsseltresors finden Sie unter Festlegen eines Geheimnisses und Abrufen des Geheimnisses aus Azure Key Vault mithilfe der Azure CLI. Außerdem gilt:

  1. Erstellen einer Azure Key Vault-Instanz:

    az keyvault create --name mykeyvault --resource-group myrg --location eastus

  2. Erstellen eines Geheimnisses:

    az keyvault secret set --vault-name mykeyvault --name secret1 --value <value>

    Dieser Befehl gibt die erstellte Geheimnisversion zurück. Sie können die id-Eigenschaft der Antwort überprüfen, um die Geheimnisversion abzurufen. Die zurückgegebene Antwort sieht wie folgt aus: https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Überprüfen, ob die Benutzeridentität das Geheimnis aus dem Schlüsseltresor lesen kann:

    az keyvault secret show --vault-name mykeyvault --name secret1 --version <secret_version>

Wichtig

Wenn Sie den Schlüsseltresor als Geheimnisspeicher für die Geheimniseinschleusung verwenden, müssen Sie das Berechtigungsmodell des Schlüsseltresors als Azure RBAC (Role-Based Access Control, rollenbasierte Zugriffssteuerung) konfigurieren. Weitere Informationen finden Sie unter Azure RBAC im Vergleich mit Zugriffsrichtlinien für Key Vault.

Auswählen einer Benutzeridentität

Wählen Sie die Benutzeridentität aus, die Sie zum Erstellen des Onlineendpunkts und der Onlinebereitstellung verwenden möchten. Diese Benutzeridentität kann ein Benutzerkonto, ein Dienstprinzipalkonto oder eine verwaltete Identität in Microsoft Entra ID sein. Führen Sie zum Einrichten der Benutzeridentität die Schritte unter Einrichten von Authentifizierung für Azure Machine Learning-Ressourcen und -Workflows aus.

(Optional:) Zuweisen einer Rolle zur Benutzeridentität

  • Wenn Ihre Benutzeridentität der systemseitig zugewiesene Identität (System-Assigned Identity, SAI) des Endpunkts automatisch die Berechtigung zum Lesen von Geheimnissen von Arbeitsbereichsverbindungen erteilen soll, muss die Benutzeridentität die Rolle Azure Machine Learning Workspace Connection Secrets Reader (oder höher) im Bereich des Arbeitsbereichs haben.

    • Administrator*innen, die über die Berechtigung Microsoft.Authorization/roleAssignments/write verfügen, können einen CLI-Befehl ausführen, um der Benutzeridentität die Rolle zuzuweisen:

      az role assignment create --assignee <UserIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

    Hinweis

    Die systemseitig zugewiesene Identität (System-Assigned Identity, SAI) des Endpunkts erhält nicht automatisch die Berechtigung zum Lesen von Geheimnissen aus Schlüsseltresoren. Daher muss der Benutzeridentität keine Rolle für den Schlüsseltresor zugewiesen werden.

  • Wenn Sie eine benutzerseitig zugewiesene Identität (User-Assigned Identity, UAI) für den Endpunkt verwenden möchten, müssen Sie die Rolle nicht Ihrer Benutzeridentität zuweisen. Wenn Sie das Feature für die Geheimniseinschleusung verwenden möchten, müssen Sie stattdessen der UAI des Endpunkts die Rolle manuell zuweisen.

    • Administrator*innen, die über die Berechtigung Microsoft.Authorization/roleAssignments/write verfügen, können die folgenden Befehle ausführen, um der Endpunktidentität die Rolle zuzuweisen:

      Für Arbeitsbereichsverbindungen:

      az role assignment create --assignee <EndpointIdentityID> --role "Azure Machine Learning Workspace Connection Secrets Reader" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.MachineLearningServices/workspaces/<workspaceName>

      Für Schlüsseltresore:

      az role assignment create --assignee <EndpointIdentityID> --role "Key Vault Secrets User" --scope /subscriptions/<subscriptionId>/resourcegroups/<resourceGroupName>/providers/Microsoft.KeyVault/vaults/<vaultName>

  • Stellen Sie sicher, dass einer Identität (einer Benutzeridentität oder einer Endpunktidentität) die Rolle zugewiesen ist, indem Sie im Azure-Portal zu der Ressource wechseln. Gehen Sie beispielsweise im Azure Machine Learning-Arbeitsbereich oder im Schlüsseltresor folgendermaßen vor:

    1. Wählen Sie die Registerkarte Zugriffssteuerung (IAM) aus.
    2. Wählen Sie die Schaltfläche Zugriff überprüfen aus, und suchen Sie nach der Identität.
    3. Vergewissern Sie sich, dass die richtige Rolle unter der Registerkarte Aktuelle Rollenzuweisungen angezeigt wird.

Erstellen eines Endpunkts

Wenn Sie eine systemseitig zugewiesene Identität (System-Assigned Identity, SAI) als Endpunktidentität verwenden, geben Sie an, ob Sie den Zugriff auf standardmäßige Geheimnisspeicher (Arbeitsbereichsverbindungen unter dem Arbeitsbereich) mit der Endpunktidentität erzwingen möchten.

  1. Erstellen Sie eine Datei vom Typ endpoint.yaml:

    $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key
properties:
    enforce_access_to_default_secret_stores: enabled  # default: disabled

  2. Erstellen des Endpunkts mithilfe der Datei endpoint.yaml:

    az ml online-endpoint create -f endpoint.yaml

Wenn Sie die identity-Eigenschaft nicht in der Endpunktdefinition angeben, verwendet der Endpunkt standardmäßig eine SAI.

Wenn die folgenden Bedingungen erfüllt sind, erhält die Endpunktidentität automatisch die Rolle Azure Machine Learning Workspace Connection Secrets Reader (oder höher) im Bereich des Arbeitsbereichs:

  • Die Benutzeridentität, die den Endpunkt erstellt, verfügt über die Berechtigung zum Lesen von Geheimnissen von Arbeitsbereichsverbindungen (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Der Endpunkt verwendet eine SAI.
  • Der Endpunkt wird mit einer Kennzeichnung definiert, um beim Erstellen des Endpunkts Zugriff auf Standardschlüsselspeicher (Arbeitsbereichsverbindungen unter dem aktuellen Arbeitsbereich) zu erzwingen.

Der Endpunktidentität wird nicht automatisch eine Rolle zum Lesen von Geheimnissen aus dem Schlüsseltresor gewährt. Wenn Sie den Schlüsseltresor als Geheimnisspeicher verwenden möchten, müssen Sie der Endpunktidentität manuell eine geeignete Rolle wie Key Vault Secrets User im Bereich des Schlüsseltresors zuweisen. Weitere Informationen finden Sie unter In Azure integrierte Rollen für Key Vault-Vorgänge auf Datenebene.

Erstellen einer Bereitstellung

  1. Erstellen Sie ein Bewertungsskript oder ein Dockerfile und die zugehörigen Skripts, sodass die Bereitstellung die Geheimnisse über Umgebungsvariablen nutzen kann.

    • Es ist nicht erforderlich, die Geheimnisabruf-APIs für die Arbeitsbereichsverbindungen oder Schlüsseltresore aufzurufen. Die Umgebungsvariablen werden mit den Geheimnissen aufgefüllt, wenn der Benutzercontainer in der Bereitstellung initiiert wird.

    • Der Wert, der in eine Umgebungsvariable eingefügt wird, kann einer dieser drei Typen sein:

      • Die gesamte Antwort der API zum Auflisten von Geheimnissen (Vorschau). Sie müssen die Struktur der API-Antwort verstehen, analysieren und in Ihrem Benutzercontainer verwenden.
      • Ein einzelnes Geheimnis oder Metadaten von der Arbeitsbereichsverbindung. Sie können dies verwenden, ohne die Antwortstruktur der Arbeitsbereichsverbindungs-API zu verstehen.
      • Eine einzelne Geheimnisversion aus dem Schlüsseltresor. Sie können diese verwenden, ohne die Antwortstruktur der Key Vault-API zu verstehen.

  2. Initiieren Sie die Erstellung der Bereitstellung über das Bewertungsskript (wenn Sie ein benutzerdefiniertes Modell verwenden) oder ein Dockerfile (wenn Sie den BYOC-Ansatz für die Bereitstellung verwenden). Geben Sie erwarteten Umgebungsvariablen im Benutzercontainer an.

    Wenn die Werte, die den Umgebungsvariablen zugeordnet sind, bestimmten Mustern entsprechen, wird die Endpunktidentität für den Abruf und die Einschleusung von Geheimnissen verwendet.

    Muster Verhalten
    ${{azureml://connections/<connection_name>}} Die gesamte Antwort der API zum Auflisten von Geheimnissen (Vorschau) wird in die Umgebungsvariable eingefügt.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} Der Wert der Anmeldeinformationen wird in die Umgebungsvariable eingefügt.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} Der Wert der Metadaten wird in die Umgebungsvariable eingefügt.
    ${{azureml://connections/<connection_name>/target}} Der Wert des Ziel (sofern zutreffend) wird in die Umgebungsvariable eingefügt.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} Der Wert der Geheimnisversion wird in die Umgebungsvariable eingefügt.

    Beispiel:

    1. Erstellen Sie deployment.yaml:

      $schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
#…
environment_variables:
    AOAI_CONNECTION: ${{azureml://connections/aoai_connection}}
    LANGCHAIN_CONNECTION: ${{azureml://connections/multi_connection_langchain}}

    OPENAI_KEY: ${{azureml://connections/multi_connection_langchain/credentials/OPENAI_API_KEY}}
    OPENAI_VERSION: ${{azureml://connections/multi_connection_langchain/metadata/OPENAI_API_VERSION}}

    USER_SECRET_KV1_KEY: ${{keyvault:https://mykeyvault.vault.azure.net/secrets/secret1/secretversion1}}

    2. Erstellen Sie die Bereitstellung:

      az ml online-deployment create -f deployment.yaml

Wenn das Flag enforce_access_to_default_secret_stores für den Endpunkt festgelegt wurde, wird die Berechtigung der Benutzeridentität zum Lesen von Geheimnissen von Arbeitsbereichsverbindungen sowohl beim Erstellen des Endpunkts als auch beim Erstellen der Bereitstellung überprüft. Wenn die Benutzeridentität nicht über die Berechtigung verfügt, tritt bei der Erstellung ein Fehler auf.

Wenn bei der Erstellung der Bereitstellung eine Umgebungsvariable einem Wert zugeordnet ist, der den Mustern in der vorstehenden Tabelle entspricht, werden die Abrufe und Einschleusungen von Geheimnissen mit der Endpunktidentität (SAI oder UAI) durchgeführt. Wenn die Endpunktidentität nicht über die Berechtigung zum Lesen von Geheimnissen aus festgelegten Geheimnisspeichern verfügt (Arbeitsbereichsverbindungen oder Schlüsseltresore), tritt bei der Erstellung der Bereitstellung ein Fehler auf. Wenn der angegebene Geheimnisverweis im Geheimnisspeicher nicht vorhanden ist, tritt bei der Erstellung der Bereitstellung ein Fehler auf.

Weitere Informationen zu Fehlern, die bei der Bereitstellung von Azure Machine Learning-Onlineendpunkten auftreten können, finden Sie unter Fehler bei der Geheimniseinschleusung.

Nutzen der Geheimnisse

Sie können die Geheimnisse nutzen, indem Sie sie aus den Umgebungsvariablen in dem Benutzercontainer abrufen, der in Ihren Bereitstellungen ausgeführt wird.

Zugehöriger Inhalt