샌드박스 관리

이 페이지에서는 Python SDK를 사용하여 샌드박스 환경의 수명 주기를 관리하는 방법을 보여줍니다. 기존 샌드박스를 나열하고, 세부정보를 확인하고, 일시중지 및 재개하거나, 더 이상 필요하지 않은 경우 삭제할 수 있습니다.

시작하기 전에

샌드박스를 관리하려면 프로젝트에 다음 역할이 필요합니다.

  • Agent Platform 사용자(roles/aiplatform.user)

샌드박스 관리하기

Agent Platform 인스턴스와 연결된 샌드박스 환경을 나열하고, 세부정보를 보고, 일시중지하고, 재개하고, 삭제할 수 있습니다. 일시중지 및 재개를 사용하면 유휴 샌드박스의 컴퓨팅 리소스 예약을 취소하고 파일 시스템 상태나 연결 ID를 잃지 않고 나중에 다시 온라인 상태로 전환할 수 있습니다. 기존 샌드박스의 구성을 변경하려면 삭제하고 새로 만들어야 합니다.

샌드박스 나열

Agent Platform 인스턴스와 연결된 모든 샌드박스를 나열하려면 다음 안내를 따르세요.

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: Agent Platform 인스턴스의 Google Cloud 리전입니다. 지원되는 지역을 참고하세요.
  • INSTANCE_ID: Agent Platform 인스턴스 ID입니다.

샌드박스 세부정보 보기

특정 샌드박스의 구성 및 상태를 보려면 다음 안내를 따르세요.

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: Agent Platform 인스턴스의 Google Cloud 리전입니다. 지원되는 지역을 참고하세요.
  • INSTANCE_ID: 샌드박스가 포함된 Agent Platform 인스턴스 ID입니다.
  • SANDBOX_ID: 기존 샌드박스 ID입니다.

출력에는 생성 시간, 상태(예: STATE_RUNNING), 샌드박스 사양과 같은 세부정보가 포함됩니다.

샌드박스 일시중지

샌드박스를 일시중지하면 디스크 상태와 연결 메타데이터를 보존하면서 컴퓨팅 리소스가 해제됩니다. 일시중지된 샌드박스는 실행 중인 샌드박스보다 비용이 훨씬 적게 들며 몇 초 만에 재개할 수 있습니다. 샌드박스가 장기간 유휴 상태이지만 나중에 사용할 수 있도록 세션 상태와 연결 ID를 보존하려면 일시중지를 사용합니다.

일시중지된 샌드박스에는 다음과 같은 특징이 있습니다.

  • 샌드박스 ID, 연결 메타데이터, Private Service Connect 엔드포인트를 유지합니다.
  • 일시중지 시점에 모든 컨테이너 내 파일 시스템 상태를 유지합니다.
  • STATE_PAUSED로 전환합니다. 재개할 때까지 데이터 영역 엔드포인트에 대한 요청에서 오류가 반환됩니다.

실행 중인 샌드박스를 일시중지하려면 다음 코드를 실행합니다.

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: Agent Platform 인스턴스의 Google Cloud 리전입니다. 지원되는 지역을 참고하세요.
  • INSTANCE_ID: 샌드박스가 포함된 Agent Platform 인스턴스 ID입니다.
  • SANDBOX_ID: 기존 샌드박스 ID입니다.

샌드박스 재개

일시중지된 샌드박스를 재개하면 컴퓨팅이 다시 온라인 상태가 됩니다. 샌드박스는 일시중지 시점에 있던 동일한 ID, 연결 엔드포인트(모든 Private Service Connect 서비스 연결 포함), 파일 시스템 상태를 유지합니다. 재개 작업이 완료되는 즉시 데이터 영역 요청을 샌드박스에 다시 보낼 수 있습니다.

일시중지된 샌드박스를 재개하려면 다음 코드를 실행합니다.

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID입니다.
  • LOCATION: Agent Platform 인스턴스의 Google Cloud 리전입니다. 지원되는 지역을 참고하세요.
  • INSTANCE_ID: 샌드박스가 포함된 Agent Platform 인스턴스 ID입니다.
  • SANDBOX_ID: 일시중지된 샌드박스 ID입니다.

샌드박스 삭제

샌드박스 환경을 명시적으로 삭제하고 리소스를 확보하려면 다음 안내를 따르세요.

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

감사 로깅 및 모니터링

샌드박스에서 명령어를 관리하고 실행하면 에이전트 플랫폼은 aiplatform.googleapis.com 서비스 이름과 audited_resource 모니터링 리소스 유형으로 Cloud 감사 로그에 API 수준 활동을 기록합니다.

  • 관리자 활동(ADMIN_WRITE) 로그: CreateSandboxEnvironment, PauseSandboxEnvironment, ResumeSandboxEnvironment, SnapshotSandboxEnvironment, DeleteSandboxEnvironment(aiplatform.sandboxEnvironments.* IAM 권한 필요)를 포함한 컨트롤 플레인 수명 주기 변형에 대해 자동으로 기록됩니다.
  • 데이터 액세스(ADMIN_READ) 로그: GetSandboxEnvironment 및 ListSandboxEnvironments를 포함하여 메타데이터 읽기 작업에 사용 설정된 경우 기록됩니다.
  • 데이터 액세스(DATA_WRITE) 로그: ExecuteSandboxEnvironment, BidiExecuteSandboxEnvironment, AuthorizeSandboxEnvironmentAccess, ExecuteCode를 포함하여 데이터 영역 명령어 실행 및 액세스 승인 호출에 사용 설정된 경우 기록됩니다. VPC 서비스 제어로 보호되는 리소스의 경우 요청 및 응답 페이로드가 감사 로그에서 생략됩니다.

다음 모니터링 가능성 및 위협 감지 경계를 염두에 두세요.

  • 컨테이너 내 프로세스 및 스트림 활동: Cloud 감사 로그는 명령어 실행을 시작하거나 연결을 승인하는 API 요청을 로깅하지만 컨테이너 내에서 생성된 개별 하위 프로세스, 파일 시스템 수정 또는 열려 있는 WebSocket, Chrome DevTools 프로토콜(CDP) 또는 PTY 세션을 통해 전송된 후속 대화형 프레임을 로깅하지 않습니다.
  • 컨테이너 stdout 및 stderr 로깅: 자동 Agent Runtime용 Cloud Logging 수집(예: reasoning_engine_stdout 및 reasoning_engine_stderr)은 상위 ReasoningEngine 인스턴스에만 적용되며 샌드박스 하위 리소스에서 로그를 자동으로 수집하지 않습니다. 명령어 출력(stdout, stderr, 종료 코드)은 상위 에이전트에 대한 실행 응답으로 반환되며, 여기서 구조화된 항목을 검사하고 Cloud Logging에 작성할 수 있습니다.
  • 위협 감지 및 네트워크 검사: 샌드박스는 gVisor 커널 격리와 앰비언트 Google Cloud 사용자 인증 정보가 없는 권한이 없는 샌드박스 내 ID를 통해 격리를 적용합니다. 비정상적인 동작이나 승인되지 않은 네트워크 이그레스를 모니터링하려면 DATA_WRITE 감사 로그를 상위 에이전트의 에이전트 이상 감지와 결합하고 VPC 흐름 로그, Cloud Next Generation Firewall(Cloud NGFW) 규칙 로깅, Secure Web Proxy 검사를 사용하여 Private Service Connect 인터페이스를 통해 샌드박스 이그레스를 라우팅합니다. 자세한 내용은 보안, ID, 모니터링 가능성 경계를 참조하세요.