자습서: Azure Container Apps를 사용하여 세션 풀에서 셸 명령 실행(미리 보기)

이 자습서에서는 Azure Container Apps에서 셸 세션 풀을 배포하고 동적 세션 API 및 ARM 템플릿을 사용하여 셸 명령을 실행하는 방법을 보여 줍니다.

이 자습서에서 수행하는 작업은 다음과 같습니다.

필수 조건

이 자습서를 시작하기 전에 다음 리소스가 필요합니다.

설치 프로그램

먼저 최신 업데이트로 Azure CLI를 준비하고 Azure에 로그인합니다.

1. Azure CLI를 최신 버전으로 업데이트합니다.

   az upgrade
   

2. Microsoft.App 리소스 공급자를 등록합니다.

   az provider register --namespace Microsoft.App
   

3. 최신 버전의 Azure Container Apps CLI 확장을 설치합니다.

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

4. Azure에 로그인합니다.

   az login
   

5. Azure 구독 ID를 쿼리하고 값을 변수로 설정합니다.

   SUBSCRIPTION_ID=$(az account show --query id --output tsv)
   

6. 이 프로시저에서 사용되는 변수를 설정합니다.

   다음 명령을 실행하기 전에 <>(으)로 둘러싸인 자리 표시자를 사용자 고유의 값으로 바꿔야 합니다.

   RESOURCE_GROUP=<RESOURCE_GROUP_NAME>
   SESSION_POOL_NAME=<SESSION_POOL_NAME>
   LOCATION=<LOCATION>
   API_VERSION="2025-10-02-preview"
   

   이러한 변수를 사용하여 다음 단계에서 리소스를 만듭니다.

7. 리소스 그룹을 만드는 데 사용할 구독을 설정합니다.

   az account set -s $SUBSCRIPTION_ID
   

8. 리소스 그룹을 만듭니다.

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

ARM 템플릿 만들기

셸 세션 풀을 정의하기 위해 명명된 deploy.json ARM 템플릿 파일을 만듭니다.

{
    "$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"
                }
            }
        }
    ]
}

셸 세션 풀 배포

ARM 템플릿을 사용하여 셸 세션 풀을 배포합니다.

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

관리 ID 할당

세션 풀에 대한 API 호출을 인증하는 데 사용할 사용자 할당 관리 ID를 만듭니다.

1. ID 이름 및 풀 리소스 ID를 설정합니다.

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

2. 사용자가 할당한 관리 ID를 만듭니다.

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

3. 관리 ID의 주체 ID를 가져옵니다.

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

Azure Container App에 관리 ID 할당

Azure Container App을 만들거나 업데이트할 때 사용자 할당 관리 ID를 앱에 할당합니다. 다음은 그 예입니다.

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

자세한 내용은 컨테이너 앱에 관리 ID 할당을 참조하세요.

세션 실행 API에 대한 역할 할당 설정

세션 풀의 API와 상호 작용하려면 관리 ID에 Azure ContainerApps Session Executor 역할을 할당해야 합니다.

ID 전파를 기다린 다음 관리 ID에 역할을 할당합니다.

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

전달자 토큰 가져오기

세션 풀의 API에 액세스하려면 액세스 토큰이 필요합니다. 메서드는 코드를 실행하는 위치에 따라 달라집니다.

Azure Container App 내부에서

사용자 할당 관리 ID가 할당된 Azure Container App 내에서 실행하는 경우 IMDS(Azure Instance Metadata Service)를 사용하여 액세스 토큰을 가져옵니다.

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')

이 명령은 access_token를 사용하여 토큰을 검색하고 JSON 응답에서 jq 값을 추출합니다.

로컬 테스트 및 개발용

로컬 또는 개발 환경에서 테스트할 때 Azure CLI를 사용하여 액세스 토큰을 가져올 수 있습니다(적절한 권한이 있어야 합니다).

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

세션에서 셸 명령 실행

보안 컨텍스트를 설정하는 전달자 토큰이 있으므로 세션 풀에 요청을 보내 셸 명령을 실행할 수 있습니다.

1. API 호출에 대한 요청 본문을 만듭니다.

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

2. API 엔드포인트 URL을 생성합니다.

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

3. 셸 명령을 실행합니다.

   Azure Container App 또는 로컬 테스트 내에서 다음을 수행합니다.

   curl --request POST --url "$URL" --header "Authorization: Bearer $ACCESS_TOKEN" --header 'content-type: application/json' --data "$BODY"
   

   셸 명령(hello world 및 hi)의 출력을 포함하여 실행 결과가 포함된 JSON 응답을 받아야 합니다.

배포를 확인하십시오

다음 명령을 사용하여 리소스가 성공적으로 생성되었는지 확인할 수 있습니다.

1. 세션 풀 배포를 확인합니다.

   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}'
   

2. 역할 할당을 확인합니다.

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

자원을 정리하세요

이 자습서에서 만든 리소스는 Azure 청구서에 영향을 줍니다. 이러한 서비스를 장기간 사용하지 않을 예정이면 다음 명령을 실행하여 이 자습서에서 만든 모든 항목을 제거합니다.

az group delete --resource-group $RESOURCE_GROUP

다음 단계

• Azure Container Apps 세션에 대해 자세히 알아보기
• 동적 세션 API 샘플 살펴보기
• 세션 풀 관리 이해