시작 후 스크립트 사용

이 가이드에서는 Colab Enterprise에서 시작 후 스크립트를 사용하는 방법을 설명합니다. 이 가이드에서는 시작 후 스크립트와 함께 사용할 환경 변수를 설정하는 방법도 설명합니다.

개요

시작 후 스크립트를 사용하여 Colab Enterprise 런타임의 시작 프로세스 후에 작업을 수행할 수 있습니다. 예를 들어 시작 후 스크립트를 사용하여 특정 패키지를 설치하거나 런타임의 VM에 특정 변경사항을 적용할 수 있습니다.

Colab Enterprise에서 시작 후 스크립트를 사용하려면 런타임 템플릿을 만들 때 시작 후 스크립트를 지정하세요. 그런 다음 해당 런타임 템플릿을 기반으로 런타임을 만들면 시작 프로세스가 끝날 때 시작 후 스크립트가 실행됩니다.

시작 후 스크립트 위치

시작 후 스크립트 URI는 다음 중 하나일 수 있습니다.

Cloud Storage URI: 예를 들면 gs://BUCKET_NAME/SCRIPT_FILE_NAME입니다. 시작 후 스크립트가 Cloud Storage에 저장된 경우 최종 사용자 인증 정보가 사용 설정된 런타임을 사용해야 합니다. Colab Enterprise는 사용자 인증 정보를 사용하여 Cloud Storage 버킷에 액세스하기 때문입니다.
HTTPS URL: 예를 들어 https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME입니다. Google Cloud 콘솔을 사용하여 런타임 템플릿을 만들 때는 HTTPS URL을 사용할 수 없습니다.

시작 후 스크립트 동작

시작 후 스크립트의 동작을 지정할 수 있습니다. 다음 표를 참고하세요.

동작	설명
한 번 실행 (`RUN_ONCE`)	기본값입니다. Colab Enterprise는 런타임 생성 중에 시작 후 스크립트를 한 번만 실행합니다.
시작할 때마다 실행 (`RUN_EVERY_START`)	시작할 때마다 Colab Enterprise는 시작 후 스크립트를 실행합니다. 예를 들어 유휴 상태 종료로 런타임이 중지되면 런타임이 다시 시작될 때 Colab Enterprise에서 시작 후 스크립트를 다시 실행합니다.
시작할 때마다 다운로드하고 실행 (`DOWNLOAD_AND_RUN_EVERY_START`)	시작할 때마다 Colab Enterprise는 소스에서 시작 후 스크립트를 다시 다운로드한 후 스크립트를 실행합니다.

환경 변수

런타임 템플릿에서 환경 변수를 지정하고 시작 후 스크립트에서 이러한 변수를 참조할 수 있습니다.

예를 들어 환경 변수를 사용하여 할당량 프로젝트를 설정할 수 있습니다. Google Cloud클라이언트 라이브러리에서 사용되는 일반적인 변수인 GOOGLE_CLOUD_QUOTA_PROJECT를 사용하여 할당량 프로젝트를 특정 프로젝트 ID로 설정할 수 있습니다.

환경 변수와 함께 시작 후 스크립트를 사용하려면 시작 후 스크립트 및 환경 변수를 사용하여 런타임 템플릿 만들기를 참고하세요.

시작 후 스크립트 변경사항 추적 및 복구

시작 후 스크립트의 변경사항을 추적하고 특정 버전의 시작 후 스크립트 복구를 사용 설정하려면 객체 버전 관리가 사용 설정된 Cloud Storage 버킷에 시작 후 스크립트를 저장하세요. 객체 버전 관리는 삭제된 객체를 버전이 지정된 이전 객체로 보존하며, 명시적으로 삭제될 때까지 버킷에서 액세스할 수 있는 상태로 유지됩니다.

시작 후 스크립트의 버전을 지정하려면 런타임 템플릿을 만들 때 시작 후 스크립트의 URI에 #GENERATION_NUMBER를 추가하세요(예: gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER). 객체 버전 관리 및 생성 번호에 관한 자세한 내용은 객체 버전 관리를 참고하세요.

Google Cloud 콘솔을 사용하여 런타임 템플릿을 만들 때는 시작 후 스크립트의 생성 번호를 지정할 수 없습니다.

시작하기 전에

Google Cloud 계정에 로그인합니다. Google Cloud를 처음 사용하는 경우 계정을 만들고 Google 제품의 실제 성능을 평가해 보세요. 신규 고객에게는 워크로드를 실행, 테스트, 배포하는 데 사용할 수 있는 $300의 무료 크레딧이 제공됩니다.

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

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

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Vertex AI, Dataform, and Compute Engine APIs.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the APIs

필요한 역할

Colab Enterprise에서 런타임 템플릿을 만드는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 Colab Enterprise 관리자(roles/aiplatform.colabEnterpriseAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

필수 역할 하나 이상에 dataform.repositories.list 권한이 포함되어 있습니다. 프로젝트에서 dataform.repositories.list 권한이나 코드 생성자(roles/dataform.codeCreator) 역할을 부여받은 사용자는 Dataform API 또는 Dataform 명령줄 인터페이스(CLI)를 사용하여 해당 프로젝트의 코드 애셋 이름을 나열할 수 있습니다. 관리자가 아닌 사용자가 BigQuery Studio를 사용할 때 직접 만들었거나 공유받은 코드 애셋만 볼 수 있습니다.

시작 후 스크립트를 사용하는 런타임 템플릿 만들기

시작 후 스크립트를 사용하는 런타임 템플릿을 만들려면 Google Cloud 콘솔, Google Cloud CLI 또는 REST API를 사용하면 됩니다.

콘솔

시작 후 스크립트를 사용하는 런타임 템플릿을 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Colab Enterprise 런타임 템플릿 페이지로 이동합니다.

런타임 템플릿으로 이동
새 템플릿을 클릭합니다.

새 런타임 템플릿 만들기 대화상자가 나타납니다.
런타임 기본사항 섹션에 표시 이름을 입력합니다.
리전 메뉴에서 런타임 템플릿을 사용할 리전을 선택합니다.
환경 섹션의 시작 후 스크립트 필드에서 찾아보기를 클릭한 다음 Cloud Storage에 있는 시작 후 스크립트로 이동합니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
시작 후 스크립트 URL에서 시작 후 스크립트의 동작을 선택합니다. 기본 동작은 한 번 실행입니다. 자세한 내용은 시작 후 스크립트 동작을 참조하세요.
네트워킹 및 보안 섹션에서 최종 사용자 인증 정보 사용 설정이 선택되어 있는지 확인합니다.
대화상자의 나머지 부분을 완료한 후 만들기를 클릭합니다.

런타임 템플릿이 런타임 템플릿 탭의 목록에 나타납니다.

gcloud

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

DISPLAY_NAME: 런타임 템플릿의 표시 이름입니다.
PROJECT_ID: 프로젝트 ID입니다.
REGION: 런타임 템플릿을 배치할 리전입니다.
POST_STARTUP_SCRIPT_URI: 시작 후 스크립트의 URI입니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
POST_STARTUP_SCRIPT_BEHAVIOR: 시작 후 스크립트의 동작입니다. 시작 후 스크립트 동작을 참고하세요.

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

Linux, macOS 또는 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows(PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

Windows(cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR

명령줄에서 런타임 템플릿을 만드는 명령어에 대한 자세한 내용은 gcloud CLI 문서를 참조하세요.

REST

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

REGION: 런타임 템플릿을 배치할 리전입니다.
PROJECT_ID: 프로젝트 ID입니다.
DISPLAY_NAME: 런타임 템플릿의 표시 이름입니다.
POST_STARTUP_SCRIPT_URI: 시작 후 스크립트의 URI입니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
POST_STARTUP_SCRIPT_BEHAVIOR: 시작 후 스크립트의 동작입니다. 시작 후 스크립트 동작을 참고하세요.

HTTP 메서드 및 URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

JSON 요청 본문:

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

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

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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

요청이 성공하면 응답 본문에 Operation의 인스턴스가 포함됩니다.

자세한 내용은notebookRuntimeTemplates.create REST API 문서를 참조하세요.

런타임 만들기

시작 후 스크립트를 사용하는 런타임 템플릿을 만든 후 해당 런타임 템플릿을 기반으로 런타임을 만듭니다. 런타임이 시작되고 지정된 동작에 따라 시작 후 스크립트가 실행됩니다. 런타임 만들기를 참고하세요.

시작 후 스크립트 및 환경 변수를 사용하여 런타임 템플릿 만들기

시작 후 스크립트와 환경 변수를 사용하는 런타임 템플릿을 만들려면 Google Cloud 콘솔, Google Cloud CLI 또는 REST API를 사용하면 됩니다.

콘솔

시작 후 스크립트와 환경 변수를 사용하는 런타임 템플릿을 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 Colab Enterprise 런타임 템플릿 페이지로 이동합니다.

런타임 템플릿으로 이동
새 템플릿을 클릭합니다.

새 런타임 템플릿 만들기 대화상자가 나타납니다.
런타임 기본사항 섹션에 표시 이름을 입력합니다.
리전 메뉴에서 런타임 템플릿을 사용할 리전을 선택합니다.
환경 섹션의 시작 후 스크립트 필드에서 찾아보기를 클릭한 다음 Cloud Storage에 있는 시작 후 스크립트로 이동합니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
시작 후 스크립트 URL에서 시작 후 스크립트의 동작을 선택합니다. 기본 동작은 한 번 실행입니다. 자세한 내용은 시작 후 스크립트 동작을 참고하세요.
환경 변수를 추가하려면 환경 변수 추가를 클릭한 후 키 및 값 쌍을 입력합니다. 환경 변수를 더 추가하려면 이 단계를 반복합니다.
네트워킹 및 보안 섹션에서 최종 사용자 인증 정보 사용 설정이 선택되어 있는지 확인합니다.
대화상자의 나머지 부분을 완료한 후 만들기를 클릭합니다.

런타임 템플릿이 런타임 템플릿 탭의 목록에 나타납니다.

gcloud

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

DISPLAY_NAME: 런타임 템플릿의 표시 이름입니다.
PROJECT_ID: 프로젝트 ID입니다.
REGION: 런타임 템플릿을 배치할 리전입니다.
POST_STARTUP_SCRIPT_URI: 시작 후 스크립트의 URI입니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
POST_STARTUP_SCRIPT_BEHAVIOR: 시작 후 스크립트의 동작입니다. 시작 후 스크립트 동작을 참고하세요.
ENV_VARIABLE_NAME: 런타임에 설정할 환경 변수의 이름입니다.
ENV_VARIABLE_VALUE: 런타임에 설정할 환경 변수의 값입니다.

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

Linux, macOS 또는 Cloud Shell

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" \
    --project=PROJECT_ID \
    --region=REGION \
    --machine-type=e2-standard-4 \
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI \
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR \
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows(PowerShell)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" `
    --project=PROJECT_ID `
    --region=REGION `
    --machine-type=e2-standard-4 `
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI `
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR `
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

Windows(cmd.exe)

gcloud colab runtime-templates create --display-name="DISPLAY_NAME" ^
    --project=PROJECT_ID ^
    --region=REGION ^
    --machine-type=e2-standard-4 ^
    --post-startup-script-url=POST_STARTUP_SCRIPT_URI ^
    --post-startup-script-behavior=POST_STARTUP_SCRIPT_BEHAVIOR ^
    --set-env-vars=ENV_VARIABLE_NAME=ENV_VARIABLE_VALUE

명령줄에서 런타임 템플릿을 만드는 명령어에 대한 자세한 내용은 gcloud CLI 문서를 참조하세요.

REST

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

REGION: 런타임 템플릿을 배치할 리전입니다.
PROJECT_ID: 프로젝트 ID입니다.
DISPLAY_NAME: 런타임 템플릿의 표시 이름입니다.
POST_STARTUP_SCRIPT_URI: 시작 후 스크립트의 URI입니다. 자세한 내용은 시작 후 스크립트 위치를 참고하세요.
POST_STARTUP_SCRIPT_BEHAVIOR: 시작 후 스크립트의 동작입니다. 시작 후 스크립트 동작을 참고하세요.
ENV_VARIABLE_NAME: 런타임에 설정할 환경 변수의 이름입니다.
ENV_VARIABLE_VALUE: 런타임에 설정할 환경 변수의 값입니다.

HTTP 메서드 및 URL:

POST https://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates

JSON 요청 본문:

{
  "displayName": "DISPLAY_NAME",
  "machineSpec": {
    "machineType": "e2-standard-4"
  },
  softwareConfig: {
    postStartupScriptConfig: {
      postStartupScriptUrl: "POST_STARTUP_SCRIPT_URI",
      postStartupScriptBehavior: "POST_STARTUP_SCRIPT_BEHAVIOR"
    },
    "env": [
      {
        "name": "ENV_VARIABLE_NAME",
        "value": "ENV_VARIABLE_VALUE"
      }
    ]
  },
  "networkSpec": {
    "enableInternetAccess": true
  }
}

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

curl

요청 본문을 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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates"

PowerShell

요청 본문을 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://REGION-aiplatform.googleapis.com/v1beta1/projects/PROJECT_ID/locations/REGION/notebookRuntimeTemplates" | Select-Object -Expand Content

요청이 성공하면 응답 본문에 Operation의 인스턴스가 포함됩니다.

자세한 내용은notebookRuntimeTemplates.create REST API 문서를 참조하세요.

런타임 만들기

권장사항

Colab Enterprise에서 시작 후 스크립트를 사용할 때는 다음 권장사항을 고려하세요.

런타임 템플릿에 대한 액세스 제어: 시작 후 스크립트 구성이 원치 않는 방식으로 변경되지 않도록 IAM 역할 및 권한을 사용하여 런타임 템플릿을 만들고 업데이트할 수 있는 사용자를 제어합니다.
스크립트에 대한 액세스 제어: 시작 후 스크립트 파일이 원치 않는 방식으로 변경되지 않도록 하려면 IAM 역할과 권한을 사용하여 스크립트가 저장된 Cloud Storage 버킷에 대한 액세스를 제어하세요.
객체 버전 관리 사용: 시작 후 스크립트의 변경사항을 추적하고 런타임 템플릿에서 특정 버전의 스크립트를 사용하도록 하려면 객체 버전 관리가 사용 설정된 Cloud Storage 버킷에 시작 후 스크립트를 저장하세요. 그런 다음 런타임 템플릿을 만들 때 스크립트 경로에 생성 번호를 포함합니다. 예를 들면 gs://BUCKET_NAME/OBJECT_NAME1#GENERATION_NUMBER1입니다. 자세한 내용은 시작 후 스크립트 변경사항 추적 및 복구를 참고하세요.
데이터 무단 반출 방지: 조직에서 필요한 경우 VPC 서비스 제어를 사용하여 데이터 무단 반출을 방지할 수 있습니다.

제한사항

Colab Enterprise에서 시작 후 스크립트를 사용할 때는 다음 제한사항을 고려하세요.

시작 후 스크립트와 EUC가 사용 설정된 런타임 템플릿을 기반으로 런타임을 만들려면 해당 런타임의 소유자여야 합니다. 예를 들어 관리자는 REST API를 사용하여 다른 사용자의 시작 후 스크립트를 사용하는 런타임을 만들 수 없습니다.
시작 후 스크립트를 통해 환경 변수를 전달하는 것은 지원되지 않습니다. 이 가이드에 설명된 대로 소프트웨어 구성에서 환경 변수를 지정해야 합니다.
Cloud Storage에 있는 시작 후 스크립트를 사용하려면 최종 사용자 인증 정보가 사용 설정된 런타임을 사용해야 하며 사용자 인증 정보에 Cloud Storage 버킷에 대한 액세스 권한이 있어야 합니다.
Google Cloud 콘솔을 사용하여 런타임 템플릿을 만드는 경우 시작 후 스크립트가 Cloud Storage에 있어야 합니다. Google Cloud 콘솔을 사용하여 런타임 템플릿을 만들 때는 다른 위치의 시작 후 스크립트가 지원되지 않습니다.
Google Cloud 콘솔을 사용하여 런타임 템플릿을 만들 때는 시작 후 스크립트의 생성 번호를 지정할 수 없습니다.

다음 단계

런타임을 만들고 연결합니다.
런타임을 관리하려면 런타임 관리를 참조하세요.
런타임 및 런타임 템플릿을 자세히 알아봅니다.