사용자 관리형 노트북에서 Vertex AI Workbench 인스턴스로 마이그레이션

사용자 관리형 노트북에서 Vertex AI Workbench 인스턴스로 마이그레이션

Vertex AI Workbench 사용자 관리 노트북은 지원 중단되었습니다. 2025년 1월 30일에 사용자 관리형 노트북에 대한 지원이 종료되고 사용자 관리형 노트북 인스턴스를 만드는 기능이 삭제됩니다. 기존 인스턴스는 계속 작동하지만 패치, 업데이트, 업그레이드는 제공되지 않습니다. Vertex AI Workbench를 계속 사용하려면 이 페이지의 단계를 완료하여 사용자 관리형 노트북 인스턴스를 Vertex AI Workbench 인스턴스로 마이그레이션합니다.

이 페이지에서는 사용자 관리형 노트북 인스턴스에서 Vertex AI Workbench 인스턴스로 마이그레이션하는 방법을 설명합니다. Vertex AI Workbench 마이그레이션 도구를 사용하여 마이그레이션하거나 인스턴스의 데이터와 파일을 수동으로 마이그레이션할 수 있습니다.

마이그레이션 도구 개요

Vertex AI Workbench는 사용자 관리형 노트북 인스턴스에서 Vertex AI Workbench 인스턴스로 마이그레이션할 수 있는 마이그레이션 도구를 제공합니다.

마이그레이션 도구는 마이그레이션하려는 사용자 관리형 노트북 인스턴스와 비슷한 구성을 사용하여 Vertex AI Workbench 인스턴스를 만듭니다. 예를 들어 마이그레이션 도구에서 머신 유형, 네트워크 구성, 유휴 상태 종료 설정, 기타 사양이 동일하거나 유사한 인스턴스를 만듭니다. 그런 다음 사용자 관리형 노트북 인스턴스의 데이터 디스크에 있는 파일이 Vertex AI Workbench 인스턴스로 복사됩니다.

Vertex AI Workbench는 사용자 관리형 노트북 인스턴스를 삭제하거나 변경하지 않으므로 마이그레이션 후에도 계속 사용할 수 있습니다. 사용자 관리형 노트북 인스턴스가 더 이상 필요하지 않으면 해당 인스턴스에 대한 추가 요금이 청구되지 않도록 삭제합니다.

결제

사용자 관리형 노트북 인스턴스에서 익스트림 영구 디스크를 사용하는 경우 I/O 작업에 대한 마이그레이션 요금이 청구합니다. 디스크 가격 책정의 Persistent Disk 및 하이퍼디스크 가격 책정 섹션에서 '익스트림 프로비저닝된 IOPS'를 참조하세요.

마이그레이션 후에도 사용자 관리형 노트북 인스턴스는 계속 존재하며 이전과 마찬가지로 요금이 청구됩니다. 사용자 관리형 노트북 인스턴스가 더 이상 필요하지 않으면 해당 인스턴스에 대한 추가 요금이 청구되지 않도록 삭제합니다.

기본 마이그레이션 도구 동작

Vertex AI Workbench 마이그레이션 도구는 사용자 관리형 노트북 인스턴스를 사양이 일치하는 Vertex AI Workbench 인스턴스로 마이그레이션하려고 합니다. 사용자 관리형 노트북 인스턴스 사양을 Vertex AI Workbench 인스턴스에서 사용할 수 없으면 Vertex AI Workbench는 가능한 경우 기본 사양을 사용합니다. 마이그레이션 도구에서 사용자 관리형 노트북 인스턴스 사양을 마이그레이션할 수 없으면 인스턴스가 마이그레이션되지 않습니다.

다음 표에는 마이그레이션 도구의 주요 기본 마이그레이션 동작이 나와 있습니다.

카테고리	사용자 관리형 노트북 사양	마이그레이션 결과
OS	모든 Ubuntu 버전	Debian 11
	모든 Debian 버전	Debian 11
프레임워크	모든 CUDA 버전	CUDA 11.3
	모든 Python 버전	Python 3.10
	모든 PyTorch 버전	PyTorch 1.13
	모든 TensorFlow 버전	TensorFlow 2.11
	모든 R 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
	모든 로컬 PySpark 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
	모든 XGBoost 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
	모든 Kaggle Python 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
	모든 Jax 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
	모든 Apache Beam 버전	마이그레이션되지 않음. conda 환경 추가를 참조하세요.
머신 유형	지원되는 머신 유형	동일한 머신 유형
	지원되지 않는 머신 유형	e2-standard-4
가속기	지원되는 가속기	동일한 가속기
	지원되지 않는 가속기	마이그레이션에 가속기가 포함되지 않음
설정	유휴 상태 종료	마이그레이션됨
	휴지통에 삭제	마이그레이션됨
	nbconvert	마이그레이션됨
	파일 다운로드	마이그레이션됨
	터미널 액세스	마이그레이션됨
기타	Identity and Access Management 권한	마이그레이션됨. 하지만 Vertex AI Workbench 인스턴스를 사용하려면 새 권한이 필요할 수 있습니다.
	액세스 모드	마이그레이션됨
	네트워크	마이그레이션됨
	시작 후 스크립트	Google Cloud 콘솔을 사용할 때 인스턴스는 시작 후 스크립트 없이 마이그레이션됩니다. 시작 후 스크립트를 사용해서 인스턴스를 마이그레이션하려면 Google Cloud CLI 또는 REST API를 사용하여 PostStartupScriptOption 옵션을 지정합니다.
	Dataproc Hub	마이그레이션되지 않음. 수동으로 마이그레이션해야 합니다.

시작 후 스크립트 지정

시작 후 스크립트를 사용하는 사용자 관리형 노트북 인스턴스는 PostStartupScriptOption 옵션이 지정된 인스턴스로 마이그레이션되어야 합니다. 이 옵션을 사용하면 새 Vertex AI Workbench 인스턴스에서 시작 후 스크립트를 건너뛰거나 다시 실행할지 여부를 나타낼 수 있습니다.

Google Cloud 콘솔에서는 PostStartupScriptOption 옵션 지정이 지원되지 않습니다. 사용자 관리형 노트북 인스턴스를 마이그레이션할 때 PostStartupScriptOption 옵션을 지정하려면 Google Cloud CLI 또는 REST API를 사용해야 합니다.

시작하기 전에

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. Enable the Notebooks API.

   Enable the API

5. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

6. Make sure that billing is enabled for your Google Cloud project.

7. Enable the Notebooks API.

   Enable the API

8. 아직 사용자 관리형 노트북 인스턴스를 만들지 않은 경우 사용자 관리형 노트북 인스턴스를 만듭니다.

필요한 역할

사용자 계정에 사용자 관리형 노트북 인스턴스를 Vertex AI Workbench 인스턴스로 마이그레이션하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트에 대한 Notebooks 실행자(roles/notebooks.runner) IAM 역할을 사용자 계정에 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

이 사전 정의된 역할에는 사용자 관리형 노트북 인스턴스를 Vertex AI Workbench 인스턴스로 마이그레이션하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

사용자 관리형 노트북 인스턴스를 Vertex AI Workbench 인스턴스로 마이그레이션하려면 다음 권한이 필요합니다.

• notebooks.instances.create
• notebooks.instances.get

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

마이그레이션 전 검사

마이그레이션하기 전에 인스턴스를 나열하고 출력에 마이그레이션 경고나 오류가 있는지 확인하여 사용자 관리형 노트북 인스턴스의 마이그레이션 자격 요건을 확인합니다.

인스턴스 나열

아직 마이그레이션되지 않은 사용자 관리형 노트북 인스턴스를 나열하려면 migrated:false 필터와 함께 projects.locations.instances.list 메서드를 사용합니다. gcloud CLI 또는 REST API를 사용하여 나열할 수 있습니다.

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• LOCATION: 사용자 관리형 노트북 인스턴스가 있는 리전입니다. 또는 모든 리전의 인스턴스를 나열하려면 -를 사용합니다.

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances list --project=PROJECT_ID \
    --location=LOCATION --filter=migrated:false --format=default

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances list --project=PROJECT_ID `
    --location=LOCATION --filter=migrated:false --format=default

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances list --project=PROJECT_ID ^
    --location=LOCATION --filter=migrated:false --format=default

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• LOCATION: 사용자 관리형 노트북 인스턴스가 있는 리전입니다. 또는 모든 리전의 인스턴스를 나열하려면 -를 사용합니다.

HTTP 메서드 및 URL:

GET https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances?filter=migrated:false" | Select-Object -Expand Content

출력에서 경고 또는 오류 확인

마이그레이션 경고나 오류가 감지되면 projects.locations.instances.list 메서드 출력에 이 정보가 포함됩니다.

사용자 관리형 노트북 인스턴스 구성의 특정 구성요소가 Vertex AI Workbench 인스턴스의 동일한 사양으로 마이그레이션되지 않으면 경고가 표시됩니다. 예를 들어 사용자 관리형 노트북 인스턴스에서 지원되지 않는 가속기를 사용하는 경우 출력에 경고가 표시됩니다. 이 경우 가속기 없이 인스턴스가 마이그레이션됩니다. 마이그레이션 후에 가속기를 연결할 수 있습니다. 출력에서 경고를 검토하고 마이그레이션 도구의 기본 동작을 고려하여 마이그레이션 도구가 마이그레이션에 적합한지 여부를 평가합니다.

출력에 오류가 하나 이상 있으면 마이그레이션 도구를 사용하여 사용자 관리형 노트북 인스턴스를 마이그레이션할 수 없습니다. 인스턴스를 수동으로 마이그레이션해야 합니다.

마이그레이션 경고와 오류에 대한 자세한 내용은 InstanceMigrationEligibility 문서의 경고 및 오류를 참조하세요.

마이그레이션 도구를 사용하여 마이그레이션

Google Cloud 콘솔, gcloud CLI 또는 REST API를 사용하여 사용자 관리형 노트북 인스턴스를 마이그레이션할 수 있습니다.

콘솔

1. Google Cloud 콘솔에서 사용자 관리형 노트북 페이지로 이동합니다.

   사용자 관리형 노트북으로 이동

2. 마이그레이션 버튼을 클릭합니다.

3. 사용자 관리형 노트북을 인스턴스로 마이그레이션 페이지의 준비 탭에서 마이그레이션할 인스턴스를 선택합니다.

4. 이전을 클릭합니다.

5. 마이그레이션이 완료되면 인스턴스 페이지로 이동하여 새 Vertex AI Workbench 인스턴스를 봅니다.

   인스턴스로 이동

gcloud

아래의 명령어 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• LOCATION: 사용자 관리형 노트북 인스턴스가 있는 리전
• INSTANCE_ID: 사용자 관리형 노트북 인스턴스 ID
• POST_STARTUP_SCRIPT_OPTION: 선택사항: 시작 후 스크립트 옵션 중 하나

다음 명령어를 실행합니다.

Linux, macOS 또는 Cloud Shell

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances migrate RUNTIME_ID \
    --project=PROJECT_ID \
    --location=LOCATION \
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows(PowerShell)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances migrate RUNTIME_ID `
    --project=PROJECT_ID `
    --location=LOCATION `
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

Windows(cmd.exe)

참고: gcloud init 또는 gcloud auth login 및 gcloud config set project를 실행하여 Google Cloud CLI를 인증 및 프로젝트와 함께 초기화했는지 확인합니다.

gcloud notebooks instances migrate RUNTIME_ID ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --post-startup-script-option=POST_STARTUP_SCRIPT_OPTION

REST

요청 데이터를 사용하기 전에 다음을 바꿉니다.

• PROJECT_ID: 프로젝트 ID
• LOCATION: 사용자 관리형 노트북 인스턴스가 있는 리전
• INSTANCE_ID: 사용자 관리형 노트북 인스턴스 ID
• POST_STARTUP_SCRIPT_OPTION: 선택사항: 시작 후 스크립트 옵션 중 하나

HTTP 메서드 및 URL:

POST https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate

JSON 요청 본문:

{
  "postStartupScriptOption": (POST_STARTUP_SCRIPT_OPTION)
}

요청을 보내려면 다음 옵션 중 하나를 선택합니다.

curl

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하거나 gcloud CLI에 자동으로 로그인하는 Cloud Shell을 사용하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate"

PowerShell

참고: 다음 명령어는 gcloud init 또는 gcloud auth login을 실행하여 사용자 계정으로 gcloud CLI에 로그인했다고 가정합니다. gcloud auth list를 실행하면 현재 활성 계정을 확인할 수 있습니다.

요청 본문을 request.json 파일에 저장하고 다음 명령어를 실행합니다.

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://notebooks.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/instances/INSTANCE_ID:migrate" | Select-Object -Expand Content

수동으로 마이그레이션

수동으로 인스턴스를 Vertex AI Workbench 인스턴스로 마이그레이션하려면 다음 방법을 사용하는 것이 좋습니다.

• Cloud Storage 및 터미널 사용: 터미널을 사용하여 데이터와 파일을 Cloud Storage에 복사한 후 다른 인스턴스에 복사합니다.

• GitHub 사용: JupyterLab용 Git 확장 프로그램을 사용하여 데이터와 파일을 GitHub 저장소에 복사합니다.

이 가이드에서는 Cloud Storage 및 터미널을 사용하여 데이터와 파일을 마이그레이션하는 방법을 설명합니다.

요구사항

사용자 관리형 노트북 인스턴스에 대한 터미널 액세스 권한이 있어야 합니다. 인스턴스를 만들 때 터미널 액세스가 수동으로 설정됩니다. 인스턴스가 생성된 후에는 터미널 액세스 설정을 변경할 수 없습니다.

Cloud Storage 및 터미널을 사용하여 수동으로 마이그레이션

Cloud Storage 및 터미널을 사용하여 데이터와 파일을 새 Vertex AI Workbench 인스턴스로 마이그레이션하려면 다음을 수행합니다.

1. 사용자 관리형 노트북 인스턴스가 있는 동일한 프로젝트에서 Cloud Storage 버킷을 만듭니다.

2. 같은 프로젝트에서 데이터를 마이그레이션할 Vertex AI Workbench 인스턴스를 만듭니다. 이 인스턴스를 만들 때 다음을 수행합니다.

   • 터미널 액세스를 사용 설정합니다.
   • 머신 유형, 네트워크, 기타 특성을 필요에 맞게 지정합니다.

3. 사용자 관리형 노트북 인스턴스의 JupyterLab 인터페이스에서 File(파일) > New(새로 만들기) > Terminal(터미널)을 선택하여 터미널 창을 엽니다.

4. gcloud CLI를 사용하여 사용자 데이터를 Cloud Storage 버킷에 복사합니다. 다음 예시 명령어는 인스턴스의 /home/jupyter/ 디렉터리에 있는 모든 파일을 Cloud Storage 버킷의 디렉터리에 복사합니다.

   gcloud storage cp /home/jupyter/* gs://BUCKET_NAMEPATH --recursive
   

   다음을 바꿉니다.

   • BUCKET_NAME: Cloud Storage 버킷 이름
   • PATH: 파일을 복사할 디렉터리의 경로(예: /copy/jupyter/)

5. 새 Vertex AI Workbench 인스턴스의 JupyterLab 인터페이스에서 파일 > 새로 만들기 > 터미널을 선택하여 터미널 창을 엽니다.

6. gcloud CLI를 사용하여 데이터를 새 인스턴스에 복사합니다. 다음 예시 명령어는 Cloud Storage 디렉터리에 있는 모든 파일을 새 인스턴스의 /home/jupyter/ 디렉터리로 복사합니다.

   gcloud storage cp gs://BUCKET_NAMEPATH* /home/jupyter/
   

마이그레이션 확인

마이그레이션 후에도 사용자 관리형 노트북 인스턴스 원본은 이전과 동일하게 계속 작동합니다. 원본 인스턴스를 삭제하기 전에 마이그레이션이 성공했는지 확인합니다.

사용자 관리형 노트북 인스턴스 삭제

마이그레이션한 사용자 관리형 노트북 인스턴스가 필요하지 않으면 해당 인스턴스에 대한 추가 요금이 청구되지 않도록 삭제합니다.

1. Google Cloud 콘솔에서 사용자 관리형 노트북 페이지로 이동합니다.

   사용자 관리형 노트북으로 이동

2. 삭제할 인스턴스를 선택합니다.

3. 삭제를 클릭합니다. 창 크기에 따라 옵션 메뉴에 삭제 버튼이 있을 수 있습니다.

4. 삭제를 클릭하여 확인합니다.

문제 해결

마이그레이션 문제를 진단하고 해결하는 방법은 Vertex AI Workbench 문제 해결을 참조하세요.

다음 단계

• Vertex AI Workbench 인스턴스 자세히 알아보기