커스텀 컨테이너를 사용하여 인스턴스 만들기

이 페이지에서는 맞춤 컨테이너를 기반으로 Vertex AI Workbench 인스턴스를 만드는 방법을 설명합니다.

개요

Vertex AI Workbench 인스턴스는 Google에서 제공하는 기본 컨테이너에서 파생된 커스텀 컨테이너를 사용할 수 있도록 지원합니다. 이 기본 컨테이너를 수정하여 커스텀 컨테이너 이미지를 만들고 이 커스텀 컨테이너를 사용하여 Vertex AI Workbench 인스턴스를 만들 수 있습니다.

기본 컨테이너는 호스트 가상 머신 (VM)에서 컨테이너 최적화 OS로 구성됩니다. 기본 컨테이너는 사전 설치된 데이터 과학 패키지와 인스턴스를 Google Cloud와 통합할 수 있는 특정 구성을 제공합니다.

기본 컨테이너는 gcr.io/deeplearning-platform-release/workbench-container:latest에 있습니다.

제한사항

프로젝트를 계획할 때 다음 제한사항을 고려하세요.

• 커스텀 컨테이너는 Google에서 제공하는 기본 컨테이너(gcr.io/deeplearning-platform-release/workbench-container:latest)에서 파생되어야 합니다. 기본 컨테이너에서 파생되지 않은 컨테이너를 사용하면 호환성 문제가 발생할 위험이 증가하고 Vertex AI Workbench 인스턴스 사용을 지원하는 기능이 제한됩니다.

• Vertex AI Workbench 인스턴스에서 두 개 이상의 컨테이너를 사용하는 것은 지원되지 않습니다.

• 사용자 관리형 노트북과 관리형 노트북의 커스텀 컨테이너에 지원되는 메타데이터는 Vertex AI Workbench 인스턴스와 함께 사용될 때 다른 동작을 보일 수 있습니다.

• 맞춤 컨테이너를 호스팅하는 VM은 Container-Optimized OS에서 실행되므로 호스트 머신과 상호작용하는 방식이 제한됩니다. 예를 들어 Container-Optimized OS에는 패키지 관리자가 포함되어 있지 않습니다. 즉, 호스트에서 작동하는 패키지는 마운트가 있는 컨테이너에서 실행해야 합니다. 이는 관리형 노트북 인스턴스 및 사용자 관리 노트북 인스턴스에서 이전된 시작 후 스크립트에 영향을 미치며, 여기서 호스트 머신에는 Container-Optimized OS보다 훨씬 많은 도구가 포함되어 있습니다.

• Vertex AI Workbench 인스턴스는 커스텀 컨테이너를 실행하는 데 nerdctl(containerd CLI)를 사용합니다. 이는 이미지 스트리밍 서비스와의 호환성을 위해 필요합니다. 메타데이터 값을 사용하여 추가된 모든 컨테이너 매개변수는 nerdctl에서 지원하는 사항을 준수해야 합니다.

• Vertex AI Workbench 인스턴스는 Artifact Registry 또는 공개 컨테이너 저장소에서 가져오도록 구성됩니다. 비공개 저장소에서 가져오도록 인스턴스를 구성하려면 containerd에서 사용하는 사용자 인증 정보를 수동으로 구성해야 합니다.

시작하기 전에

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.

   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.

   Go to project selector

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

7. Enable the Notebooks API.

   Enable the API

필요한 역할

맞춤 컨테이너로 Vertex AI Workbench 인스턴스를 만드는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

• 사용자 계정의 메모장 실행자 (roles/notebooks.runner)
• Artifact Registry 저장소에서 이미지를 가져오려면 다음을 실행합니다. 서비스 계정의 Artifact Registry 리더 (roles/artifactregistry.reader)

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

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

커스텀 컨테이너 만들기

Vertex AI Workbench 인스턴스에서 사용할 커스텀 컨테이너를 만들려면 다음 단계를 따르세요.

1. Google에서 제공하는 기본 컨테이너 이미지(gcr.io/deeplearning-platform-release/workbench-container:latest)에서 파생된 파생 컨테이너를 만듭니다.

2. 컨테이너를 빌드하고 Artifact Registry에 푸시합니다. Vertex AI Workbench 인스턴스를 만들 때 컨테이너의 URI를 사용합니다. 예를 들어 URI는 gcr.io/PROJECT_ID/IMAGE_NAME와 같이 표시될 수 있습니다.

인스턴스 만들기

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 맞춤 컨테이너를 기반으로 Vertex AI Workbench 인스턴스를 만들 수 있습니다.

gcloud workbench instances create INSTANCE_NAME \
    --project=PROJECT_ID \
    --location=LOCATION \
    --container-repository=CUSTOM_CONTAINER_URL \
    --container-tag=latest \
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME `
    --project=PROJECT_ID `
    --location=LOCATION `
    --container-repository=CUSTOM_CONTAINER_URL `
    --container-tag=latest `
    --metadata=METADATA

gcloud workbench instances create INSTANCE_NAME ^
    --project=PROJECT_ID ^
    --location=LOCATION ^
    --container-repository=CUSTOM_CONTAINER_URL ^
    --container-tag=latest ^
    --metadata=METADATA

네트워크 구성 옵션

커스텀 컨테이너가 있는 Vertex AI Workbench 인스턴스는 일반 네트워크 옵션 외에도 Artifact Registry 서비스에 액세스할 수 있어야 합니다.

VPC의 공개 IP 액세스를 사용 중지한 경우 비공개 Google 액세스를 사용 설정했는지 확인합니다.

이미지 스트리밍 사용 설정

맞춤 컨테이너 호스트는 Google Kubernetes Engine (GKE)의 이미지 스트리밍과 상호작용하도록 프로비저닝됩니다. 그러면 컨테이너가 더 빠르게 가져오고 대규모 컨테이너가 GKE 원격 파일 시스템에 캐시되면 초기화 시간이 줄어듭니다.

이미지 스트리밍을 사용 설정하기 위한 요구사항은 요구사항을 참고하세요. Container File System API를 사용 설정하면 Vertex AI Workbench 인스턴스에서 이미지 스트리밍을 사용할 수 있는 경우가 많습니다.

Container File System API 사용 설정

호스트 VM에서 맞춤 컨테이너를 실행하는 방법

호스트 VM은 Docker를 사용하여 맞춤 컨테이너를 실행하는 대신 Kubernetes 네임스페이스 아래의 nerdctl를 사용하여 컨테이너를 로드하고 실행합니다. 이렇게 하면 Vertex AI Workbench에서 커스텀 컨테이너에 이미지 스트리밍을 사용할 수 있습니다.

# Runs the custom container.
sudo /var/lib/google/nerdctl/nerdctl --snapshotter=gcfs -n k8s.io run --name payload-container

설치 예시: 맞춤 기본 커널이 있는 맞춤 컨테이너

다음 예에서는 pip 패키지가 사전 설치된 새 커널을 만드는 방법을 보여줍니다.

1. 새 커스텀 컨테이너를 만듭니다.

   FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
   
   ENV MAMBA_ROOT_PREFIX=/opt/micromamba
   
   RUN micromamba create -n ENVIRONMENT_NAME -c conda-forge python=PYTHON_VERSION -y
   
   SHELL ["micromamba", "run", "-n", "ENVIRONMENT_NAME", "/bin/bash", "-c"]
   
   RUN micromamba install -c conda-forge pip -y
   RUN pip install PACKAGE
   RUN pip install ipykernel
   RUN python -m ipykernel install --prefix /opt/micromamba/envs/ENVIRONMENT_NAME --name ENVIRONMENT_NAME --display-name KERNEL_NAME
   # Creation of a micromamba kernel automatically creates a python3 kernel
   # that must be removed if it's in conflict with the new kernel.
   RUN rm -rf "/opt/micromamba/envs/ENVIRONMENT_NAME/share/jupyter/kernels/python3

2. Artifact Registry에 새 컨테이너를 추가합니다.

   gcloud auth configure-docker REGION-docker.pkg.dev
   docker build -t REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME .
   docker push REGION-docker.pkg.dev/PROJECT_ID/REPOSITORY_NAME/IMAGE_NAME:latest

3. 인스턴스를 만듭니다.

   gcloud workbench instances create INSTANCE_NAME  \
       --project=PROJECT_ID \
       --location=ZONE \
       --container-repository=REGION-docker.pkg.dev/PROJECT_ID/IMAGE_NAME \
       --container-tag=latest

커스텀 컨테이너의 영구 커널

Vertex AI Workbench 커스텀 컨테이너는 각 컨테이너 내의 /home/USER 디렉터리에만 데이터 디스크를 마운트하며 여기서 jupyter는 기본 사용자입니다. 즉, /home/USER 외부의 모든 변경사항은 일시적이며 다시 시작 후에는 유지되지 않습니다. 특정 커널에 설치된 패키지가 유지되어야 하는 경우 /home/USER 디렉터리에 커널을 만들 수 있습니다.

/home/USER 디렉터리에 커널을 만들려면 다음 단계를 따르세요.

1. micromamba 환경을 만듭니다.

   micromamba create -p /home/jupyter/ENVIRONMENT_NAME -c conda-forge python=3.11 -y
   micromamba activate ENVIRONMENT_NAME
   pip install ipykernel
   pip install -r ~/requirement.txt
   python -m ipykernel install --prefix "/home/jupyter/ENVIRONMENT_NAME" --display-name "Example Kernel"

2. 커널이 새로고침될 때까지 30초~1분 정도 기다립니다.

기본 컨테이너의 시작 업데이트

Vertex AI Workbench 인스턴스의 기본 컨테이너(us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest)는 /run_jupyter.sh를 실행하여 JupyterLab을 시작합니다.

파생 컨테이너에서 컨테이너의 시작을 수정하는 경우 /run_jupyter.sh를 추가하여 JupyterLab의 기본 구성을 실행해야 합니다.

다음은 Dockerfile을 수정하는 방법의 예입니다.

# DockerFile
FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

# Override the existing CMD directive from the base container.
CMD ["/startup_file.sh"]

# /startup_file.sh

echo "Running startup scripts"
...

/run_jupyter.sh

기본 컨테이너 내에서 JupyterLab 구성 업데이트

기본 컨테이너에서 JupyterLab 구성을 수정해야 하는 경우 다음을 실행해야 합니다.

• JupyterLab이 포트 8080으로 구성되어 있는지 확인합니다. 프록시 에이전트는 모든 요청을 포트 8080으로 전달하도록 구성되어 있으며, Jupyter 서버가 올바른 포트를 수신 대기하지 않으면 인스턴스에 프로비저닝 문제가 발생합니다.

• jupyterlab micromamba 환경에서 JupyterLab 패키지를 수정합니다. 커널 환경과 종속 항목 충돌이 없도록 JupyterLab 및 플러그인을 실행하는 별도의 패키지 환경을 제공합니다. JupyterLab 확장 프로그램을 추가로 설치하려면 jupyterlab 환경 내에 설치해야 합니다. 예를 들면 다음과 같습니다.

  # DockerFile
  FROM us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest
  RUN micromamba activate jupyterlab && \
    jupyter nbextension install nbdime

맞춤 컨테이너 메타데이터

Vertex AI Workbench 인스턴스에 적용할 수 있는 표준 메타데이터 목록 외에도 커스텀 컨테이너가 있는 인스턴스에는 페이로드 컨테이너의 인스턴스화를 관리하기 위한 다음 메타데이터가 포함됩니다.

커스텀 컨테이너 업그레이드

맞춤 컨테이너를 업데이트해야 하는 경우 custom-container-payload 메타데이터 값을 새 컨테이너 URI로 업데이트하면 됩니다. 컨테이너를 재시작할 때마다 custom-container-payload에 저장된 URI에서 컨테이너를 가져오려고 시도합니다.

:latest 태그를 사용하면 재시작할 때마다 기본 컨테이너가 업데이트됩니다. 아래 예시를 참조하세요.

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:latest

기본 컨테이너가 업데이트되지 않도록 하려면 버전을 지정하면 됩니다. 다음 예를 참고하세요.

custom-container-payload = us-docker.pkg.dev/deeplearning-platform-release/gcr.io/workbench-container:20240920-2200-rc0

진단도구 실행

진단 도구는 다양한 Vertex AI Workbench 서비스의 상태를 확인합니다. 자세한 내용은 진단 도구에서 실행하는 작업을 참고하세요.

커스텀 컨테이너를 사용하여 Vertex AI Workbench 인스턴스를 만들면 사용자가 실행할 수 있는 호스트 환경에서 진단 도구를 스크립트로 사용할 수 없습니다. 대신 바이너리로 컴파일되고 Container-Optimized OS 환경에서 진단 서비스를 실행하도록 빌드된 Google 런타임 컨테이너에 로드됩니다. Container-Optimized OS 개요를 참고하세요.

진단 도구를 실행하려면 다음 단계를 완료합니다.

1. ssh를 사용하여 Vertex AI Workbench 인스턴스에 연결합니다.

2. SSH 터미널에서 다음 명령어를 실행합니다.

   sudo docker exec diagnostic-service ./diagnostic_tool

3. 추가 명령어 옵션을 보려면 다음 명령어를 실행합니다.

   sudo docker exec diagnostic-service ./diagnostic_tool --help

진단 도구의 옵션에 관한 자세한 내용은 상태 모니터링 문서를 참고하세요.

REST API를 사용하여 진단 도구를 실행하려면 REST API 문서를 참고하세요.

인스턴스에 액세스

프록시 URL을 통해 인스턴스에 액세스할 수 있습니다.

인스턴스가 생성되고 활성 상태가 되면 gcloud CLI를 사용하여 프록시 URL을 가져올 수 있습니다.

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

• INSTANCE_NAME: Vertex AI Workbench 인스턴스의 이름
• PROJECT_ID: 프로젝트 ID입니다.
• LOCATION: 인스턴스가 있는 영역

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

gcloud workbench instances describe INSTANCE_NAME \
--project=PROJECT_ID \
--location=LOCATION | grep proxy-url

gcloud workbench instances describe INSTANCE_NAME `
--project=PROJECT_ID `
--location=LOCATION | grep proxy-url

gcloud workbench instances describe INSTANCE_NAME ^
--project=PROJECT_ID ^
--location=LOCATION | grep proxy-url

proxy-url: 7109d1b0d5f850f-dot-datalab-vm-staging.googleusercontent.com

describe 명령어는 프록시 URL을 반환합니다. 인스턴스에 액세스하려면 웹브라우저에서 프록시 URL을 엽니다.

명령줄에서 인스턴스를 설명하는 명령어에 대한 자세한 내용은 gcloud CLI 문서를 참고하세요.