Sessões de contêiner personalizadas dos Aplicativos de Contêiner do Azure

Artigo
11/07/2024

Além do interpretador de código interno que as sessões dinâmicas dos Aplicativos de Contêiner do Azure fornecem, você também pode usar contêineres personalizados para definir suas próprias áreas restritas de sessão.

Usos para sessões de contêiner personalizadas

Os contentores personalizados permitem-lhe criar soluções adaptadas às suas necessidades. Eles permitem que você execute código ou execute aplicativos em ambientes rápidos e efêmeros e oferecem espaços seguros e em área restrita com o Hyper-V. Além disso, eles podem ser configurados com isolamento de rede opcional. Alguns exemplos incluem:

Interpretadores de código: quando você precisa executar código não confiável em caixas de proteção seguras por uma linguagem não suportada no interpretador interno ou precisa de controle total sobre o ambiente do interpretador de código.
Execução isolada: quando você precisa executar aplicativos em cenários hostis e multilocatários em que cada locatário ou usuário tem seu próprio ambiente em área restrita. Esses ambientes são isolados uns dos outros e do aplicativo host. Alguns exemplos incluem aplicativos que executam código fornecido pelo usuário, código que concede ao usuário final acesso a um shell baseado em nuvem, agentes de IA e ambientes de desenvolvimento.

Usando sessões de contêiner personalizadas

Para usar sessões de contêiner personalizadas, primeiro crie um pool de sessões com uma imagem de contêiner personalizada. Os Aplicativos de Contêiner do Azure iniciam automaticamente os contêineres em suas próprias caixas de proteção do Hyper-V usando a imagem fornecida. Assim que o contêiner for iniciado, ele estará disponível para o pool de sessões.

Quando seu aplicativo solicita uma sessão, uma instância é alocada instantaneamente do pool. A sessão permanece ativa até entrar em um estado ocioso, que é automaticamente interrompido e destruído.

Criando um pool de sessões de contêiner personalizado

Para criar um pool de sessões de contêiner personalizado, você precisa fornecer uma imagem de contêiner e definições de configuração 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.

CLI do Azure
Azure Resource Manager

Para criar um pool de sessões de contêiner personalizado 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 com os seguintes comandos:

az upgrade
az extension add --name containerapp --upgrade --allow-preview true -y

Os pools de sessão de contêiner personalizados exigem um perfil de carga de trabalho habilitado para o ambiente de Aplicativos de Contêiner do Azure. Se você não tiver um ambiente, use o az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles comando para criar um.

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

O exemplo a seguir cria um pool de sessões 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 para o pool de sessões e o 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>

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

Parâmetro	valor	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 ID do recurso do ambiente do aplicativo contêiner.
`--container-type`	`CustomContainer`	O tipo de contêiner do pool de sessões. 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ões.
`--registry-server`	`myregistry.azurecr.io`	O nome do host do servidor de registro de contêiner.
`--registry-username`	`my-username`	O nome de usuário para efetuar login no registro de contêiner.
`--registry-password`	`my-password`	A senha para fazer login no registro do 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 que a sessão seja encerrada. O período ocioso é redefinido cada vez que a API da sessão é chamada. O valor deve estar entre `300` e `3600`.
`--network-status`	Designa se o tráfego de rede de saída é permitido a partir da 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ões o tempo todo. Aumente esse número se as sessões forem alocadas mais rapidamente do que o pool está sendo 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ões.

Para verificar o status do 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

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

Para criar um pool de sessões de contêiner personalizado usando o Gerenciador de Recursos do Azure, crie um recurso de pool de sessão com o tipo de Microsoft.ContainerApps/sessionPools recurso. O exemplo a seguir mostra um trecho de modelo ARM que cria um pool de sessões de contêiner personalizado.

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

{
  "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
    },
    "secrets": [
      {
        "name": "registrypassword",
        "value": "<REGISTRY_PASSWORD>"
      }
    ],
    "customContainerTemplate": {
      "registryCredentials": {
          "server": "myregistry.azurecr.io",
          "username": "myregistry",
          "passwordSecretRef": "registrypassword"
      },
      "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"
    }
  }
}

Este modelo cria um pool de sessões com as seguintes configurações:

Parâmetro	valor	Description
`name`	`my-session-pool`	O nome do pool de sessões.
`location`	`westus2`	O local do pool de sessões.
`environmentId`	`/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>`	A ID do recurso do ambiente do aplicativo contêiner.
`poolManagementType`	`Dynamic`	Deve ser `Dynamic` para sessões de contêiner personalizadas.
`containerType`	`CustomContainer`	O tipo de contêiner do pool de sessões. Deve ser `CustomContainer` para sessões de contêiner personalizadas.
`scaleConfiguration.maxConcurrentSessions`	`10`	O número máximo de sessões que podem ser alocadas ao mesmo tempo.
`scaleConfiguration.readySessionInstances`	`5`	O número de sessões de destino que estão prontas no pool de sessões o tempo todo. Aumente esse número se as sessões forem alocadas mais rapidamente do que o pool está sendo reabastecido.
`dynamicPoolConfiguration.executionType`	`Timed`	O tipo de execução para o pool de sessões. Deve ser `Timed` para sessões de contêiner personalizadas.
`dynamicPoolConfiguration.cooldownPeriodInSeconds`	`600`	O número de segundos que uma sessão pode ficar ociosa antes que a sessão seja encerrada. O período ocioso é redefinido cada vez que a API da sessão é chamada. O valor deve estar entre `300` e `3600`.
`secrets`	`[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]`	Uma lista de segredos.
`customContainerTemplate.registryCredentials.server`	`myregistry.azurecr.io`	O nome do host do servidor de registro de contêiner.
`customContainerTemplate.registryCredentials.username`	`myregistry`	O nome de usuário para efetuar login no registro de contêiner.
`customContainerTemplate.registryCredentials.passwordSecretRef`	`registrypassword`	O nome do segredo que contém a senha para efetuar login no registro do contêiner.
`customContainerTemplate.containers[0].image`	`myregistry.azurecr.io/my-container-image:1.0`	A imagem de contêiner a ser usada para o pool de sessões.
`customContainerTemplate.containers[0].name`	`mycontainer`	O nome do contêiner.
`customContainerTemplate.containers[0].resources.cpu`	`0.25`	A CPU necessária em núcleos.
`customContainerTemplate.containers[0].resources.memory`	`0.5Gi`	A memória necessária.
`customContainerTemplate.containers[0].env`	Matriz de pares nome-valor	As variáveis de ambiente a serem definidas no contêiner.
`customContainerTemplate.containers[0].command`	`["/bin/sh"]`	O comando a ser executado no contêiner.
`customContainerTemplate.containers[0].args`	`["-c", "while true; do echo hello; sleep 10;done"]`	Os argumentos a serem passados para o comando.
`customContainerTemplate.containers[0].ingress.targetPort`	`80`	A porta de sessão usada para o tráfego de entrada.
`sessionNetworkConfiguration.status`	`EgressDisabled`	Designa se o tráfego de rede de saída é permitido a partir da sessão. Os valores válidos são `EgressDisabled` (padrão) e `EgressEnabled`.

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 é mal-intencionado e tem acesso total ao contêiner, incluindo suas variáveis de ambiente, segredos e arquivos.

Cache de imagens

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

Quaisquer 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 tag exclusiva para cada atualização de imagem para garantir que a nova imagem seja puxada.

Trabalhar com sessões

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 para sessões de contêiner personalizadas segue este formato: https://<SESSION_POOL>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io.

Para recuperar o ponto de extremidade de gerenciamento do 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

Todas as solicitações para o ponto de extremidade de gerenciamento de pool devem incluir um Authorization cabeçalho 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. Esse ID de sessão exclusivo permite que seu aplicativo interaja com sessões específicas. Para saber mais sobre identificadores de sessão, consulte Identificadores de sessão.

Importante

O identificador de sessão é uma informação confidencial que requer 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 às suas próprias sessões. A falha em proteger o 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

Encaminhando solicitações para o contêiner da sessã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 da sessão:

Pode continuar a fazer pedidos para a mesma sessão. Se não houver solicitações para a sessão por mais tempo do que o período de resfriamento, a sessão será excluída automaticamente.

Pedido de amostra

O exemplo a seguir mostra uma solicitação para uma sessão de contêiner personalizada por um ID de usuário.

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

POST https://<SESSION_POOL_NAME>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io/<API_PATH_EXPOSED_BY_CONTAINER>?identifier=<USER_ID>
Authorization: Bearer <TOKEN>
{
  "command": "echo 'Hello, world!'"
}

Essa solicitação é encaminhada para a sessão de contêiner personalizada 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 uma sessão do pool antes de encaminhar a solicitação.

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

Usando identidade gerenciada

Uma identidade gerenciada do Microsoft Entra ID permite que seus pools de sessões de contêiner personalizados e suas sessões acessem outros recursos protegidos pelo Microsoft Entra. Para obter mais informações sobre identidades gerenciadas no Microsoft Entra ID, consulte Identidades gerenciadas para recursos do Azure.

Você pode habilitar identidades gerenciadas para seus pools de sessões de contêiner personalizados. Há suporte para identidades gerenciadas atribuídas pelo sistema e pelo usuário.

Há duas maneiras de usar identidades gerenciadas com pools de sessão 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 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 Entra para a identidade gerenciada do pool. Como as sessões geralmente executam código não confiável, use esse recurso com cuidado.

CLI do Azure
Azure Resource Manager

Para habilitar a identidade gerenciada para um pool de sessões de contêiner personalizado, use o Gerenciador de Recursos do Azure.

Para habilitar a identidade gerenciada para um pool de sessões de contêiner personalizado, adicione uma identity propriedade ao recurso do pool de sessões. A identity propriedade deve ter uma type propriedade com o valor SystemAssigned ou UserAssigned. Para obter detalhes sobre como configurar essa propriedade, consulte Configurar identidades gerenciadas.

O exemplo a seguir mostra um trecho de modelo ARM que habilita uma identidade atribuída pelo usuário para um pool de sessões de contêiner personalizado e a usa para autenticação de recebimento de imagem. Antes de enviar a solicitação, substitua os espaços reservados entre <> os colchetes pelos valores apropriados para o pool de sessões e o identificador de sessão.

{
  "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>": {}
    }
  }
}

Este modelo contém as seguintes configurações adicionais para identidade gerenciada:

Parâmetro	valor	Description
`customContainerTemplate.registryCredentials.identity`	`<IDENTITY_RESOURCE_ID>`	O ID do recurso da identidade gerenciada a ser usada para autenticação de recebimento de imagem.
`managedIdentitySettings.identity`	`<IDENTITY_RESOURCE_ID>`	A ID do recurso da identidade gerenciada a ser usada na sessão.
`managedIdentitySettings.lifecycle`	`None`	O ciclo de vida da sessão em que a identidade gerenciada está disponível. - `None` (padrão): a sessão não pode acessar a identidade. É usado apenas para extração de imagem. - `Main`: Além do pull de imagem, a sessão principal também pode acessar a identidade. Use com cuidado.

Registo

Os logs de console de sessões de contêiner personalizadas 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.

Faturação

As sessões de contêiner personalizadas são cobradas com base nos recursos consumidos pelo pool de sessões. Para obter mais informações, consulte Cobrança de aplicativos de contêiner do Azure.

Próximos passos

Visão geral das sessões dinâmicas dos Aplicativos de Contêiner do Azure

Partilhar via