Compartilhar via

Usar pools de sessão nos Aplicativos de Contêiner do Azure

Os pools de sessões fornecem tempos de alocação de sessão inferiores a um segundo e gerenciam o ciclo de vida de cada sessão.

Conceitos comuns para ambas as piscinas

O processo de criação de um pool é ligeiramente diferente dependendo se você está criando um pool de sessão de interpretador de código ou um pool de contêineres personalizado. Os conceitos a seguir se aplicam a ambos.

Para criar pools de sessão usando a CLI do Azure, verifique se você tem as versões mais recentes da CLI do Azure e da extensão aplicativos de contêiner do Azure:

# Upgrade the Azure CLI
az upgrade

# Install or upgrade the Azure Container Apps extension
az extension add --name containerapp --upgrade --allow-preview true -y

Dentre os comandos comuns do pool de sessão, incluem-se:

  • az containerapp sessionpool create
  • az containerapp sessionpool show
  • az containerapp sessionpool list
  • az containerapp sessionpool update
  • az containerapp sessionpool delete

Use --help com qualquer comando para ver argumentos disponíveis e valores com suporte.

Para verificar o status de um pool de sessões, use o az containerapp sessionpool show comando:

az containerapp sessionpool show \
    --name <SESSION_POOL_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query "properties.poolManagementEndpoint" \
    --output tsv

Ao criar ou atualizar um pool, você pode definir um número máximo de sessões simultâneas, um período de resfriamento ocioso e se o tráfego de rede de saída é permitido para sessões.

Importante

Se você habilitar a saída, o código em execução na sessão poderá acessar a Internet. Tenha cuidado quando o código não for confiável porque ele pode ser usado para executar atividades mal-intencionadas, como ataques de negação de serviço.

Importante

Se a sessão for usada para executar código não confiável, não inclua informações ou dados que você não deseja que o código não confiável acesse. Suponha que o código seja mal-intencionado e tenha acesso total ao contêiner, incluindo suas variáveis de ambiente, segredos e arquivos.

Configurar um pool

Use az containerapp sessionpool create --help para ver os argumentos mais recentes da CLI para a configuração do pool de sessão. Esta seção se concentra em opções de configuração avançadas que se aplicam em versões de API.

Configuração do ciclo de vida da sessão

Ao criar ou atualizar um pool de sessões, você pode configurar como as sessões são encerradas por meio da configuração properties.dynamicPoolConfiguration.lifecycleConfiguration. A partir da versão 2025-01-01da API, escolha um dos dois tipos de ciclo de vida.

Para obter a especificação completa da API, consulte a especificação da API SessionPools.

Cronometrado (padrão)

Com o Timed ciclo de vida, uma sessão é excluída após um período de inatividade. Qualquer solicitação enviada a uma sessão redefine o temporizador de resfriamento, estendendo o tempo de vida da sessão em cooldownPeriodInSeconds.

Observação

Timed tem suporte para todos os tipos de pool de sessão e funciona da mesma forma que executionType: Timed nas versões anteriores da API.

{
  "dynamicPoolConfiguration": {
    "lifecycleConfiguration": {
      "cooldownPeriodInSeconds": 600,
      "lifecycleType": "Timed"
    }
  }
}
Propriedade Description
cooldownPeriodInSeconds A sessão é excluída quando não há solicitações para essa duração.
maxAlivePeriodInSeconds Não compatível com o ciclo de vida Timed.

Ponto de extremidade de gerenciamento

Importante

O identificador de sessão é uma informação confidencial que exige um processo seguro à medida que você cria e gerencia seu valor. Para proteger esse valor, seu aplicativo deve garantir que cada usuário ou locatário tenha acesso apenas a suas próprias sessões.

A falha na proteção do acesso às sessões pode resultar em uso indevido ou acesso não autorizado aos dados armazenados nas sessões dos usuários. Para obter mais informações, consulte identificadores de sessão

Todas as solicitações para o ponto de extremidade de gerenciamento do pool precisam incluir um cabeçalho Authorization com um token de portador. Para saber como autenticar com a API de gerenciamento de pool, consulte Autenticação.

Cada solicitação de API também deve incluir o parâmetro identifier de cadeia de caracteres de consulta com a ID da sessão. Essa ID de sessão exclusiva permite que seu aplicativo interaja com sessões específicas. Para saber mais sobre identificadores de sessão, consulte identificadores de sessão.

Cache de imagem

Quando um pool de sessões é criado ou atualizado, os Aplicativos de Contêiner do Azure armazenam em cache a imagem de contêiner no pool. Esse cache ajuda a acelerar o processo de criação de novas sessões.

As alterações na imagem não são refletidas automaticamente nas sessões. Para atualizar a imagem, atualize o pool de sessões com uma nova tag de imagem. Use uma marca exclusiva para cada atualização de imagem para garantir que seja efetuado o pull da nova imagem.

Pool de sessão do interpretador de código

Use o az containerapps sessionpool create comando para criar o pool. O exemplo a seguir cria um pool de sessão de interpretador de código do Python chamado my-session-pool. Substitua <RESOURCE_GROUP> pelo nome do seu grupo de recursos antes de executar o comando.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --location westus2 \
    --container-type PythonLTS \
    --max-sessions 100 \
    --cooldown-period 300 \
    --network-status EgressDisabled

Você pode definir as seguintes configurações ao criar um pool de sessões:

Configurações Description
--container-type O tipo de interpretador de código a ser usado. Os valores compatíveis incluem: PythonLTS, NodeLTS, Shell e CustomContainer.
--max-sessions O número máximo de sessões alocadas permitidas simultaneamente. O valor máximo é 600.
--cooldown-period O número de segundos ociosos permitidos antes do encerramento. O período ocioso é redefinido sempre que a API da sessão é chamada. O intervalo permitido é entre 300 e 3600.
--network-status Especifica se o tráfego de rede de saída é permitido na sessão. Os valores válidos são EgressDisabled (padrão) e EgressEnabled.

Endpoint de gerenciamento do interpretador de código

Para usar sessões de interpretador de código com integrações da estrutura LLM ou chamando diretamente os pontos de extremidade da API de gerenciamento, você precisa do ponto de extremidade da API de gerenciamento do pool.

O ponto de extremidade está no formato https://<REGION>.dynamicsessions.io/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/sessionPools/<SESSION_POOL_NAME>.

Para recuperar o ponto de extremidade da API de gerenciamento de um pool de sessões, consulte a seção comum acima para obter um exemplo de comando.

Os seguintes endpoints estão disponíveis para gerenciar sessões em um pool:

Caminho do ponto de extremidade Método Description
code/execute POST Execute o código em uma sessão.
files/upload POST Carregue um arquivo em uma sessão.
files/content/{filename} GET Baixe um arquivo de uma sessão.
files GET Liste os arquivos em uma sessão.

Você cria a URL completa para cada ponto de extremidade concatenando o ponto de extremidade da API de gerenciamento do pool com o caminho do ponto de extremidade. A cadeia de caracteres de consulta deve incluir um identifier parâmetro que contém o identificador de sessão e um api-version parâmetro com o valor 2024-02-02-preview. As versões da API podem ser alteradas, portanto, sempre confirme a versão mais recente nos documentos da API REST antes de usá-la em produção.

Por exemplo: {sessionManagementEndpoint}/code/execute?api-version=2024-02-02-preview&identifier=<IDENTIFIER>

Para referências à API REST, consulte as APIs do plano de dados dos Aplicativos de Contêiner e a Visão geral das operações do plano de dados dos Aplicativos de Contêiner.

Pool de sessão de contêiner personalizado

Para criar um pool de sessões de contêiner personalizado, você precisa fornecer uma imagem de contêiner e configurações do pool.

Você invoca ou se comunica com cada sessão usando solicitações HTTP. O contêiner personalizado deve expor um servidor HTTP em uma porta especificada para responder a essas solicitações.

Os recursos a seguir se aplicam somente a pools de sessão de contêiner personalizados.

Ponto de extremidade de gerenciamento de contêiner personalizado

Para pools de sessões de contêiner personalizados, obtenha o ponto de extremidade de gerenciamento no portal do Azure ou na saída da CLI do Azure. O ponto de extremidade é retornado como poolManagementEndpoint.

O ponto de extremidade está no formato https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io.

OnContainerExit

Com o ciclo de vida OnContainerExit, uma sessão permanece ativa até que o contêiner seja encerrado automaticamente ou o período máximo de atividade seja atingido.

{
  "dynamicPoolConfiguration": {
    "lifecycleConfiguration": {
      "maxAlivePeriodInSeconds": 6000,
      "lifecycleType": "OnContainerExit"
    }
  }
}
Propriedade Description
maxAlivePeriodInSeconds Tempo máximo em que a sessão pode permanecer ativa antes de ser excluída.
cooldownPeriodInSeconds Não compatível com o ciclo de vida OnContainerExit.

Verificações de contêiner

As sondas de contêiner permitem definir verificações de integridade para contêineres de sessão, para que o pool possa detectar sessões com problemas e substituí-las para manter o destino readySessionInstances íntegro.

Os pools de sessão são compatíveis com sondas de Atividade e Inicialização. Para obter mais informações sobre o comportamento da sonda, consulte sondas de integridade nos Aplicativos de Contêiner do Azure.

Ao criar ou atualizar um pool de sessões, especifique sondas em properties.customContainerTemplate.containers. Para obter o esquema completo do corpo da solicitação, consulte a referência da API de Criação ou Atualização de SessionPools. O exemplo a seguir mostra uma configuração parcial com definições de sondas.

{
  "properties": {
    "customContainerTemplate": {
      "containers": [
        {
          "name": "my-session-container",
          "image": "myregistry.azurecr.io/my-session-image:latest",
          "probes": [
            {
              "type": "Liveness",
              "httpGet": {
                "path": "/health",
                "port": 8080
              },
              "periodSeconds": 10,
              "failureThreshold": 3
            },
            {
              "type": "Startup",
              "httpGet": {
                "path": "/ready",
                "port": 8080
              },
              "periodSeconds": 5,
              "failureThreshold": 30
            }
          ]
        }
      ]
    },
    "dynamicPoolConfiguration": {
      "readySessionInstances": 5
    }
  }
}

Os pools de sessão de contêiner personalizados exigem um ambiente do Azure Container Apps com perfis de carga de trabalho habilitados. Se você não tiver um ambiente, use o az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> comando para criar um.

Use o az containerapp sessionpool create comando para criar um pool de sessão de contêiner personalizado.

O exemplo a seguir cria um pool de sessão nomeado my-session-pool com uma imagem myregistry.azurecr.io/my-container-image:1.0de contêiner personalizada.

Antes de enviar a solicitação, substitua os espaços reservados entre os colchetes <> pelos valores apropriados do pool de sessão e do identificador de sessão.

az containerapp sessionpool create \
    --name my-session-pool \
    --resource-group <RESOURCE_GROUP> \
    --environment <ENVIRONMENT> \
    --registry-server myregistry.azurecr.io \
    --registry-username <USER_NAME> \
    --registry-password <PASSWORD> \
    --container-type CustomContainer \
    --image myregistry.azurecr.io/my-container-image:1.0 \
    --cpu 0.25 --memory 0.5Gi \
    --target-port 80 \
    --cooldown-period 300 \
    --network-status EgressDisabled \
    --max-sessions 10 \
    --ready-sessions 5 \
    --env-vars "key1=value1" "key2=value2" \
    --location <LOCATION>

Esse comando cria um pool de sessões com as seguintes configurações:

Parâmetro Value Description
--name my-session-pool O nome do pool de sessões.
--resource-group my-resource-group O grupo de recursos que contém o pool de sessões.
--environment my-environment O nome ou o identificador do recurso do ambiente do aplicativo de contêiner.
--container-type CustomContainer O tipo de contêiner do pool de sessão. Deve ser CustomContainer para sessões de contêiner personalizadas.
--image myregistry.azurecr.io/my-container-image:1.0 A imagem de contêiner a ser usada para o pool de sessão.
--registry-server myregistry.azurecr.io O nome do host do servidor de registro de contêineres.
--registry-username my-username O nome de usuário para fazer login no registro de contêiner.
--registry-password my-password A senha para fazer logon no registro de contêiner.
--cpu 0.25 A CPU necessária em núcleos.
--memory 0.5Gi A memória necessária.
--target-port 80 A porta de sessão usada para o tráfego de entrada.
--cooldown-period 300 O número de segundos que uma sessão pode ficar ociosa antes de a sessão ser encerrada. O período ocioso é redefinido sempre que a API da sessão é chamada. O valor deve estar entre 300 e 3600.
--network-status EgressDisabled Especifica se o tráfego de rede de saída é permitido na sessão. Os valores válidos são EgressDisabled (padrão) e EgressEnabled.
--max-sessions 10 O número máximo de sessões que podem ser alocadas ao mesmo tempo.
--ready-sessions 5 O número de sessões de destino que estão prontas no pool de sessão o tempo todo. Aumente esse número se as sessões forem alocadas mais rapidamente do que o pool é reabastecido.
--env-vars "key1=value1" "key2=value2" As variáveis de ambiente a serem definidas no contêiner.
--location "Supported Location" O local do pool de sessão.

Para atualizar o pool de sessões, use o az containerapp sessionpool update comando.

  • Last updated on