Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Agent Platform Workbench 문제 해결

이 페이지에서는 Gemini Enterprise Agent Platform Workbench 사용 시 문제가 발생할 경우 도움이 될 수 있는 문제 해결 단계를 설명합니다.

Gemini Enterprise Agent Platform의 다른 구성요소를 사용하는 데 도움이 필요하면 Agent Platform 문제 해결도 참고하세요.

이 페이지의 콘텐츠를 필터링하려면 주제를 클릭합니다.

Agent Platform Workbench 인스턴스

이 섹션에서는 Agent Platform Workbench 인스턴스의 문제 해결 단계를 설명합니다.

AI 도구를 사용한 문제 해결

이 섹션에서는 문제 해결을 위해 AI 도구를 사용하는 방법을 설명합니다.

Cloud Assistance 조사로 문제 해결

Agent Platform을 다른 Google Cloud 제품과 연결할 경우 Gemini Cloud Assist 조사가 통합 문제를 해결하는 데 도움이 될 수 있습니다. 또한 인스턴스 자체의 문제 해결을 가속화할 수도 있습니다. Gemini Cloud Assist를 사용하면 인스턴스에서 생성된 측정항목과 로그에서 유용한 정보를 얻을 수 있습니다.

인스턴스를 중지하고 View in Compute Engine 링크를 따릅니다.
운영 에이전트를 설치합니다(권장). 몇 분 정도 걸릴 수 있습니다.
맞춤 메타데이터 필드 notebook-enable-debug를 추가하고 이를 true로 설정합니다.
인스턴스를 다시 시작하고 문제를 재현합니다.
Cloud Assist Investigations API를 사용 설정하고 구성합니다.
새 조사를 만들고 자연어 프롬프트를 사용하여 문제를 자세히 설명합니다.
입력하면 조사에 추가할 리소스를 제안하는 대화상자가 표시됩니다. 이 목록을 검토하고 인스턴스를 리소스로 추가하고 이 지원되는 제품 목록에 있는 다른 리소스도 추가해야 합니다.
조사를 시작하고 결과를 검토합니다.

Gemini CLI로 진단 파일 문제 해결

Cloud 지원 조사 결과를 사용하여 인스턴스의 진단 파일에 대한 추가 AI 기반 조사를 알릴 수 있습니다.

진단 도구를 실행하고 결과를 업로드할 Cloud Storage 버킷을 지정합니다.

sudo /opt/deeplearning/bin/diagnostic_tool.sh [--repair] [--bucket=$BUCKET]

진단 파일을 워크스테이션에 다운로드한 다음 Gemini CLI를 설치하고 구성합니다.
애플리케이션을 시작한 다음 문제를 설명합니다. 컨텍스트에 Cloud Assistance 조사의 가설을 포함합니다. 자연어 프롬프트를 사용하여 진단 파일의 내용을 읽어 조사를 확장하도록 모델에 요청합니다.

JupyterLab에 연결 및 열기

이 섹션에서는 JupyterLab 연결 및 열기와 관련된 문제 해결 단계에 대해 설명합니다.

JupyterLab 열기를 클릭해도 아무 반응이 없음

문제

JupyterLab 열기를 클릭해도 아무 반응이 없습니다.

해결책

브라우저에서 새 탭 자동 열기가 차단되지 않았는지 확인합니다. JupyterLab은 새 브라우저 탭에서 열립니다.

Agent Platform Workbench 인스턴스에서 터미널에 액세스할 수 없음

문제

터미널에 액세스할 수 없거나 런처에서 터미널 창을 찾을 수 없는 경우 이는 Agent Platform Workbench 인스턴스에 터미널 액세스가 사용 설정되지 않았기 때문일 수 있습니다.

해결책

터미널 액세스 옵션을 사용 설정하여 새 Agent Platform Workbench 인스턴스를 만들어야 합니다. 인스턴스를 만든 후에는 이 옵션을 변경할 수 없습니다.

JupyterLab을 열 때 502 오류 발생

문제

502 오류는 Agent Platform Workbench 인스턴스가 아직 준비되지 않았음을 의미합니다.

해결책

몇 분 정도 기다린 후 Google Cloud 콘솔 브라우저 탭을 새로고침하고 다시 시도합니다.

노트북이 응답하지 않음

문제

Agent Platform Workbench 인스턴스가 셀을 실행 중이 아니거나 고정된 것으로 보입니다.

해결책

먼저 상단 메뉴에서 커널을 클릭하고 커널 다시 시작을 클릭하여 커널을 다시 시작해봅니다. 그래도 문제가 해결되지 않으면 다음 안내를 따르세요.

JupyterLab 브라우저 페이지를 새로고침합니다. 저장되지 않은 셀 출력은 지속되지 않으므로 이러한 셀을 다시 실행하여 출력을 다시 생성해야 합니다.
인스턴스를 재설정합니다.

SSH를 사용하여 Agent Platform Workbench 인스턴스에 연결할 수 없음

문제

터미널 창을 통해 SSH를 사용해서 인스턴스에 연결할 수 없습니다.

Agent Platform Workbench 인스턴스는 OS 로그인을 사용하여 SSH 액세스를 사용 설정합니다. 인스턴스를 만들 때 Agent Platform Workbench는 메타데이터 키 enable-oslogin을 TRUE로 설정하여 기본적으로 OS 로그인을 사용 설정합니다. SSH를 사용해서 인스턴스에 액세스할 수 없으면 이 메타데이터 키를 TRUE로 설정해야 할 수 있습니다.

해결책

Google Cloud 콘솔을 사용하여 Agent Platform Workbench 인스턴스에 연결하는 방식은 지원되지 않습니다. 터미널 창을 통해 SSH를 사용하여 인스턴스에 연결할 수 없으면 다음을 참조하세요.

메타데이터 키 enable-oslogin을 TRUE로 설정하려면 Notebooks API의 projects.locations.instances.patch 메서드 또는 Agent Platform SDK의 gcloud workbench instances update 명령어를 사용합니다.

GPU 할당량이 초과됨

문제

GPU를 사용해서 Agent Platform Workbench 인스턴스를 만들 수 없습니다.

해결책

할당량 페이지에서 프로젝트의 현재 사용 가능한 GPU 수를 확인합니다. GPU가 할당량 페이지에 나와 있지 않거나 추가 GPU 할당량이 필요한 경우에는 Compute Engine GPU의 할당량 상향 조정을 요청할 수 있습니다. 할당량 한도 상향 요청을 참조하세요.

Agent Platform Workbench 인스턴스 만들기

이 섹션에서는 에이전트 플랫폼 워크벤치 인스턴스 만들기와 관련된 문제 해결 방법을 설명합니다.

인스턴스가 무기한 대기 중 상태로 유지되거나 프로비저닝 상태에서 멈춤

문제

Agent Platform Workbench 인스턴스를 만든 후에는 인스턴스가 무기한 대기 상태로 유지됩니다. 다음과 같은 오류가 직렬 로그에 표시될 수 있습니다.

Could not resolve host: notebooks.googleapis.com

인스턴스가 프로비저닝 상태에서 멈춘 경우 이는 인스턴스에 잘못된 비공개 네트워킹 구성이 있기 때문일 수 있습니다.

해결책

인스턴스 로그에 연결 또는 제한 시간 오류 표시 섹션의 단계를 수행합니다.

공유 VPC 네트워크 내에서 인스턴스를 만들 수 없음

문제

공유 VPC 네트워크 내에서 인스턴스를 만들려고 시도하면 다음과 같은 오류 메시지가 표시됩니다.

Required 'compute.subnetworks.use' permission for
'projects/network-administration/regions/us-central1/subnetworks/v'

해결책

문제는 Notebooks 서비스 계정이 올바른 권한 없이 인스턴스를 만들려고 시도 중이기 때문입니다.

Notebooks 서비스 계정이 공유 VPC 네트워크 내에서 에이전트 플랫폼 워크벤치 인스턴스를 만들 수 있도록 Notebooks 서비스 계정에 필요한 권한이 있는지 확인하려면 관리자에게 호스트 프로젝트에서 Notebooks 서비스 계정에 Compute 네트워크 사용자 역할 (roles/compute.networkUser) IAM 역할을 부여해 달라고 요청하세요.

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 Notebooks 서비스 계정이 공유 VPC 네트워크 내에서 에이전트 플랫폼 Workbench 인스턴스를 만들 수 있는지 확인하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

Notebooks 서비스 계정이 공유 VPC 네트워크 내에서 Agent Platform Workbench 인스턴스를 만들 수 있도록 하려면 다음 권한이 필요합니다.

서브네트워크를 사용하려면 다음 안내를 따르세요. compute.subnetworks.use

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 Notebooks 서비스 계정에 이러한 권한을 부여할 수도 있습니다.

커스텀 컨테이너로 Agent Platform Workbench 인스턴스를 만들 수 없음

문제

Google Cloud 콘솔에서 Agent Platform Workbench 인스턴스를 만들 때는 커스텀 컨테이너를 사용하는 옵션이 없습니다.

해결책

커스텀 컨테이너를 Agent Platform Workbench 인스턴스에 추가할 수 없으며 Google Cloud 콘솔을 사용하여 커스텀 컨테이너를 추가할 수 없습니다.

커스텀 컨테이너를 사용하는 대신 conda 환경을 추가하는 것이 좋습니다.

Notebooks API를 사용하여 커스텀 컨테이너를 Agent Platform Workbench 인스턴스에 추가할 수 있지만 이 기능은 지원되지 않습니다.

Gemini CLI를 사용할 수 없음

문제

Gemini CLI 타일이 JupyterLab 런처에 있고 성공적으로 열리지만 Gemini가 프롬프트에 응답하지 않습니다.

해결책

관리자가 Gemini CLI에 대한 액세스를 차단했을 수 있습니다. Gemini CLI에 대한 액세스 제어를 참고하세요.

공유 스토리지 마운트 버튼 없음

문제

JupyterLab 인터페이스의 파일 브라우저 탭에 공유 스토리지 마운트 버튼이 없습니다.

해결책

Agent Platform Workbench 인스턴스의 JupyterLab 인터페이스에 공유 스토리지 마운트 버튼을 표시하려면 storage.buckets.list 권한이 필요합니다. 관리자에게 Agent Platform Workbench 인스턴스의 서비스 계정에 프로젝트에 대한 storage.buckets.list 권한을 부여해 달라고 요청하세요.

Managed Service for Apache Spark를 사용할 때 599 오류 발생

문제

Managed Service for Apache Spark가 사용 설정된 인스턴스를 만들려고 시도하면 다음과 같은 오류 메시지가 표시됩니다.

HTTP 599: Unknown (Error from Gateway: [Timeout while connecting]
Exception while attempting to connect to Gateway server url.
Ensure gateway url is valid and the Gateway instance is running.)

해결책

Cloud DNS 구성에서 *.googleusercontent.com 도메인의 Cloud DNS 항목을 추가합니다.

서드 파티 JupyterLab 확장 프로그램을 설치할 수 없음

문제

서드 파티 JupyterLab 확장 프로그램을 설치하려고 시도하면 Error: 500 메시지가 표시됩니다.

해결책

서드 파티 JupyterLab 확장 프로그램은 Agent Platform Workbench 인스턴스에서 지원되지 않습니다.

기본 가상 머신을 수정할 수 없음

문제

Agent Platform Workbench 인스턴스의 기본 가상 머신 (VM)을 수정하려고 하면 다음과 비슷한 오류 메시지가 표시될 수 있습니다.

Current principal doesn't have permission to mutate this resource.

해결책

이 오류는 Google Cloud 콘솔 또는 Compute Engine API를 사용하여 인스턴스의 기본 VM을 수정할 수 없기 때문에 발생합니다.

Agent Platform Workbench 인스턴스의 기본 VM을 수정하려면 Notebooks API의 projects.locations.instances.patch 메서드 또는 Agent Platform SDK의 gcloud workbench instances update 명령어를 사용합니다.

conda 환경을 추가한 후 `pip` 패키지를 사용할 수 없음

문제

conda 기반 커널을 추가한 후 pip 패키지를 사용할 수 없습니다.

해결책

이 문제를 해결하려면 conda 환경 추가를 참조하고 다음을 시도하세요.

DL_ANACONDA_ENV_HOME 변수가 사용되었고 환경 이름이 포함되었는지 확인합니다.
pip가 opt/conda/envs/ENVIRONMENT/bin/pip와 비슷한 경로에 있는지 확인합니다. which pip 명령어를 사용하여 경로를 가져올 수 있습니다.

단일 사용자 액세스로 인스턴스의 데이터에 액세스하거나 복사할 수 없음

문제

단일 사용자 액세스로 인스턴스의 데이터에 액세스할 수 없습니다.

단일 사용자 액세스로 설정된 Agent Platform Workbench 인스턴스의 경우 지정된 단일 사용자 (소유자)만 인스턴스의 데이터에 액세스할 수 있습니다.

해결책

인스턴스 소유자가 아닐 때 데이터를 액세스하거나 복사하려면 지원 케이스를 개설합니다.

예기치 않은 종료

문제

Agent Platform Workbench 인스턴스가 예기치 않게 종료됩니다.

해결책

인스턴스가 예기치 않게 종료되면 유휴 상태 종료가 초기화되었기 때문일 수 있습니다.

유휴 상태 종료를 사용 설정했으면 지정된 기간 동안 커널 활동이 없을 때 인스턴스가 종료됩니다. 예를 들어 노트북에 셀 또는 새 출력 인쇄를 실행하는 것은 유휴 제한 시간 타이머를 재설정하는 활동입니다. CPU 사용량은 유휴 제한 시간 타이머를 재설정하지 않습니다.

인스턴스 로그에 연결 또는 제한 시간 오류 표시

문제

Agent Platform Workbench 인스턴스의 로그에 연결 또는 제한 시간 오류가 표시됩니다.

해결책

인스턴스 로그에 연결 또는 제한 시간 오류가 표시되면 포트 8080에서 Jupyter 서버가 실행 중인지 확인합니다. Jupyter 내부 API가 활성 상태인지 확인 섹션의 단계를 수행합니다.

External IP를 사용 중지하고 비공개 VPC 네트워크를 사용하는 경우 네트워크 구성 옵션 문서도 따랐는지 확인합니다. 다음 사항을 고려하세요.

VPC 호스트 프로젝트에 인스턴스가 있는 리전과 같은 리전에서 선택한 서브넷에서 비공개 Google 액세스를 사용 설정해야 합니다. 비공개 Google 액세스 구성 방법에 대한 자세한 내용은 비공개 Google 액세스 문서를 참조하세요.
Cloud DNS를 사용하는 경우 인스턴스에서 네트워크 구성 옵션 문서에 지정된 필수 Cloud DNS 도메인을 확인할 수 있어야 합니다. 이를 확인하려면 인스턴스에서 필요한 DNS 도메인을 확인할 수 있는지 확인 섹션의 단계를 수행합니다.

인스턴스 로그에 'Jupyter API에 연결할 수 없음' 'ReadTimeoutError' 표시

문제

Agent Platform Workbench 인스턴스 로그에 다음과 같은 오류가 표시됩니다.

notebooks_collection_agent. Unable to contact Jupyter API:
HTTPConnectionPool(host=\'127.0.0.1\', port=8080):
Max retries exceeded ReadTimeoutError(\"HTTPConnectionPool(host=\'127.0.0.1\', port=8080

해결책

인스턴스 로그에 연결 또는 제한 시간 오류 표시 섹션의 단계를 수행합니다. Notebooks 수집 에이전트 스크립트를 수정하여 HTTP_TIMEOUT_SESSION을 더 큰 값(예: 60)으로 변경해 호출이 응답하는 데 시간이 너무 오래 걸리거나 요청된 URL에 연결할 수 없어 요청이 실패했는지 확인할 수도 있습니다.

`docker0` 주소가 VPC 주소 지정과 충돌함

문제

기본적으로 docker0 인터페이스는 172.17.0.1/16 IP 주소로 생성됩니다. 이로 인해 VPC 네트워크의 IP 주소 지정이 충돌하여 인스턴스가 172.17.0.1/16 주소가 있는 다른 엔드포인트에 연결할 수 없게 될 수 있습니다.

해결책

다음 시작 후 스크립트를 사용하고 시작 후 스크립트 동작을 run_once로 설정하여 VPC 네트워크와 충돌하지 않는 IP 주소로 docker0 인터페이스가 생성되도록 강제할 수 있습니다.

#!/bin/bash
# Wait for Docker to be fully started
while ! systemctl is-active docker; do
sleep 1
done
# Stop the Docker service
systemctl stop docker
# Modify /etc/docker/daemon.json
cat < /etc/docker/daemon.json
{
"bip": "CUSTOM_DOCKER_IP/16"
}
EOF
# Restart the Docker service
systemctl start docker

지정된 예약 없음

문제

인스턴스를 만드는 작업으로 인해 Specified reservations do not exist 오류 메시지가 표시됩니다. 작업 출력은 다음과 유사할 수 있습니다.

{
  "name": "projects/PROJECT/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.notebooks.v2.OperationMetadata",
    "createTime": "2025-01-01T01:00:01.000000000Z",
    "endTime": "2025-01-01T01:00:01.000000000Z",
    "target": "projects/PROJECT/locations/LOCATION/instances/INSTANCE_NAME",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v2",
    "endpoint": "CreateInstance"
  },
  "done": true,
  "error": {
    "code": 3,
    "message": "Invalid value for field 'resource.reservationAffinity': '{  \"consumeReservationType\": \"SPECIFIC_ALLOCATION\",  \"key\": \"compute.googleapis.com/reservation-name...'. Specified reservations [projects/PROJECT/zones/ZONE/futureReservations/RESERVATION_NAME] do not exist.",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "REQUEST_ID"
      }
    ]
  }
}

해결책

일부 Compute Engine 머신 유형을 사용하려면 생성 시 로컬 SSD나 최소 CPU 플랫폼과 같은 추가 파라미터가 필요합니다. 인스턴스 사양에는 이러한 추가 필드가 포함되어야 합니다.

Agent Platform Workbench 인스턴스는 기본적으로 자동 최소 CPU 플랫폼을 사용합니다. 예약에서 특정 플랫폼을 설정하는 경우 Agent Platform Workbench 인스턴스를 만들 때 min_cpu_platform을 적절하게 설정해야 합니다.
Agent Platform Workbench 인스턴스는 항상 로컬 SSD 수를 머신 유형에 따른 기본값으로 설정합니다. 예를 들어 a2-ultragpu-1g에는 항상 1개의 로컬 SSD가 있지만 a2-highgpu-1g에는 항상 0개의 로컬 SSD가 있습니다. 에이전트 플랫폼 워크벤치 인스턴스에 사용할 예약을 만들 때는 로컬 SSD를 기본값으로 두어야 합니다.

유용한 절차

이 섹션에서는 유용한 절차에 대해 설명합니다.

SSH를 사용하여 Agent Platform Workbench 인스턴스에 연결

Cloud Shell에서 또는 Google Cloud CLI가 설치된 환경에서 다음 명령어를 입력하여 ssh를 통해 인스턴스에 연결합니다.

gcloud compute ssh --project PROJECT_ID \
  --zone ZONE \
  INSTANCE_NAME -- -L 8080:localhost:8080

다음을 바꿉니다.

PROJECT_ID: 프로젝트 ID
ZONE: 인스턴스가 있는 Google Cloud 영역
INSTANCE_NAME: 인스턴스의 이름

인스턴스의 Compute Engine 세부정보 페이지를 열고 SSH 버튼을 클릭하여 인스턴스에 연결할 수도 있습니다.

역방향 프록시 서버에 다시 등록

Agent Platform Workbench 인스턴스를 내부 역방향 프록시 서버에 다시 등록하려면 인스턴스 페이지에서 VM을 중지하고 시작하거나 ssh를 사용하여 Agent Platform Workbench 인스턴스에 연결하고 다음을 입력하면 됩니다.

cd /opt/deeplearning/bin
sudo ./attempt-register-vm-on-proxy.sh

Docker 서비스 상태 확인

Docker 서비스 상태를 확인하려면 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력합니다.

sudo service docker status

역방향 프록시 에이전트가 실행 중인지 확인

노트북 역방향 프록시 에이전트가 실행 중인지 확인하려면 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력합니다.

# Confirm Inverting Proxy agent Docker container is running (proxy-agent)
sudo docker ps

# Verify State.Status is running and State.Running is true.
sudo docker inspect proxy-agent

# Grab logs
sudo docker logs proxy-agent

Jupyter 서비스 상태 확인 및 로그 수집

Jupyter 서비스 상태를 확인하려면 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력합니다.

sudo service jupyter status

Jupyter 서비스 로그를 수집하려면 다음을 실행합니다.

sudo journalctl -u jupyter.service --no-pager

Jupyter 내부 API가 활성 상태인지 확인

Jupyter API는 항상 포트 8080에서 실행되어야 합니다. 인스턴스의 syslog에서 다음과 유사한 항목이 있는지 확인하여 이를 확인할 수 있습니다.

Jupyter Server ... running at:
http://localhost:8080

또한 Jupyter 내부 API가 활성 상태인지 확인하려면 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력하면 됩니다.

curl http://127.0.0.1:8080/api/kernelspecs

요청이 너무 오래 걸리는 경우 API가 응답하는 데 걸리는 시간을 측정할 수도 있습니다.

time curl -V http://127.0.0.1:8080/api/status
time curl -V http://127.0.0.1:8080/api/kernels
time curl -V http://127.0.0.1:8080/api/connections

Agent Platform Workbench 인스턴스에서 이러한 명령어를 실행하려면 JupyterLab을 열고 새 터미널을 만듭니다.

Docker 서비스 다시 시작

Docker 서비스를 다시 시작하려면 인스턴스 페이지에서 VM을 중지하고 시작하거나 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력합니다.

sudo service docker restart

역방향 프록시 에이전트 다시 시작

역방향 프록시 에이전트를 다시 시작하려면 인스턴스 페이지에서 VM을 중지하고 시작하거나 ssh를 사용하여 에이전트 플랫폼 Workbench 인스턴스에 연결하고 다음을 입력합니다.

sudo docker restart proxy-agent

Jupyter 서비스 다시 시작

Jupyter 서비스를 다시 시작하려면 인스턴스 페이지에서 VM을 중지하고 시작하거나 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력합니다.

sudo service jupyter restart

Notebooks 수집 에이전트 다시 시작

Notebooks 수집 에이전트 서비스는 백그라운드에서 에이전트 플랫폼 Workbench 인스턴스의 핵심 서비스 상태를 확인하는 Python 프로세스를 실행합니다.

Notebooks 수집 에이전트 서비스를 다시 시작하려면 Google Cloud 콘솔에서 VM을 중지하고 시작하거나 ssh를 사용하여 에이전트 플랫폼 Workbench 인스턴스에 연결하고 다음을 입력합니다.

sudo systemctl stop notebooks-collection-agent.service

다음을 수행합니다.

sudo systemctl start notebooks-collection-agent.service

Agent Platform Workbench 인스턴스에서 이러한 명령어를 실행하려면 JupyterLab을 열고 새 터미널을 만듭니다.

Notebooks 수집 에이전트 스크립트 수정

스크립트에 액세스하고 수정하려면 인스턴스에서 터미널을 열거나 ssh를 사용하여 Agent Platform Workbench 인스턴스에 연결하고 다음을 입력합니다.

nano /opt/deeplearning/bin/notebooks_collection_agent.py

파일을 수정한 후에는 저장해야 합니다.

그런 다음 Notebooks 수집 에이전트 서비스를 다시 시작해야 합니다.

인스턴스에서 필요한 DNS 도메인을 확인할 수 있는지 확인

인스턴스에서 필요한 DNS 도메인을 확인할 수 있는지 확인하려면 ssh를 사용하여 에이전트 플랫폼 워크벤치 인스턴스에 연결하고 다음을 입력하면 됩니다.

host notebooks.googleapis.com
host *.notebooks.cloud.google.com
host *.notebooks.googleusercontent.com
host *.kernels.googleusercontent.com

또는

curl --silent --output /dev/null "https://notebooks.cloud.google.com"; echo $?

인스턴스에 Managed Service for Apache Spark가 사용 설정된 경우 다음을 실행하여 인스턴스에서 *.kernels.googleusercontent.com을 확인하는지 확인할 수 있습니다.

curl --verbose -H "Authorization: Bearer $(gcloud auth print-access-token)" https://${PROJECT_NUMBER}-dot-${REGION}.kernels.googleusercontent.com/api/kernelspecs | jq .

Agent Platform Workbench 인스턴스에서 이러한 명령어를 실행하려면 JupyterLab을 열고 새 터미널을 만듭니다.

인스턴스의 사용자 데이터 사본 만들기

인스턴스의 사용자 데이터 사본을 Cloud Storage에 저장하려면 다음 단계를 완료합니다.

Cloud Storage 버킷 만들기(선택사항)

인스턴스가 있는 동일한 프로젝트에서 사용자 데이터를 저장할 수 있는 Cloud Storage 버킷을 만듭니다. Cloud Storage 버킷이 이미 있으면 이 단계를 건너뜁니다.

Cloud Storage 버킷을 만듭니다.
```
gcloud storage buckets create gs://BUCKET_NAME
```
BUCKET_NAME을 버킷 이름 요구사항을 충족하는 버킷 이름으로 바꿉니다.

사용자 데이터 복사

인스턴스의 JupyterLab 인터페이스에서 파일 > 새로 만들기 > 터미널을 선택하여 터미널 창을 엽니다. Agent Platform Workbench 인스턴스의 경우 대신 SSH를 사용하여 인스턴스 터미널에 연결할 수 있습니다.
gcloud CLI를 사용하여 사용자 데이터를 Cloud Storage 버킷에 복사합니다. 다음 예시 명령어는 인스턴스의 /home/jupyter/ 디렉터리에 있는 모든 파일을 Cloud Storage 버킷의 디렉터리에 복사합니다.
```
gcloud storage cp /home/jupyter/* gs://BUCKET_NAMEPATH --recursive
```
다음을 바꿉니다.
- BUCKET_NAME: Cloud Storage 버킷 이름
- PATH: 파일을 복사할 디렉터리의 경로(예: /copy/jupyter/)

gcpdiag를 사용하여 프로비저닝 중에 중단된 인스턴스 조사

gcpdiag는 오픈소스 도구입니다. 공식적으로 지원되는 Google Cloud 제품이 아닙니다. gcpdiag 도구를 사용하여 Google Cloud프로젝트 문제를 식별하고 해결할 수 있습니다. 자세한 내용은 GitHub의 gcpdiag 프로젝트를 참조하세요.

이 gcpdiag 런북에서는 다음 영역을 포함하여 Agent Platform Workbench 인스턴스가 프로비저닝 상태에서 중단되는 잠재적 원인을 조사합니다.

상태: 현재 인스턴스 상태를 확인하여 프로비저닝 중에 중단되거나 활성 상태가 아닌지 확인합니다.
인스턴스의 Compute Engine VM 부팅 디스크 이미지: 인스턴스가 커스텀 컨테이너, 공식 workbench-instances 이미지, Deep Learning VM 이미지 또는 인스턴스가 프로비저닝 상태에서 중단될 수 있는 지원되지 않는 이미지로 생성되었는지 확인합니다.
커스텀 스크립트: 기본 Jupyter 포트를 변경하거나 인스턴스가 프로비저닝 상태에서 중단될 수 있는 종속 항목을 중단하는 커스텀 시작 스크립트 또는 시작 후 스크립트를 인스턴스에서 사용하고 있는지 확인합니다.
환경 버전: 업그레이드 가능성을 확인하여 인스턴스에서 최신 환경 버전을 사용하고 있는지 확인합니다. 이전 버전에서는 인스턴스가 프로비저닝 상태에서 중단될 수 있습니다.
인스턴스의 Compute Engine VM 성능: 현재 VM 성능을 검사하여 높은 CPU 사용량, 메모리 부족 또는 디스크 공간 문제로 인해 정상적인 작업이 중단되지 않았는지 확인합니다.
인스턴스의 Compute Engine 직렬 포트 또는 시스템 로깅: 인스턴스에 직렬 포트 로그가 있는지 확인합니다. 이 로그는 Jupyter가 포트 127.0.0.1:8080에서 실행 중인지 확인하기 위해 분석됩니다.
인스턴스의 Compute Engine SSH 및 터미널 액세스: 사용자가 SSH를 통해 터미널을 열어 'home/jupyter'의 공간 사용량이 85% 미만인지 확인할 수 있도록 인스턴스의 Compute Engine VM이 실행 중인지 확인합니다. 여유 공간이 부족하면 인스턴스가 프로비저닝 상태에서 중단될 수 있습니다.
외부 IP가 사용 중지됨: 외부 IP 액세스가 사용 중지되었는지 확인합니다. 잘못된 네트워킹 구성으로 인해 인스턴스가 프로비저닝 상태에서 중단될 수 있습니다.

Docker

Docker 컨테이너에서 gcpdiag를 시작하는 래퍼를 사용하여 gcpdiag를 실행할 수 있습니다. Docker 또는 Podman이 설치되어 있어야 합니다.

로컬 워크스테이션에서 다음 명령어를 복사하고 실행합니다.
```
curl https://gcpdiag.dev/gcpdiag.sh >gcpdiag && chmod +x gcpdiag
```

gcpdiag 명령어를 실행합니다.

./gcpdiag runbook vertex/workbench-instance-stuck-in-provisioning \
    --parameter project_id=PROJECT_ID \
    --parameter instance_name=INSTANCE_NAME \
    --parameter zone=ZONE

이 런북에 사용 가능한 파라미터를 봅니다.

다음을 바꿉니다.

PROJECT_ID: 리소스가 포함된 프로젝트의 ID입니다.
INSTANCE_NAME: 프로젝트 내 대상 Agent Platform Workbench 인스턴스의 이름입니다.
ZONE: 대상 Agent Platform Workbench 인스턴스가 있는 영역입니다.

유용한 플래그:

--universe-domain: 해당되는 경우 리소스를 호스팅하는 신뢰할 수 있는 파트너 Sovereign Cloud 도메인
--parameter 또는 -p: 런북 파라미터

모든 gcpdiag 도구 플래그의 목록과 설명은 gcpdiag 사용 안내를 참조하세요.

에이전트 플랫폼에서 서비스 계정 역할을 사용할 때 권한 오류 발생

문제

Agent Platform에서 서비스 계정 역할을 사용하면 일반 권한 오류가 발생합니다.

이러한 오류는 Cloud Logging의 제품 구성요소 로그나 감사 로그에 표시될 수 있습니다. 영향을 받는 프로젝트의 조합으로 표시될 수도 있습니다.

이러한 문제는 다음 중 하나 또는 둘 다로 인해 발생할 수 있습니다.

Service Account User 역할을 사용해야 할 때 Service Account Token Creator 역할을 사용하거나 그 반대의 경우. 이러한 역할은 서비스 계정에 서로 다른 권한을 부여하며 상호 교환될 수 없습니다. Service Account Token Creator 및 Service Account User 역할의 차이점은 서비스 계정 역할을 참조하세요.
기본적으로 허용되지 않는 여러 프로젝트에 서비스 계정 권한을 부여했습니다.

해결책

이 문제를 해결하려면 다음 중 하나 이상을 사용해 보세요.

Service Account Token Creator 또는 Service Account User 역할이 필요한지 확인합니다. 자세한 내용은 사용 중인 Agent Platform 서비스 및 사용 중인 기타 제품 통합에 대한 IAM 문서를 참고하세요.
여러 프로젝트에 서비스 계정 권한을 부여한 경우 iam.disableCrossProjectServiceAccountUsage가 적용되지 않는지 확인하여 프로젝트 간에 연결할 서비스 계정을 사용 설정합니다. iam.disableCrossProjectServiceAccountUsage가 적용되지 않게 하려면 다음 명령어를 실행합니다.
```
gcloud resource-manager org-policies disable-enforce \
  iam.disableCrossProjectServiceAccountUsage \
  --project=PROJECT_ID
```

Agent Platform Workbench 문제 해결 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Agent Platform Workbench 인스턴스

AI 도구를 사용한 문제 해결

Cloud Assistance 조사로 문제 해결

Gemini CLI로 진단 파일 문제 해결

JupyterLab에 연결 및 열기

JupyterLab 열기를 클릭해도 아무 반응이 없음

Agent Platform Workbench 인스턴스에서 터미널에 액세스할 수 없음

JupyterLab을 열 때 502 오류 발생

노트북이 응답하지 않음

SSH를 사용하여 Agent Platform Workbench 인스턴스에 연결할 수 없음

GPU 할당량이 초과됨

Agent Platform Workbench 인스턴스 만들기

인스턴스가 무기한 대기 중 상태로 유지되거나 프로비저닝 상태에서 멈춤

공유 VPC 네트워크 내에서 인스턴스를 만들 수 없음

필수 권한

커스텀 컨테이너로 Agent Platform Workbench 인스턴스를 만들 수 없음

Gemini CLI를 사용할 수 없음

공유 스토리지 마운트 버튼 없음

Managed Service for Apache Spark를 사용할 때 599 오류 발생

서드 파티 JupyterLab 확장 프로그램을 설치할 수 없음

기본 가상 머신을 수정할 수 없음

conda 환경을 추가한 후 pip 패키지를 사용할 수 없음

단일 사용자 액세스로 인스턴스의 데이터에 액세스하거나 복사할 수 없음

예기치 않은 종료

인스턴스 로그에 연결 또는 제한 시간 오류 표시

인스턴스 로그에 'Jupyter API에 연결할 수 없음' 'ReadTimeoutError' 표시

docker0 주소가 VPC 주소 지정과 충돌함

지정된 예약 없음

유용한 절차

SSH를 사용하여 Agent Platform Workbench 인스턴스에 연결

역방향 프록시 서버에 다시 등록

Docker 서비스 상태 확인

역방향 프록시 에이전트가 실행 중인지 확인

Jupyter 서비스 상태 확인 및 로그 수집

Jupyter 내부 API가 활성 상태인지 확인

Docker 서비스 다시 시작

역방향 프록시 에이전트 다시 시작

Jupyter 서비스 다시 시작

Notebooks 수집 에이전트 다시 시작

Notebooks 수집 에이전트 스크립트 수정

인스턴스에서 필요한 DNS 도메인을 확인할 수 있는지 확인

인스턴스의 사용자 데이터 사본 만들기

Cloud Storage 버킷 만들기(선택사항)

사용자 데이터 복사

gcpdiag를 사용하여 프로비저닝 중에 중단된 인스턴스 조사

Docker

에이전트 플랫폼에서 서비스 계정 역할을 사용할 때 권한 오류 발생

Agent Platform Workbench 문제 해결

conda 환경을 추가한 후 `pip` 패키지를 사용할 수 없음

`docker0` 주소가 VPC 주소 지정과 충돌함