Tutorial: Executar comandos do shell em um pool de sessões usando aplicativos de contêiner do Azure (versão prévia)

Este tutorial demonstra como implantar um pool de sessões de shell nos Aplicativos de Contêiner do Azure e executar comandos de shell usando a API de Sessões Dinâmicas e modelos do ARM.

Neste tutorial, você:

Implantar um pool de sessões do shell usando modelos do ARM
Criar uma identidade gerenciada atribuída pelo usuário com permissões apropriadas
Executar comandos de shell por meio da API de Sessões Dinâmicas

Pré-requisitos

Você precisa dos recursos a seguir antes de começar este tutorial.

Requirement	Description
Conta do Azure	Você precisa de uma conta do Azure com uma assinatura ativa. Se você não tiver uma conta, é possível criar uma gratuitamente.
CLI do Azure	Instale a CLI do Azure.

Configuração

Comece preparando a CLI do Azure com as atualizações mais recentes e entrando no Azure.

Atualize a CLI do Azure para a versão mais recente.
```
az upgrade
```

Registre o provedor de recursos Microsoft.App.

az provider register --namespace Microsoft.App

Instale a última versão da extensão da CLI dos Aplicativos de Contêiner do Azure.
```
az extension add --name containerapp --allow-preview true --upgrade
```
Inicie sessão no Azure.
```
az login
```
Consulte sua ID de assinatura do Azure e defina o valor como uma variável.
```
SUBSCRIPTION_ID=$(az account show --query id --output tsv)
```
Defina as variáveis usadas nesse procedimento.

Antes de executar o comando a seguir, substitua os espaços reservados cercados por <> por seus próprios valores.
```
RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
SESSION_POOL_NAME=<SESSION_POOL_NAME>
LOCATION=<LOCATION>
API_VERSION="2025-10-02-preview"
```
Use essas variáveis para criar os recursos nas etapas a seguir.
Defina a assinatura que você deseja usar para criar o grupo de recursos.
```
az account set -s $SUBSCRIPTION_ID
```

Crie um grupo de recursos.

az group create --name $RESOURCE_GROUP --location $LOCATION

Criar um modelo do ARM

Crie um arquivo de modelo ARM nomeado deploy.json para definir o pool de sessão do shell.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "resources": [
      {
         "apiVersion": "2025-10-02-preview",
            "name": "myshellpool",
            "type": "Microsoft.App/sessionpools",
            "location": "North Central US",
            "properties": {
                "poolManagementType": "Dynamic",
                "containerType": "Shell", # Set the "containerType" property to "Shell"
                "scaleConfiguration": {
                    "maxConcurrentSessions": 5
                },
                "dynamicPoolConfiguration": {
                    "lifecycleConfiguration": {
                        "lifecycleType": "Timed",
                        "cooldownPeriodInSeconds": 300
                    }
                },
                "sessionNetworkConfiguration": {
                    "status": "EgressEnabled"
                }
            }
        }
    ]
}

Implantar o pool de sessões do shell

Utilize o modelo ARM para implantar o pool de sessão do shell.

az deployment group create --resource-group $RESOURCE_GROUP --template-file deploy.json

Atribuir uma identidade gerenciada

Crie uma identidade gerenciada atribuída pelo usuário que será usada para autenticar chamadas à API no pool de sessões.

Defina o nome da identidade e a ID do recurso do pool.

UAMI_NAME=${SESSION_POOL_NAME}-uami
POOL_ID="/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME"

Crie a identidade gerenciada atribuída pelo usuário.

az identity create --resource-group $RESOURCE_GROUP --name $UAMI_NAME --location $LOCATION

Obtenha o ID principal da identidade gerenciada.

UAMI_PRINCIPAL=$(az identity show --resource-group $RESOURCE_GROUP --name $UAMI_NAME --query principalId -o tsv)

Atribuir a identidade gerenciada ao aplicativo de contêiner do Azure

Ao criar ou atualizar seu Aplicativo de Contêiner do Azure, atribua a identidade gerenciada atribuída pelo usuário ao aplicativo. Por exemplo:

az containerapp update \
  --name <CONTAINER_APP_NAME> \
  --resource-group $RESOURCE_GROUP \
  --user-assigned $UAMI_NAME

Consulte Atribuir uma identidade gerenciada a um aplicativo de contêiner para obter mais detalhes.

Definir atribuições de função para APIs de execução de sessão

Para interagir com a API do pool de sessão, você deve atribuir a Azure ContainerApps Session Executor função à sua identidade gerenciada.

Aguarde a propagação de identidade e atribua a função à identidade gerenciada.

az role assignment create --assignee $UAMI_PRINCIPAL --role "Azure ContainerApps Session Executor" --scope $POOL_ID

Obter um token de portador

Para acessar a API do pool de sessão, você precisa de um token de acesso. O método depende de onde você está executando o código:

De dentro de seu Aplicativo de Contêiner do Azure

Ao executar de dentro de um Aplicativo de Contêiner do Azure que possui a identidade gerenciada atribuída pelo usuário, obtenha um token de acesso usando o Serviço de Metadados da Instância do Azure (IMDS):

ACCESS_TOKEN=$(curl -s -H "Metadata: true" \
  "http://169.254.169.254/metadata/identity/oauth2/token?api-version=2018-02-01&resource=https://dynamicsessions.io" \
  | jq -r '.access_token')

Esse comando recupera o token e extrai o access_token valor da resposta JSON usando jq.

Para teste e desenvolvimento local

Ao testar localmente ou em seu ambiente de desenvolvimento, você pode obter um token de acesso usando a CLI do Azure (você deve ter as permissões apropriadas):

ACCESS_TOKEN=$(az account get-access-token --resource "https://dynamicsessions.io" --query accessToken --output tsv)

Observação

Para que o teste local funcione, sua sessão da CLI do Azure deve ser autenticada como um usuário ou entidade de serviço que tenha a função "Executor de Sessão do Azure ContainerApps" atribuída ao pool de sessões. A abordagem de identidade gerenciada é recomendada para cenários de produção.

Executar comandos de shell em sua sessão

Agora que você tem um token de portador para estabelecer o contexto de segurança, você pode enviar uma solicitação para o pool de sessões para executar comandos de shell.

Crie o corpo da solicitação para a chamada à API.

EXEC_ID=$(uuidgen)
BODY=$(cat <<EOF
 {
   "codeInputType": "inline",
   "executionType": "synchronous",
   "shellCommand": "echo Hello world!",
   "timeoutInSeconds": 600
 }
 EOF
 )

Construa a URL do endpoint da API.

URL="https://$LOCATION.dynamicsessions.io/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/sessionPools/$SESSION_POOL_NAME/executions?api-version=$API_VERSION&identifier=$EXEC_ID"

Execute os comandos do shell.

De dentro do Aplicativo de Contêiner do Azure ou teste local:
```
curl --request POST --url "$URL" --header "Authorization: Bearer $ACCESS_TOKEN" --header 'content-type: application/json' --data "$BODY"
```
Você deve receber uma resposta JSON contendo os resultados da execução, incluindo a saída dos comandos do shell (hello world e hi).

Verificar sua implantação

Você pode verificar se seus recursos foram criados com êxito usando estes comandos:

Verifique a implantação do pool de sessões.

az resource show --ids "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --query '{name:name, location:location, provisioningState:properties.provisioningState}'

Verifique a atribuição de função.

az role assignment list --scope "/subscriptions/$SUBSCRIPTION_ID/resourceGroups/$RESOURCE_GROUP/providers/Microsoft.App/sessionpools/$SESSION_POOL_NAME" --output table

Limpar os recursos

Os recursos criados neste tutorial têm um efeito na sua fatura do Azure. Se você não usar esses serviços a longo prazo, execute o comando a seguir para remover tudo o que foi criado neste tutorial.

az group delete --resource-group $RESOURCE_GROUP

Próximas etapas

Comentários

Esta página foi útil?

Last updated on 2025-11-19