Acceso a secretos desde la implementación en línea mediante la inserción de secretos (versión preliminar)

  • Artículo

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En este artículo, aprenderá a usar la inserción de secretos con un punto de conexión en línea y una implementación para acceder a secretos desde un almacén de secretos.

Aprenderá lo siguiente:

  • Configurar la identidad de usuario y sus permisos
  • Crear conexiones de área de trabajo o almacenes de claves para usarlos como almacenes de secretos
  • Crear el punto de conexión y la implementación mediante la característica de inserción de secretos

Importante

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas.

Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Requisitos previos

  • Para usar Azure Machine Learning, es preciso tener una suscripción a Azure. Si no tiene una suscripción de Azure, cree una cuenta gratuita antes de empezar. Pruebe hoy mismo la versión gratuita o de pago de Azure Machine Learning.

  • Instale y configure la extensión de la CLI de Azure Machine Learning (v2) o el SDK de Python de Azure Machine Learning (v2).

  • Un grupo de recursos de Azure, en el que usted (o la entidad de servicio que use) necesita tener acceso de User Access Administrator y Contributor. Tendrá un grupo de recursos de este tipo si configuró la extensión de Azure Machine Learning como se indicó anteriormente.

  • Un área de trabajo de Azure Machine Learning. Tendrá un área de trabajo si configuró la extensión de Azure Machine Learning como se indicó anteriormente.

  • Cualquier modelo de Machine Learning listo para la puntuación y la implementación.

Elección de un almacén de secretos

Puede elegir almacenar los secretos (como las claves de API) mediante:

  • Conexiones del área de trabajo en el área de trabajo: si usa este tipo de almacén de secretos, puede conceder más adelante permiso a la identidad del punto de conexión (en el momento de creación del punto de conexión) para leer los secretos de las conexiones del área de trabajo automáticamente, siempre que se cumplan ciertas condiciones. Para obtener más información, consulte la pestaña de identidad asignada por el sistema en la sección Creación de un punto de conexión.
  • Almacenes de claves que no están necesariamente en el área de trabajo: si usa este tipo de almacén de secretos, a la identidad del punto de conexión no se le concederá permiso para leer los secretos de los almacenes de claves automáticamente. Por lo tanto, si desea usar un servicio de almacén de claves administrado, como Microsoft Azure Key Vault como almacén de secretos, debe asignar un rol adecuado más adelante.

Uso de la conexión del área de trabajo como almacén de secretos

Puede crear conexiones de área de trabajo para usarlas en la implementación. Por ejemplo, puede crear una conexión con OpenAI Service de Microsoft Azure mediante Conexiones del área de trabajo: creación de la API REST.

Como alternativa, puede crear una conexión personalizada mediante Estudio de Azure Machine Learning (consulte Creación de una conexión personalizada para el flujo de avisos) o Inteligencia artificial de Azure Studio (consulte Creación de una conexión personalizada en Inteligencia artificial de Azure Studio).

  1. Creación de una conexión de 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. También puede crear una conexión personalizada:

    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. Compruebe que la identidad del usuario puede leer los secretos de la conexión del área de trabajo mediante Conexiones del área de trabajo: Enumeración de la API REST de secretos (versión preliminar).

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

Nota:

Los fragmentos de código anteriores usan un token en el encabezado Authorization al realizar llamadas a la API REST. Para obtener el token, ejecute az account get-access-token. Para obtener más información sobre cómo obtener un token, consulte Obtención de un token de acceso.

(Opcional) Uso de Azure Key Vault como almacén de secretos

Cree el almacén de claves y establezca un secreto que se usará en la implementación. Para más información sobre la creación del almacén de claves, consulte Establecimiento y recuperación de un secreto desde Azure Key Vault mediante la CLI de Azure. Además,

  1. Cree un almacén de claves de Azure Key Vault:

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

  2. Cree un secreto:

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

    Este comando devuelve la versión del secreto que crea. Puede comprobar la propiedad id de la respuesta para obtener la versión del secreto. La respuesta devuelta es similar a https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Compruebe que la identidad del usuario puede leer el secreto del almacén de claves:

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

Importante

Si usa el almacén de claves como almacén de secretos para la inserción de secretos, debe configurar el modelo de permisos del almacén de claves como control de acceso basado en roles (RBAC) de Azure. Para más información, consulte RBAC de Azure frente a la directiva de acceso para Key Vault.

Elección de la identidad de un usuario

Elija la identidad de usuario que usará para crear el punto de conexión en línea y la implementación en línea. Esta identidad de usuario puede ser una cuenta de usuario, una cuenta de entidad de servicio o una identidad administrada en Microsoft Entra ID. Para configurar la identidad del usuario, siga los pasos que se indican en Configuración de la autenticación para recursos y flujos de trabajo de Azure Machine Learning.

(Opcional) Asignación de un rol a la identidad del usuario

  • Si la identidad de usuario quiere que la identidad asignada por el sistema (SAI) del punto de conexión tenga permiso para leer automáticamente los secretos de las conexiones del área de trabajo, la identidad del usuario debe tener el rol Azure Machine Learning Workspace Connection Secrets Reader (o superior) en el ámbito del área de trabajo.

    • Un administrador que tenga el permiso Microsoft.Authorization/roleAssignments/write puede ejecutar un comando de la CLI para asignar el rol a la identidad de usuario:

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

    Nota:

    La identidad asignada por el sistema (SAI) del punto de conexión no obtendrá automáticamente permiso para leer secretos de los almacenes de claves. Por lo tanto, no es necesario asignar un rol a la identidad del usuario para Key Vault.

  • Si quiere usar una identidad asignada por el usuario (UAI) para el punto de conexión, no es necesario asignar el rol a la identidad de usuario. En su lugar, si piensa usar la característica de inserción de secretos, debe asignar el rol a la UAI del punto de conexión manualmente.

    • Un administrador que tenga el permiso Microsoft.Authorization/roleAssignments/write puede ejecutar los siguientes comandos para asignar el rol a la identidad del punto de conexión:

      Para las conexiones del área de trabajo:

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

      Para los almacenes de claves:

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

  • Compruebe que una identidad (ya sea una identidad de usuario o una identidad de punto de conexión) tenga asignado el rol; para ello, vaya al recurso en Azure Portal. Por ejemplo, en el área de trabajo de Azure Machine Learning o Key Vault:

    1. Seleccione la pestaña Control de acceso (IAM).
    2. Seleccione el botón Comprobar acceso y busque la identidad.
    3. Compruebe que aparece el rol correcto en la pestaña Asignaciones de roles actuales.

Creación de un punto de conexión

Si usa una identidad asignada por el sistema (SAI) como identidad del punto de conexión, especifique si desea aplicar el acceso a los almacenes de secretos predeterminados (es decir, las conexiones del área de trabajo en el área de trabajo) a la identidad del punto de conexión.

  1. Cree un archivo 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. Cree el punto de conexión mediante el archivo endpoint.yaml:

    az ml online-endpoint create -f endpoint.yaml

Si no especifica la propiedad identity en la definición del punto de conexión, el punto de conexión usará una SAI de forma predeterminada.

Si se cumplen las condiciones siguientes, a la identidad del punto de conexión se le concederá automáticamente el rol Azure Machine Learning Workspace Connection Secrets Reader (o superior) en el ámbito del área de trabajo:

  • La identidad de usuario que crea el punto de conexión tiene el permiso para leer secretos desde las conexiones del área de trabajo (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • El punto de conexión usa una SAI.
  • El punto de conexión se define con una marca para aplicar el acceso a almacenes secretos predeterminados (conexiones de área de trabajo en el área de trabajo actual) al crear el punto de conexión.

A la identidad del punto de conexión no se le concederá automáticamente un rol para leer secretos de Key Vault. Si quiere usar Key Vault como almacén de secretos, debe asignar manualmente un rol adecuado, como Key Vault Secrets User, a la identidad del punto de conexión en el ámbito de Key Vault. Para más información sobre los roles, consulte Roles integrados de Azure para operaciones del plano de datos de Key Vault.

de una implementación

  1. Cree un script de puntuación o Dockerfile y los scripts relacionados para que la implementación pueda consumir los secretos a través de variables de entorno.

    • No es necesario llamar a las API de recuperación de secretos para las conexiones del área de trabajo o los almacenes de claves. Las variables de entorno se rellenan con los secretos cuando se inicia el contenedor de usuarios en la implementación.

    • El valor que se inserta en una variable de entorno puede ser uno de los tres tipos:

      • Respuesta completa de la API de enumeración de secretos (versión preliminar). Deberá comprender la estructura de respuesta de la API, analizarla y usarla en el contenedor de usuarios.
      • Secreto individual o metadatos de la conexión del área de trabajo. Puede usarlo sin comprender la estructura de respuesta de la API de conexión del área de trabajo.
      • Versión de secreto individual de Key Vault. Puede usarlo sin comprender la estructura de respuesta de la API de Key Vault.

  2. Inicie la creación de la implementación mediante el script de puntuación (si usa un modelo personalizado) o un Dockerfile (si adopta el enfoque BYOC para la implementación). Especifique las variables de entorno que el usuario espera dentro del contenedor de usuarios.

    Si los valores asignados a las variables de entorno siguen determinados patrones, la identidad del punto de conexión se usará para realizar la recuperación e inserción de secretos.

    Patrón Comportamiento
    ${{azureml://connections/<connection_name>}} La respuesta completa de la API de enumeración de secretos (versión preliminar) se inserta en la variable de entorno.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} El valor de la credencial se inserta en la variable de entorno.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} El valor de los metadatos se inserta en la variable de entorno.
    ${{azureml://connections/<connection_name>/target}} El valor del destino (si procede) se inserta en la variable de entorno.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} El valor de la versión del secreto se inserta en la variable de entorno.

    Por ejemplo:

    1. Creación de 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. Creación de la implementación:

      az ml online-deployment create -f deployment.yaml

Si la marca enforce_access_to_default_secret_stores se estableció para el punto de conexión, el permiso de la identidad del usuario para leer secretos de las conexiones del área de trabajo se comprobará tanto en el momento de creación del punto de conexión como de la creación de la implementación. Si la identidad del usuario no tiene el permiso, se producirá un error en la creación.

En el momento de la creación de la implementación, si alguna variable de entorno se asigna a un valor que sigue los patrones de la tabla anterior, la recuperación y la inserción de secretos se realizarán con la identidad del punto de conexión (ya sea una SAI o una UAI). Si la identidad del punto de conexión no tiene permiso para leer secretos de almacenes secretos designados (conexiones del área de trabajo o almacenes de claves), se producirá un error en la creación de la implementación. Además, si la referencia secreta especificada no existe en los almacenes de secretos, se producirá un error en la creación de la implementación.

Para más información sobre los errores que pueden producirse durante la implementación de puntos de conexión en línea de Azure Machine Learning, consulte Errores de inserción de secretos.

Consumo de los secretos

Puede consumir los secretos recuperándolos de las variables de entorno dentro del contenedor de usuarios que se ejecuta en las implementaciones.

Contenido relacionado