Azure Container Apps 사용자 지정 컨테이너 세션

아티클
11/07/2024

Azure Container Apps 동적 세션이 제공하는 기본 제공 코드 인터프리터 외에도 사용자 지정 컨테이너를 사용하여 고유한 세션 샌드박스를 정의할 수도 있습니다.

사용자 지정 컨테이너 세션에 사용

사용자 지정 컨테이너를 사용하면 필요에 맞는 솔루션을 빌드할 수 있습니다. 이를 통해 빠르고 일시적이며 Hyper-V를 통해 안전한 샌드박스 공간을 제공하는 환경에서 코드나 애플리케이션을 실행할 수 있습니다. 또한 선택적 네트워크 격리를 사용하여 구성할 수도 있습니다. 일부 사례:

코드 인터프리터: 기본 제공된 인터프리터에서 지원되지 않는 언어로 보안 샌드박스에서 신뢰할 수 없는 코드를 실행해야 하거나 코드 인터프리터 환경을 완전히 제어해야 하는 경우.
격리 실행: 각 테넌트 또는 사용자가 자체 샌드박스 환경을 갖고 있는 적대적인 다중 테넌트 시나리오에서 애플리케이션을 실행해야 하는 경우. 이러한 환경은 서로 격리되어 있으며 호스트 애플리케이션과도 격리되어 있습니다. 일부 예로는 사용자 제공 코드를 실행하는 애플리케이션, 클라우드 기반 셸에 대한 최종 사용자 액세스 권한을 부여하는 코드, AI 에이전트 및 개발 환경이 포함됩니다.

사용자 지정 컨테이너 세션 사용

사용자 지정 컨테이너 세션을 사용하려면 먼저 사용자 지정 컨테이너 이미지를 사용하여 세션 풀을 만듭니다. Azure Container Apps는 제공된 이미지를 사용하여 자체 Hyper-V 샌드박스에서 컨테이너를 자동으로 시작합니다. 컨테이너가 시작되면 세션 풀에서 사용할 수 있습니다.

애플리케이션이 세션을 요청하면 인스턴스가 풀에서 즉시 할당됩니다. 세션은 유휴 상태가 될 때까지 활성 상태로 유지되며 유휴 상태는 자동으로 중지되고 제거됩니다.

사용자 지정 컨테이너 세션 풀 만들기

사용자 지정 컨테이너 세션 풀을 만들려면 컨테이너 이미지와 풀 구성 설정을 제공해야 합니다.

HTTP 요청을 사용하여 각 세션을 호출하거나 세션과 통신합니다. 사용자 지정 컨테이너는 이러한 요청에 응답하기 위해 지정한 포트에 HTTP 서버를 노출해야 합니다.

Azure CLI
Azure Resource Manager

Azure CLI를 사용하여 사용자 지정 컨테이너 세션 풀을 만들려면 다음 명령을 사용하여 최신 버전의 Azure CLI와 Azure Container Apps 확장이 있는지 확인합니다.

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

사용자 지정 컨테이너 세션 풀에는 워크로드 프로필이 지원되는 Azure Container Apps 환경이 필요합니다. 환경이 없으면 az containerapp env create -n <ENVIRONMENT_NAME> -g <RESOURCE_GROUP> --location <LOCATION> --enable-workload-profiles 명령을 사용하여 환경을 만듭니다.

사용자 지정 컨테이너 세션 풀을 만들려면 az containerapp sessionpool create 명령을 사용합니다.

다음 예에서는 사용자 지정 컨테이너 이미지 myregistry.azurecr.io/my-container-image:1.0을 사용하여 my-session-pool이라는 세션 풀을 만듭니다.

요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 세션 풀 및 세션 식별자에 대한 적절한 값으로 바꿉니다.

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>

이 명령은 다음 설정을 사용하여 세션 풀을 만듭니다.

매개 변수	값	설명
`--name`	`my-session-pool`	세션 풀의 이름입니다.
`--resource-group`	`my-resource-group`	세션 풀을 포함하는 리소스 그룹입니다.
`--environment`	`my-environment`	컨테이너 앱 환경의 이름 또는 리소스 ID입니다.
`--container-type`	`CustomContainer`	세션 풀의 컨테이너 형식입니다. 사용자 지정 컨테이너 세션의 경우 `CustomContainer`여야 합니다.
`--image`	`myregistry.azurecr.io/my-container-image:1.0`	세션 풀에 사용할 컨테이너 이미지입니다.
`--registry-server`	`myregistry.azurecr.io`	컨테이너 레지스트리 서버 호스트 이름입니다.
`--registry-username`	`my-username`	컨테이너 레지스트리에 로그인하기 위한 사용자 이름입니다.
`--registry-password`	`my-password`	컨테이너 레지스트리에 로그인하기 위한 암호입니다.
`--cpu`	`0.25`	코어에 필요한 CPU입니다.
`--memory`	`0.5Gi`	필요한 메모리입니다.
`--target-port`	`80`	수신 트래픽에 사용되는 세션 포트입니다.
`--cooldown-period`	`300`	세션이 종료되기 전에 세션이 유휴 상태일 수 있는 시간(초)입니다. 유휴 기간은 세션의 API가 호출될 때마다 다시 설정됩니다. 값은 `300`에서 `3600` 사이여야 합니다.
`--network-status`	세션에서 아웃바운드 네트워크 트래픽이 허용되는지 여부를 지정합니다. 유효한 값은 `EgressDisabled`(기본값)와 `EgressEnabled`입니다.
`--max-sessions`	`10`	동시에 할당할 수 있는 최대 세션 수입니다.
`--ready-sessions`	`5`	세션 풀에 항상 준비되어 있는 대상 세션 수입니다. 풀이 보충되는 것보다 세션이 더 빨리 할당되는 경우 이 숫자를 늘립니다.
`--env-vars`	`"key1=value1" "key2=value2"`	컨테이너에 설정할 환경 변수입니다.
`--location`	`"Supported Location"`	세션 풀의 위치입니다.

세션 풀의 상태를 확인하려면 다음 명령을 사용합니다 az containerapp sessionpool show .

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

세션 풀을 업데이트하려면 az containerapp sessionpool update 명령을 사용합니다.

Azure Resource Manager를 사용하여 사용자 지정 컨테이너 세션 풀을 만들려면 Microsoft.ContainerApps/sessionPools 리소스 종류를 사용하여 세션 풀 리소스를 만듭니다. 다음 예에서는 사용자 지정 컨테이너 세션 풀을 만드는 ARM 템플릿 코드 조각을 보여 줍니다.

요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 세션 풀 및 세션 식별자에 대한 적절한 값으로 바꿉니다.

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

이 템플릿은 다음 설정으로 세션 풀을 만듭니다.

매개 변수	값	설명
`name`	`my-session-pool`	세션 풀의 이름입니다.
`location`	`westus2`	세션 풀의 위치입니다.
`environmentId`	`/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.ContainerApps/environments/<ENVIRONMENT_NAME>`	컨테이너 앱 환경의 리소스 ID입니다.
`poolManagementType`	`Dynamic`	사용자 지정 컨테이너 세션의 경우 `Dynamic`여야 합니다.
`containerType`	`CustomContainer`	세션 풀의 컨테이너 형식입니다. 사용자 지정 컨테이너 세션의 경우 `CustomContainer`여야 합니다.
`scaleConfiguration.maxConcurrentSessions`	`10`	동시에 할당할 수 있는 최대 세션 수입니다.
`scaleConfiguration.readySessionInstances`	`5`	세션 풀에 항상 준비되어 있는 대상 세션 수입니다. 풀이 보충되는 것보다 세션이 더 빨리 할당되는 경우 이 숫자를 늘립니다.
`dynamicPoolConfiguration.executionType`	`Timed`	세션 풀의 실행 형식입니다. 사용자 지정 컨테이너 세션의 경우 `Timed`여야 합니다.
`dynamicPoolConfiguration.cooldownPeriodInSeconds`	`600`	세션이 종료되기 전에 세션이 유휴 상태일 수 있는 시간(초)입니다. 유휴 기간은 세션의 API가 호출될 때마다 다시 설정됩니다. 값은 `300`에서 `3600` 사이여야 합니다.
`secrets`	`[{ "name": "registrypassword", "value": "<REGISTRY_PASSWORD>" }]`	비밀 목록입니다.
`customContainerTemplate.registryCredentials.server`	`myregistry.azurecr.io`	컨테이너 레지스트리 서버 호스트 이름입니다.
`customContainerTemplate.registryCredentials.username`	`myregistry`	컨테이너 레지스트리에 로그인하기 위한 사용자 이름입니다.
`customContainerTemplate.registryCredentials.passwordSecretRef`	`registrypassword`	컨테이너 레지스트리에 로그인할 암호를 포함하는 비밀의 이름입니다.
`customContainerTemplate.containers[0].image`	`myregistry.azurecr.io/my-container-image:1.0`	세션 풀에 사용할 컨테이너 이미지입니다.
`customContainerTemplate.containers[0].name`	`mycontainer`	컨테이너의 이름입니다.
`customContainerTemplate.containers[0].resources.cpu`	`0.25`	코어에 필요한 CPU입니다.
`customContainerTemplate.containers[0].resources.memory`	`0.5Gi`	필요한 메모리입니다.
`customContainerTemplate.containers[0].env`	이름 값 쌍의 배열	컨테이너에 설정할 환경 변수입니다.
`customContainerTemplate.containers[0].command`	`["/bin/sh"]`	컨테이너에서 실행할 명령입니다.
`customContainerTemplate.containers[0].args`	`["-c", "while true; do echo hello; sleep 10;done"]`	명령에 전달할 인수입니다.
`customContainerTemplate.containers[0].ingress.targetPort`	`80`	수신 트래픽에 사용되는 세션 포트입니다.
`sessionNetworkConfiguration.status`	`EgressDisabled`	세션에서 아웃바운드 네트워크 트래픽이 허용되는지 여부를 지정합니다. 유효한 값은 `EgressDisabled`(기본값)와 `EgressEnabled`입니다.

Important

신뢰할 수 없는 코드를 실행하는 데 세션이 사용되는 경우 신뢰할 수 없는 코드가 액세스하지 못하게 하려는 정보나 데이터를 포함하지 마세요. 코드가 악의적이고 환경 변수, 비밀 및 파일을 포함하여 컨테이너에 대한 모든 권한을 가지고 있다고 가정합니다.

이미지 캐싱

세션 풀을 만들거나 업데이트하면 Azure Container Apps는 풀의 컨테이너 이미지를 캐시합니다. 이 캐싱은 새 세션을 만드는 프로세스를 가속화하는 데 도움이 됩니다.

이미지에 대한 변경 내용은 세션에 자동으로 반영되지 않습니다. 이미지를 업데이트하려면 세션 풀을 새 이미지 태그로 업데이트합니다. 각 이미지 업데이트에 고유한 태그를 사용하여 새 이미지를 끌어옵니다.

세션 작업

애플리케이션은 세션 풀의 관리 API를 사용하여 세션과 상호 작용합니다.

사용자 지정 컨테이너 세션의 풀 관리 엔드포인트는 https://<SESSION_POOL>.<ENVIRONMENT_ID>.<REGION>.azurecontainerapps.io 형식을 따릅니다.

세션 풀의 관리 엔드포인트를 검색하려면 az containerapp sessionpool show 명령을 사용합니다.

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

풀 관리 엔드포인트에 대한 모든 요청에는 전달자 토큰이 있는 Authorization 헤더가 포함되어야 합니다. 풀 관리 API로 인증하는 방법을 알아보려면 인증을 참조하세요.

각 API 요청에는 세션 ID와 함께 identifier 쿼리 문자열 매개 변수도 포함되어야 합니다. 이 고유한 세션 ID를 사용하면 애플리케이션이 특정 세션과 상호 작용할 수 있습니다. 세션 식별자에 대해 자세히 알아보려면 세션 식별자를 참조하세요.

Important

세션 식별자는 해당 값을 만들고 관리할 때 보안 프로세스가 필요한 중요한 정보입니다. 이 값을 보호하려면 애플리케이션에서 각 사용자 또는 테넌트가 자신의 세션에만 액세스할 수 있도록 해야 합니다. 세션에 대한 액세스를 보호하지 못하면 사용자의 세션에 저장된 데이터에 대한 오용 또는 무단 액세스가 발생할 수 있습니다. 자세한 내용은 세션 식별자를 참조하세요.

세션의 컨테이너에 요청 전달:

기본 풀 관리 엔드포인트 다음에 있는 경로의 모든 항목은 세션의 컨테이너로 전달됩니다.

예를 들어 <POOL_MANAGEMENT_ENDPOINT>/api/uploadfile을 호출하는 경우 요청은 0.0.0.0:<TARGET_PORT>/api/uploadfile의 세션 컨테이너로 라우팅됩니다.

연속 세션 상호 작용:

동일한 세션에 대한 요청을 계속할 수 있습니다. 휴지 기간보다 오랫동안 세션에 대한 요청이 없으면 세션이 자동으로 삭제됩니다.

샘플 요청

다음 예에서는 사용자 ID로 사용자 지정 컨테이너 세션에 대한 요청을 보여 줍니다.

요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 요청과 관련된 값으로 바꿉니다.

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

이 요청은 사용자 ID의 식별자와 함께 사용자 지정 컨테이너 세션으로 전달됩니다. 세션이 아직 실행되고 있지 않으면 Azure Container Apps는 요청을 전달하기 전에 풀에서 세션을 할당합니다.

예에서 세션 컨테이너는 http://0.0.0.0:<INGRESS_PORT>/<API_PATH_EXPOSED_BY_CONTAINER>에서 요청을 받습니다.

관리 ID 사용

Microsoft Entra ID의 관리 ID를 사용하면 사용자 지정 컨테이너 세션 풀 및 해당 세션이 다른 Microsoft Entra로 보호된 리소스에 액세스할 수 있습니다. Microsoft Entra ID의 관리 ID에 대한 자세한 내용은 Azure 리소스의 관리 ID를 참조하세요.

사용자 지정 컨테이너 세션 풀에 대해 관리 ID를 사용하도록 설정할 수 있습니다. 시스템 할당 및 사용자 할당 관리 ID가 모두 지원됩니다.

사용자 지정 컨테이너 세션 풀에서 관리 ID를 사용하는 방법에는 두 가지가 있습니다.

이미지 끌어오기 인증: 관리 ID를 사용하여 컨테이너 레지스트리를 사용하여 인증하여 컨테이너 이미지를 끌어오세요.
리소스 액세스: 세션에서 세션 풀의 관리 ID를 사용하여 다른 Microsoft Entra로 보호된 리소스에 액세스합니다. 보안에 미치는 영향으로 인해 이 기능은 기본적으로 사용하지 않도록 설정됩니다.

Important

세션에서 관리 ID에 대한 액세스를 사용하도록 설정하면 세션에서 실행되는 모든 코드 또는 프로그램에서 풀의 관리 ID에 대한 Entra 토큰을 만들 수 있습니다. 세션은 일반적으로 신뢰할 수 없는 코드를 실행하므로 주의해서 이 기능을 사용합니다.

Azure CLI
Azure Resource Manager

사용자 지정 컨테이너 세션 풀에 대한 관리 ID를 사용하도록 설정하려면 Azure Resource Manager를 사용합니다.

사용자 지정 컨테이너 세션 풀에 대한 관리 ID를 사용하도록 설정하려면 세션 풀 리소스에 속성을 추가 identity 합니다. 속성에 identity 값 SystemAssigned 또는 UserAssigned.가 있는 type 속성이 있어야 합니다. 이 속성을 구성하는 방법에 대한 자세한 내용은 관리 ID 구성을 참조 하세요.

다음 예제에서는 사용자 지정 컨테이너 세션 풀에 대해 사용자 할당 ID를 사용하도록 설정하고 이미지 끌어오기 인증에 사용하는 ARM 템플릿 코드 조각을 보여 줍니다. 요청을 보내기 전에 <> 대괄호 사이의 자리 표시자를 세션 풀 및 세션 식별자에 대한 적절한 값으로 바꿉니다.

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

이 템플릿에는 관리 ID에 대한 다음과 같은 추가 설정이 포함되어 있습니다.

매개 변수	값	설명
`customContainerTemplate.registryCredentials.identity`	`<IDENTITY_RESOURCE_ID>`	이미지 끌어오기 인증에 사용할 관리 ID의 리소스 ID입니다.
`managedIdentitySettings.identity`	`<IDENTITY_RESOURCE_ID>`	세션에서 사용할 관리 ID의 리소스 ID입니다.
`managedIdentitySettings.lifecycle`	`None`	관리 ID를 사용할 수 있는 세션 수명 주기입니다. - `None` (기본값): 세션에서 ID에 액세스할 수 없습니다. 이미지 풀에만 사용됩니다. - `Main`: 이미지 끌어오기 외에도 주 세션에서 ID에 액세스할 수도 있습니다. 주의해서 사용하세요.

로깅

사용자 지정 컨테이너 세션의 콘솔 로그는 Azure Container Apps 환경과 연결된 Azure Log Analytics 작업 영역에서 이름이 지정된 AppEnvSessionConsoleLogs_CL테이블에서 사용할 수 있습니다.

결제

사용자 지정 컨테이너 세션은 세션 풀에서 사용하는 리소스에 따라 요금이 청구됩니다. 자세한 내용은 Azure Container Apps 청구를 참조 하세요.

다음 단계

Azure Container Apps 동적 세션 개요

다음을 통해 공유