Share via

Acessar segredos da implantação online usando injeção secreta (versão prévia)

  • Artigo

APLICA-SE A:Extensão de ML da CLI do Azure v2 (atual)SDK do Python azure-ai-ml v2 (atual)

Neste artigo, você aprenderá a usar a injeção de segredo com um ponto de extremidade online e implantação para acessar segredos de um repositório de segredos.

Você aprenderá a:

  • Configurar sua identidade de usuário e suas permissões
  • Criar conexões de workspace e/ou cofres de chaves para usar como repositórios de segredos
  • Criar o ponto de extremidade e a implantação usando o recurso de injeção de segredo

Importante

Esse recurso está atualmente em visualização pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos.

Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Pré-requisitos

  • Para usar o Azure Machine Learning, você precisa ter uma assinatura do Azure. Caso não tenha uma assinatura do Azure, crie uma conta gratuita antes de começar. Experimente hoje mesmo a versão gratuita ou paga do Azure Machine Learning.

  • Instale e configure a extensão CLI do Azure Machine Learning (v2) ou o SDK do Python do Azure Machine Learning (v2).

  • Um grupo de recursos do Azure, no qual você (ou a entidade de serviço usada) precisa ter User Access Administrator e Contributor acesso. Você terá esse grupo de recursos se tiver configurado sua extensão do Azure Machine Learning, conforme indicado anteriormente.

  • Um Workspace do Azure Machine Learning. Você terá um workspace se tiver configurado sua extensão do Azure Machine Learning, conforme indicado anteriormente.

  • Qualquer modelo de machine learning treinado pronto para pontuação e implantação.

Escolha um repositório de segredos

Você pode optar por armazenar seus segredos (como chaves de API) usando:

  • Conexões de workspace no workspace: se você usar esse tipo de repositório de segredos, poderá conceder permissão posteriormente à identidade do ponto de extremidade (no momento da criação do ponto de extremidade) para ler segredos de conexões de workspace automaticamente, desde que determinadas condições sejam atendidas. Para obter mais informações, consulte a guia de identidade atribuída pelo sistema na seção Criar um ponto de extremidade.
  • Cofres de chaves que não estejam necessariamente no workspace: se você usar esse tipo de repositório de segredo, a identidade do ponto de extremidade não receberá permissão para ler segredos dos cofres de chaves automaticamente. Portanto, se você quiser usar um serviço de cofre de chaves gerenciado, como o Microsoft Azure Key Vault como um repositório de segredos, deverá atribuir uma função adequada posteriormente.

Usar a conexão do workspace como um repositório de segredos

Você pode criar conexões de workspace para uso em sua implantação. Por exemplo, você pode criar uma conexão com o Serviço OpenAI do Microsoft Azure usando Conexões de Workspace – Criar API REST.

Como alternativa, você pode criar uma conexão personalizada usando o Estúdio do Azure Machine Learning (consulte Como criar uma conexão personalizada para o prompt flow) ou o Estúdio de IA do Azure (consulte Como criar uma conexão personalizada no Estúdio de IA).

  1. Criar uma conexão OpenAI do Azure:

    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. Como alternativa, você pode criar uma conexão 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. Verifique se a identidade do usuário pode ler os segredos da conexão do workspace usando Conexões do Workspace – Listar Segredos da API REST (versão prévia).

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

Observação

Os snippets de código anteriores usam um token no cabeçalho Authorization ao fazer chamadas à API REST. Você pode obter o token executando az account get-access-token. Para mais informações sobre como obter um token, consulte Obter um token de acesso.

(Opcional) Usar o Azure Key Vault como um repositório de segredos

Crie o cofre de chaves e defina um segredo a ser usado em sua implantação. Para saber mais, sobre a criação de um cofre de chaves, confira Definir e recuperar um segredo do Azure Key Vault usando a CLI do Azure. Além disso,

  1. Crie um Azure Key Vault:

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

  2. Crie um segredo:

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

    Esse comando retorna a versão do segredo que ele cria. Você pode verificar a propriedade id da resposta para obter a versão do segredo. A resposta retornada tem a seguinte aparência https://mykeyvault.vault.azure.net/secrets/<secret_name>/<secret_version>.

  3. Verifique se a identidade do usuário pode ler o segredo do cofre de chaves:

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

Importante

Se você usar o cofre de chaves como um repositório de segredos para injeção de segredo, deverá configurar o modelo de permissão do cofre de chaves como RBAC (controle de acesso baseado em função) do Azure. Para obter mais informações, consulte RBAC do Azure versus política de acesso para o Key Vault.

Escolher uma identidade de usuário

Escolha a identidade do usuário que você usará para criar o ponto de extremidade online e a implantação online. Essa identidade de usuário pode ser uma conta de usuário, uma conta de entidade de serviço ou uma identidade gerenciada no Microsoft Entra ID. Para definir a identidade do usuário, siga as etapas em Configurar a autenticação para recursos e fluxos de trabalho do Azure Machine Learning.

(Opcional) Atribuir uma função à identidade do usuário

  • Se a identidade de usuário quiser que a SAI (identidade atribuída pelo sistema) do ponto de extremidade receba permissão automaticamente para ler segredos de conexões de workspace, a identidade do usuário deverá ter a função Azure Machine Learning Workspace Connection Secrets Reader (ou superior) no escopo do workspace.

    • Um administrador com a permissão Microsoft.Authorization/roleAssignments/write pode executar um comando da CLI para atribuir a função à identidade do usuário:

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

    Observação

    A SAI (identidade atribuída pelo sistema) do ponto de extremidade não receberá permissão automaticamente para ler segredos de cofres de chaves. Portanto, a identidade do usuário não precisa ser atribuída a uma função para o Key Vault.

  • Se você quiser usar uma UAI (identidade atribuída pelo usuário) para o ponto de extremidade, não será necessário atribuir a função à sua identidade de usuário. Em vez disso, se você pretende usar o recurso de injeção de segredo, deverá atribuir a função à UAI do ponto de extremidade manualmente.

    • Um administrador com a permissão Microsoft.Authorization/roleAssignments/write pode executar os comandos a seguir para atribuir a função à identidade do ponto de extremidade:

      Para conexões do espaço de trabalho:

      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 cofres de chaves:

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

  • Verifique se uma identidade (uma identidade de usuário ou uma identidade de ponto de extremidade) tem a função atribuída, acessando o recurso no portal do Azure. Por exemplo, no workspace do Azure Machine Learning ou no Key Vault:

    1. Selecione a guia Controle de acesso (IAM).
    2. Selecione o botão Verificar acesso e localize a identidade.
    3. Verifique se a função certa aparece na guia Atribuições de função atuais.

Criar um ponto de extremidade

Se você estiver usando uma SAI (identidade atribuída pelo sistema) como a identidade do ponto de extremidade, especifique se deseja impor o acesso a repositórios de segredos padrão (ou seja, conexões de workspace no workspace) para a identidade do ponto de extremidade.

  1. Criar um arquivo 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. Crie o ponto de extremidade usando o arquivo endpoint.yaml:

    az ml online-endpoint create -f endpoint.yaml

Se você não especificar a propriedade identity na definição do ponto de extremidade, o ponto de extremidade usará um SAI por padrão.

Se as seguintes condições forem atendidas, a identidade do ponto de extremidade receberá automaticamente a função Azure Machine Learning Workspace Connection Secrets Reader (ou superior) no escopo do workspace:

  • A identidade do usuário que cria o ponto de extremidade tem permissão para ler segredos de conexões de workspace (Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action).
  • O ponto de extremidade usa um SAI.
  • O ponto de extremidade é definido com um sinalizador para impor o acesso aos repositórios de segredos padrão (conexões de workspace no workspace atual) ao criar o ponto de extremidade.

A identidade do ponto de extremidade não receberá automaticamente uma função para ler segredos do Key Vault. Se você quiser usar o Key Vault como um repositório secreto, será necessário atribuir manualmente uma função adequada, como Key Vault Secrets User à identidade do ponto de extremidade no escopo do Key Vault. Para obter mais informações sobre funções, consulte Funções internas do Azure para operações de plano de dados do Key Vault.

Criar uma implantação

  1. Crie um script de pontuação ou Dockerfile e os scripts relacionados para que a implantação possa consumir os segredos por meio de variáveis de ambiente.

    • Não é necessário chamar as APIs de recuperação de segredo para as conexões de workspace ou cofres de chaves. As variáveis de ambiente são preenchidas com os segredos quando o contêiner do usuário na implantação é iniciado.

    • O valor injetado em uma variável de ambiente pode ter um dos três tipos:

      • Toda a resposta da API Listar Segredos (versão prévia). Você precisará entender a estrutura de resposta da API, analisá-la e usá-la no contêiner do usuário.
      • Segredo individual ou metadados da conexão do workspace. Você pode usá-lo sem entender a estrutura de resposta da API de conexão do workspace.
      • Versão de segredo individual do Key Vault. Você pode usá-lo sem entender a estrutura de resposta da API do Key Vault.

  2. Inicie a criação da implantação usando o script de pontuação (se você usar um modelo personalizado) ou um Dockerfile (se você usar a abordagem BYOC para implantação). Especifique as variáveis de ambiente que o usuário espera dentro do contêiner do usuário.

    Se os valores mapeados para as variáveis de ambiente seguirem determinados padrões, a identidade do ponto de extremidade será usada para executar a recuperação e a injeção de segredo.

    Padrão Comportamental
    ${{azureml://connections/<connection_name>}} Toda a resposta da API Listar Segredos (versão prévia) é injetada na variável de ambiente.
    ${{azureml://connections/<connection_name>/credentials/<credential_name>}} O valor da credencial é injetado na variável de ambiente.
    ${{azureml://connections/<connection_name>/metadata/<metadata_name>}} O valor dos metadados é injetado na variável de ambiente.
    ${{azureml://connections/<connection_name>/target}} O valor do destino (quando aplicável) é injetado na variável de ambiente.
    ${{keyvault:https://<keyvault_name>.vault.azure.net/secrets/<secret_name>/<secret_version>}} O valor da versão do segredo é injetado na variável de ambiente.

    Por exemplo:

    1. Criar 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. Criar a implantação:

      az ml online-deployment create -f deployment.yaml

Se o sinalizador enforce_access_to_default_secret_stores foi definido para o ponto de extremidade, a permissão da identidade do usuário para ler segredos de conexões de workspace será verificada na criação do ponto de extremidade e no momento da criação da implantação. Se a identidade do usuário não tiver a permissão, a criação falhará.

No momento da criação da implantação, se qualquer variável de ambiente for mapeada para um valor que siga os padrões na tabela anterior, a recuperação e a injeção de segredo serão executadas com a identidade do ponto de extremidade (SAI ou UAI). Se a identidade do ponto de extremidade não tiver permissão para ler segredos de repositórios de segredos designados (conexões de workspace ou cofres de chaves), a criação da implantação falhará. Além disso, se a referência do segredo especificada não existir nos repositórios de segredos, a criação da implantação falhará.

Para obter mais informações sobre erros que podem ocorrer durante a implantação de pontos de extremidade online do Azure Machine Learning, consulte Erros de Injeção de Segredo.

Consumir os segredos

Você pode consumir os segredos recuperando-os das variáveis de ambiente dentro do contêiner de usuário em execução em suas implantações.

Conteúdo relacionado