Usar sessões dinâmicas nos 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ódigos 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 maneira 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ão.

Um endpoint de gerenciamento de pool possui este formato:

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

Para obter mais informações sobre o gerenciamento de pools de sessão, veja o ponto de extremidade de gerenciamento de pools de sessão

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

Para enviar uma solicitação ao contêiner de uma sessão, use o ponto de extremidade de gerenciamento como raiz da sua solicitação. Qualquer coisa no caminho após o ponto de extremidade de gerenciamento do pool de 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. Depois que não houver solicitações para a sessão após o período de resfriamento ter decorrido, a sessão será destruída automaticamente.

Solicitação de exemplo

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

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> por valores específicos à 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 da 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, a solicitação será enviada para a sessão existente.

• Se uma sessão com o identificador não existir, uma nova sessão será alocada automaticamente 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-la de qualquer maneira que atenda às necessidades do aplicativo.

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

O identificador deve ser uma cadeia de caracteres de 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 aplicativos e códigos 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.

Somente configure ou carregue dados confidenciais em uma sessão se confiar nos usuários dela.

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 de 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 estritos para garantir que os identificadores de sessão só estejam visíveis 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 seqüestradas depois que um usuário terminar de interagir com seu aplicativo.

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

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

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

• Validar a entrada do usuário: trate toda a entrada do usuário como perigosa. Use técnicas de validação de entrada e saneamento 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 do Microsoft Entra de uma identidade pertencente à função Executor de Sessão dos Aplicativos de Contêiner do Azure no pool de sessões estão autorizados a chamar a API de gerenciamento de 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 framework LLM (modelo de linguagem de grande escala), o framework manipulará 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ão.

Se você estiver usando diretamente os pontos de extremidade da API de gerenciamento do pool, deverá gerar um token e incluí-lo no cabeçalho Authorization 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 é as informações confidenciais que você deve gerenciar com segurança. Seu aplicativo precisa garantir que cada usuário ou locatário tenha acesso apenas a suas próprias sessões.

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

As estratégias de exemplo incluem:

• Uma sessão por usuário: caso o aplicativo use 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: caso o aplicativo use uma sessão por conversa de agente de IA, garanta que o aplicativo use um identificador de sessão exclusivo para cada conversa que não possa ser modificado pelo usuário final.

Usar identidade gerenciada

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

Para saber mais sobre identidades gerenciadas no Microsoft Entra ID, confira Identidades gerenciadas para recursos do Azure.

Há duas maneiras de usar identidades gerenciadas com os pools de sessões de contêiner 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 do Microsoft Entra. Devido a suas implicações de segurança, essa funcionalidade está desabilitada 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 normalmente 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>": {}
    }
  }
}

Registro

Os logs do 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 interpretador de código
  • Sessões de contêiner personalizadas

• Tutoriais: trabalhe diretamente com a API REST ou por meio de um agente LLM:

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