Partager via

Accéder aux secrets à partir d’un déploiement en ligne à l’aide de l’injection de secrets (préversion)

  • Article

S’APPLIQUE À :Extension Azure CLI v2 (actuelle)Kit de développement logiciel (SDK) Python azure-ai-ml v2 (version actuelle)

Dans cet article, vous allez apprendre à utiliser l’injection de secrets avec un point de terminaison et un déploiement en ligne pour accéder aux secrets à partir d’un magasin des secrets.

Vous allez apprendre à :

  • Configurer votre identité utilisateur et les autorisations correspondantes
  • Créer des connexions d’espace de travail et/ou des coffres de clés à utiliser comme magasins des secrets
  • Créer le point de terminaison et le déploiement à l’aide de la fonctionnalité d’injection de secrets

Important

Cette fonctionnalité est actuellement disponible en préversion publique. Cette préversion est fournie sans contrat de niveau de service et n’est pas recommandée pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’Utilisation Supplémentaires relatives aux Évaluations Microsoft Azure.

Prérequis

  • Pour utiliser Azure Machine Learning, vous devez disposer d’un abonnement Azure. Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer. Essayez la version gratuite ou payante d’Azure Machine Learning dès aujourd’hui.

  • Installez et configurez l’extension Azure Machine Learning CLI (v2) ou le Kit de développement logiciel (SDK) Python Azure Machine Learning (v2).

  • Un groupe de ressources Azure dans lequel vous (ou le principal de service que vous utilisez) devez disposer d’un accès User Access Administrator et Contributor. Vous disposez déjà d’un groupe de ressources si vous avez configuré votre extension Azure Machine Learning comme indiqué précédemment.

  • Un espace de travail Azure Machine Learning. Vous disposez déjà d’un espace de travail si vous avez configuré votre extension Azure Machine Learning comme indiqué précédemment.

  • Un modèle Machine Learning entraîné prêt pour le scoring et le déploiement.

Choisir un magasin des secrets

Vous pouvez choisir de stocker vos secrets (tels que les clés API) à l’aide de l’un des deux éléments suivants :

  • Des connexions d’espace de travail sous l’espace de travail : si vous utilisez ce type de magasin des secrets, vous pouvez accorder ultérieurement à l’identité de point de terminaison (au moment de la création du point de terminaison) l’autorisation de lire automatiquement les secrets des connexions d’espace de travail, sous réserve du respect de certaines conditions. Pour plus d’informations, consultez l’onglet Identité affectée par le système dans la section Créer un point de terminaison.
  • Des coffres de clés qui ne sont pas nécessairement sous l’espace de travail : si vous utilisez ce type de magasin des secrets, l’identité de point de terminaison n’est pas autorisée à lire automatiquement les secrets à partir des coffres de clés. Par conséquent, si vous souhaitez utiliser un service de coffre de clés managé tel que Microsoft Azure Key Vault comme magasin des secrets, vous devez attribuer un rôle approprié ultérieurement.

Utiliser une connexion d’espace de travail comme magasin des secrets

Vous pouvez créer des connexions d’espace de travail à utiliser dans votre déploiement. Par exemple, vous pouvez créer une connexion à Microsoft Azure OpenAI Service à l’aide de l’API REST Connexions d’espace de travail – Create.

Vous pouvez également créer une connexion personnalisée à l’aide d’Azure Machine Learning Studio (consultez la section Comment créer une connexion personnalisée pour un flux d’invite) ou d’Azure AI Foundry (consultez la section Comment créer une connexion personnalisée dans le portail Azure AI Foundry).

  1. Créez une connexion Azure OpenAI :

    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. Vous pouvez également créer une connexion personnalisée :

    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. Vérifiez que l’identité utilisateur peut lire les secrets de la connexion d’espace de travail à l’aide de l’API REST Connexions d’espace de travail – List Secrets (préversion).

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

Remarque

Les extraits de code précédents utilisent un jeton dans l’en-tête Authorization lors de l’exécution d’appels d’API REST. Vous pouvez obtenir le jeton en exécutant az account get-access-token. Pour plus d’informations sur l’obtention d’un jeton, consultez la section Obtenir un jeton d’accès.

(Facultatif) Utiliser Azure Key Vault comme magasin des secrets

Créez le coffre de clés et définissez un secret à utiliser dans votre déploiement. Pour plus d’informations sur la création du coffre de clés, consultez l’article Définir et récupérer un secret depuis Azure Key Vault à l’aide d’Azure CLI. De plus :

  1. Créez un coffre de clés Azure :

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

  2. Créez un secret :

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

    Cette commande retourne la version du secret qu’elle crée. Vous pouvez consulter la propriété id de la réponse pour obtenir la version du secret. La réponse renvoyée se présente comme suit : https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Vérifiez que l’identité utilisateur peut lire le secret à partir du coffre de clés :

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

Important

Si vous utilisez le coffre de clés comme magasin des secrets pour l’injection de secrets, vous devez configurer le modèle d’autorisation du coffre de clés en tant que contrôle d’accès en fonction du rôle (RBAC) Azure. Pour plus d’informations, consultez l’article Azure RBAC contre stratégie d’accès pour Key Vault.

Choisir une identité utilisateur

Choisissez l’identité utilisateur que vous allez utiliser pour créer le point de terminaison et le déploiement en ligne. Il peut s’agir d’un compte d’utilisateur, d’un compte de principal de service ou d’une identité managée dans Microsoft Entra ID. Pour configurer l’identité utilisateur, suivez la procédure décrite dans l’article Configurer l’authentification pour des ressources et workflows Azure Machine Learning.

(Facultatif) Attribuer un rôle à l’identité utilisateur

  • Si votre identité utilisateur souhaite que l’identité affectée par le système (SAI) du point de terminaison soit automatiquement autorisée à lire les secrets à partir des connexions d’espace de travail, l’identité utilisateur doit avoir le rôle Azure Machine Learning Workspace Connection Secrets Reader (ou supérieur) dans l’étendue de l’espace de travail.

    • Un administrateur disposant de l’autorisation Microsoft.Authorization/roleAssignments/write peut exécuter une commande CLI pour attribuer le rôle à l’identité utilisateur :

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

    Remarque

    L’identité affectée par le système (SAI) du point de terminaison n’est pas automatiquement autorisée à lire les secrets à partir de coffres de clés. Par conséquent, l’identité utilisateur n’a pas besoin d’être attribuée à un rôle pour le coffre de clés.

  • Si vous souhaitez utiliser une identité affectée par l’utilisateur (UAI) pour le point de terminaison, vous n’avez pas besoin d’attribuer le rôle à votre identité utilisateur. En lieu et place, si vous envisagez d’utiliser la fonctionnalité d’injection de secrets, vous devez attribuer le rôle manuellement à l’identité UAI du point de terminaison.

    • Un administrateur disposant de l’autorisation Microsoft.Authorization/roleAssignments/write peut exécuter les commandes suivantes pour attribuer le rôle à l’identité utilisateur :

      Pour les connexions d’espace de travail :

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

      Pour les coffres de clés :

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

  • Vérifiez qu’une identité (une identité utilisateur ou une identité de point de terminaison) a le rôle attribué en accédant à la ressource dans le portail Azure. Par exemple, dans l’espace de travail Azure Machine Learning ou dans Key Vault :

    1. Sélectionnez l’onglet Contrôle d’accès (IAM).
    2. Sélectionnez le bouton Vérifier l’accès et recherchez l’identité.
    3. Vérifiez que le rôle approprié s’affiche dans l’onglet Attributions de rôles actuelles.

Créer un point de terminaison

Si vous utilisez une identité affectée par le système (SAI) comme identité de point de terminaison, indiquez si vous souhaitez appliquer l’accès aux magasins des secrets par défaut (à savoir, les connexions d’espace de travail sous l’espace de travail) à l’identité de point de terminaison.

  1. Créez un fichier 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. Créez le point de terminaison à l’aide du fichier endpoint.yaml :

    az ml online-endpoint create -f endpoint.yaml

Si vous ne spécifiez pas la propriété identity dans la définition de point de terminaison, le point de terminaison utilise par défaut une identité SAI.

Si les conditions suivantes sont remplies, l’identité de point de terminaison reçoit automatiquement le rôle Azure Machine Learning Workspace Connection Secrets Reader (ou supérieur) dans l’étendue de l’espace de travail :

  • L’identité utilisateur qui crée le point de terminaison a la même autorisation de lire les secrets à partir des connexions d’espace de travail (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • Le point de terminaison utilise une identité SAI.
  • Le point de terminaison est défini avec un indicateur forçant l’accès aux magasins de secrets par défaut (connexions d’espace de travail sous l’espace de travail actuel) lors de la création du point de terminaison.

L’identité du point de terminaison n’est pas automatiquement attribuée à un rôle pour lire les secrets à partir du coffre de clés. Si vous souhaitez utiliser le coffre de clés comme magasin des secrets, vous devez attribuer manuellement un rôle approprié tel que Key Vault Secrets User à l’identité de point de terminaison dans l’étendue du coffre de clés. Pour plus d’informations sur les rôles, consultez la section Rôles intégrés Azure pour les opérations de plan de données Key Vault.

Créer un déploiement

  1. Créez un script de scoring ou un Dockerfile et les scripts associés afin que le déploiement puisse consommer les secrets via des variables d’environnement.

    • Il n’est pas nécessaire d’appeler les API de récupération de secrets pour les connexions d’espace de travail ou les coffres de clés. Les variables d’environnement sont remplies avec les secrets au lancement du conteneur utilisateur du déploiement.

    • La valeur qui est injectée dans une variable d’environnement peut être l’un des trois types suivants :

      • La réponse complète de l’API List Secrets (préversion). Vous devez comprendre la structure de la réponse de l’API, l’analyser et l’utiliser dans votre conteneur utilisateur.
      • Un secret individuel ou des métadonnées de la connexion d’espace de travail. Vous pouvez l’utiliser sans comprendre la structure de la réponse de l’API de connexion d’espace de travail.
      • La version du secret individuel du coffre de clés. Vous pouvez l’utiliser sans comprendre la structure de la réponse de l’API de coffre de clés.

  2. Lancez la création du déploiement à l’aide du script de scoring (si vous utilisez un modèle personnalisé) ou d’un Dockerfile (si vous utilisez l’approche BYOC pour le déploiement). Spécifiez les variables d’environnement attendues par l’utilisateur dans le conteneur utilisateur.

    Si les valeurs mappées aux variables d’environnement suivent certains modèles, l’identité de point de terminaison est utilisée pour effectuer la récupération et l’injection de secrets.

    Modèle Comportement
    ${{azureml://connections/<connection_name>}} La réponse complète de l’API List Secrets (préversion) est injectée dans la variable d’environnement.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} La valeur des informations d’identification est injectée dans la variable d’environnement.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} La valeur des métadonnées est injectée dans la variable d’environnement.
    ${{azureml://connections/<connection_name>/target}} La valeur de la cible (le cas échéant) est injectée dans la variable d’environnement.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} La valeur de la version du secret est injectée dans la variable d’environnement.

    Par exemple :

    1. Créez 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. Créez le déploiement :

      az ml online-deployment create -f deployment.yaml

Si l’indicateur enforce_access_to_default_secret_stores est défini pour le point de terminaison, l’autorisation de l’identité utilisateur de lire les secrets à partir des connexions d’espace de travail est vérifiée lors de la création du point de terminaison et lors de la création du déploiement. La création échoue si l’identité utilisateur ne dispose pas de cette autorisation.

Au moment de la création du déploiement, si une variable d’environnement est mappée à une valeur qui suit les modèles indiqués dans le tableau précédent, la récupération et l’injection de secrets sont effectuées avec l’identité de point de terminaison (une identité SAI ou UAI). Si l’identité de point de terminaison ne dispose pas de l’autorisation de lire les secrets à partir des magasins des secrets désignés (connexions d’espace de travail ou coffres de clés), la création du déploiement échoue. En outre, si la référence de secret spécifiée n’existe pas dans les magasins des secrets, la création du déploiement échoue.

Pour plus d’informations sur les erreurs qui peuvent se produire pendant le déploiement de points de terminaison en ligne Azure Machine Learning, consultez la section Erreurs d’injection de secrets.

Consommer les secrets

Vous pouvez consommer les secrets en les récupérant à partir des variables d’environnement au sein du conteneur utilisateur s’exécutant dans vos déploiements.

Contenu connexe