Usar sessões dinâmicas em Aplicativos de Contêiner do Azure

As sessões dinâmicas dos Aplicativos de Contêiner do Azure oferecem contextos isolados e seguros quando você precisa executar código ou aplicativos separadamente de outras cargas de trabalho. As sessões são executadas dentro de um pool de sessões que fornece acesso imediato a sessões novas e existentes. Essas sessões são ideais para cenários em que a entrada gerada pelo usuário precisa ser processada de forma controlada ou ao integrar serviços de terceiros que exigem a execução de código em um ambiente isolado.

Este artigo mostra como gerenciar e interagir com sessões dinâmicas.

Acesso à sessão

Seu aplicativo interage com uma sessão usando a API de gerenciamento do pool de sessões.

Um ponto de extremidade de gerenciamento de pool segue este formato:

https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io

Para obter mais informações sobre como gerir pools de sessão, consulte Ponto de Extremidade de Gerenciamento de Pools de Sessões

Encaminhando solicitações para o contêiner de uma sessão

Para enviar uma solicitação para o contêiner de uma sessão, use o ponto de extremidade de gerenciamento como a raiz da solicitação. Qualquer coisa no caminho após o ponto de extremidade de gerenciamento do pool base é encaminhada para o contêiner da sessão.

Por exemplo, se você fizer uma chamada para: <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile, a solicitação será roteada para o contêiner da sessão em 0.0.0.0:<TARGET_PORT>/api/uploadfile.

Interação contínua

À medida que você continua a fazer chamadas para a mesma sessão, a sessão permanece alocada no pool. Quando não houver solicitações para a sessão após o período de resfriamento, a sessão será automaticamente destruída.

Pedido de amostra

O exemplo a seguir mostra como enviar solicitação para uma sessão usando o ID de um usuário como identificador exclusivo da sessão.

Antes de enviar a solicitação, substitua os espaços reservados entre <> colchetes por valores específicos para sua solicitação.

POST <POOL_MANAGEMENT_ENDPOINT>/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

Essa solicitação é encaminhada para o contêiner na sessão com o identificador do ID do usuário.

Se a sessão ainda não estiver em execução, os Aplicativos de Contêiner do Azure alocarão automaticamente uma sessão do pool antes de encaminhar a solicitação.

Neste exemplo, o contêiner da sessão recebe a solicitação em http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>.

Identificadores

Para enviar uma solicitação HTTP para uma sessão, você deve fornecer um identificador de sessão na solicitação. Você passa o identificador de sessão em um parâmetro de cadeia de caracteres de consulta nomeado identifier na URL quando faz uma solicitação para uma sessão.

• Se já existir uma sessão com o identificador, o pedido é enviado para a sessão existente.

• Se uma sessão com o identificador não existir, uma nova sessão será automaticamente alocada antes que a solicitação seja enviada a ela.

Formato do identificador

O identificador de sessão é uma cadeia de caracteres de forma livre, o que significa que você pode defini-lo de qualquer maneira que atenda às necessidades do seu aplicativo.

O identificador de sessão é uma cadeia de caracteres que você define que é exclusiva dentro do pool de sessões. Se você estiver criando um aplicativo Web, poderá usar o ID do usuário como identificador de sessão. Se você estiver criando um chatbot, poderá usar o ID da conversa.

O identificador deve ser uma cadeia de caracteres com 4 a 128 caracteres e pode conter apenas caracteres alfanuméricos e caracteres especiais desta lista: |, -, &, ^, %$#(){}[];<e .>

Segurança

As sessões dinâmicas são criadas para executar código e aplicativos não confiáveis em um ambiente seguro e isolado. Embora as sessões sejam isoladas umas das outras, qualquer coisa dentro de uma única sessão, incluindo arquivos e variáveis de ambiente, é acessível pelos usuários da sessão.

Configure ou carregue dados confidenciais para uma sessão somente se confiar nos usuários da sessão.

Por padrão, as sessões são impedidas de fazer solicitações de rede de saída. Você pode controlar o acesso à rede definindo as configurações de status da rede no pool de sessões.

• Use identificadores de sessão fortes e exclusivos: sempre gere identificadores de sessão longos e complexos para evitar ataques de força bruta. Use algoritmos criptográficos para criar identificadores difíceis de adivinhar.

• Limitar a visibilidade da sessão: defina controles de acesso rígidos para garantir que os identificadores de sessão sejam visíveis apenas para o pool de sessões. Evite expor IDs de sessão em URLs ou logs.

• Implementar tempos de expiração curtos: configure identificadores de sessão para expirar após um curto período de inatividade. Essa abordagem minimiza o risco de sessões serem sequestradas depois que um usuário terminar de interagir com seu aplicativo.

• Alterne regularmente as credenciais da sessão: examine e atualize periodicamente as credenciais associadas às suas sessões. A rotação diminui o risco de acesso não autorizado.

• Utilize protocolos de transmissão seguros: sempre use HTTPS para criptografar dados em trânsito, incluindo identificadores de sessão. Esta abordagem protege contra ataques man-in-the-middle.

• Monitorar a atividade da sessão: implemente o registro em log e o monitoramento para controlar as atividades da sessão. Use esses logs para identificar padrões incomuns ou possíveis violações de segurança.

• Validar entrada do usuário: trate todas as entradas do usuário como perigosas. Use técnicas de validação e higienização de entrada para proteger contra ataques de injeção e garantir que apenas dados confiáveis sejam processados.

Para proteger totalmente suas sessões, você pode:

• Usar autenticação e autorização do Microsoft Entra ID
• Proteger identificadores de sessão

Autenticação e autorização

Quando você envia solicitações para uma sessão usando a API de gerenciamento de pool, a autenticação é tratada usando tokens do Microsoft Entra. Somente os tokens Microsoft Entra de uma identidade pertencente à função Executor de Sessão do Azure ContainerApps no pool de sessões estão autorizados a chamar a API de gerenciamento do pool.

Para atribuir a função a uma identidade, use o seguinte comando da CLI do Azure:

az role assignment create \
    --role "Azure ContainerApps Session Executor" \
    --assignee <PRINCIPAL_ID> \
    --scope <SESSION_POOL_RESOURCE_ID>

Se você estiver usando uma integração de estrutura de modelo de linguagem grande (LLM), a estrutura lida com a geração e o gerenciamento de tokens para você. Verifique se o aplicativo está configurado com uma identidade gerenciada com as atribuições de função necessárias no pool de sessões.

Se você estiver usando os pontos de extremidade da API de gerenciamento do pool diretamente, deverá gerar um token e incluí-lo no Authorization cabeçalho de suas solicitações HTTP. Além das atribuições de função mencionadas anteriormente, o token precisa conter uma declaração de audiência (aud) com o valor https://dynamicsessions.io.

az account get-access-token --resource https://dynamicsessions.io

dotnet add package Azure.Identity

using Azure.Identity;

var credential = new DefaultAzureCredential();
var token = credential.GetToken(new TokenRequestContext(new[] { "https://dynamicsessions.io/.default" }));
var accessToken = token.Token;

npm install @azure/identity

const { DefaultAzureCredential } = require("@azure/identity");
const { TokenCredential } = require("@azure/core-auth");

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://dynamicsessions.io/.default");
const accessToken = token.token;

pip install azure-identity

from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()
token = credential.get_token("https://dynamicsessions.io/.default")
access_token = token.token

Proteger identificadores de sessão

O identificador de sessão é uma informação confidencial que deve ser gerida de forma segura. Seu aplicativo precisa garantir que cada usuário ou locatário tenha acesso apenas às suas próprias sessões.

As estratégias específicas que evitam o uso indevido de identificadores de sessão diferem dependendo do design e da arquitetura do seu aplicativo. No entanto, seu aplicativo sempre deve ter controle total sobre a criação e o uso de identificadores de sessão para que um usuário mal-intencionado não possa acessar a sessão de outro usuário.

Exemplos de estratégias incluem:

• Uma sessão por usuário: se seu aplicativo usa uma sessão por usuário, cada usuário deve ser autenticado com segurança e seu aplicativo deve usar um identificador de sessão exclusivo para cada usuário conectado.

• Uma sessão por conversa de agente: se seu aplicativo usa uma sessão por conversa de agente de IA, certifique-se de que seu aplicativo use um identificador de sessão exclusivo para cada conversa que não possa ser modificada pelo usuário final.

Utilizar a identidade gerida

Uma identidade gerenciada do Microsoft Entra ID permite que seus pools de sessões de contêiner e as suas sessões acessem outros recursos protegidos pelo Microsoft Entra. As identidades gerenciadas atribuídas pelo sistema e pelo usuário são suportadas em um pool de sessões.

Para obter mais informações sobre identidades gerenciadas no Microsoft Entra ID, consulte Identidades gerenciadas para recursos do Azure.

Há duas maneiras de usar identidades geridas com grupos de sessão de contentores personalizados:

• Autenticação de pull de imagem: use a identidade gerenciada para autenticar com o registro de contêiner para extrair a imagem de contêiner.

• Acesso a recursos: use a identidade gerenciada do pool de sessões em uma sessão para acessar outros recursos protegidos pelo Microsoft Entra. Devido às suas implicações de segurança, esse recurso é desativado por padrão.

  Importante

  Se você habilitar o acesso à identidade gerenciada em uma sessão, qualquer código ou programa em execução na sessão poderá criar tokens do Microsoft Entra para a identidade gerenciada do pool. Como as sessões geralmente executam código não confiável, use esse recurso com extrema cautela.

{
  "type": "Microsoft.App/sessionPools",
  "apiVersion": "2024-08-02-preview",
  "name": "my-session-pool",
  "location": "westus2",
  "properties": {
    "environmentId": "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>",
    "poolManagementType": "Dynamic",
    "containerType": "CustomContainer",
    "scaleConfiguration": {
      "maxConcurrentSessions": 10,
      "readySessionInstances": 5
    },
    "dynamicPoolConfiguration": {
      "executionType": "Timed",
      "cooldownPeriodInSeconds": 600
    },
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "identity": "<IDENTITY_RESOURCE_ID>"
      },
      "containers": [
        {
          "image": "myregistry.azurecr.io/my-container-image:1.0",
          "name": "mycontainer",
          "resources": {
            "cpu": 0.25,
            "memory": "0.5Gi"
          },
          "command": [
            "/bin/sh"
          ],
          "args": [
            "-c",
            "while true; do echo hello; sleep 10;done"
          ],
          "env": [
            {
              "name": "key1",
              "value": "value1"
            },
            {
              "name": "key2",
              "value": "value2"
            }
          ]
        }
      ],
      "ingress": {
        "targetPort": 80
      }
    },
    "sessionNetworkConfiguration": {
      "status": "EgressEnabled"
    },
    "managedIdentitySettings": [
      {
        "identity": "<IDENTITY_RESOURCE_ID>",
        "lifecycle": "None"
      }
    ]
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "<IDENTITY_RESOURCE_ID>": {}
    }
  }
}

Exploração Florestal

Os logs de console de contêineres em execução em uma sessão estão disponíveis no espaço de trabalho do Azure Log Analytics associado ao ambiente de Aplicativos de Contêiner do Azure em uma tabela chamada AppEnvSessionConsoleLogs_CL.

Conteúdo relacionado

• Tipos de sessão: Saiba mais sobre os diferentes tipos de sessões dinâmicas:

  • Sessões de intérprete de código
  • Sessões de contêiner personalizadas

• Tutoriais: Trabalhe diretamente com a API REST ou através de um agente LLM:

  • Use um agente LLM:
    • AutoGen
    • LangChain
    • LlamaIndex
    • Kernel semântico
  • Usar a API REST
    • Interpretador de código JavaScript