Questa pagina è stata tradotta dall'API Cloud Translation.

Utilizza uno script post-avvio

Questa guida descrive come utilizzare uno script post-avvio con Colab Enterprise. Questa guida descrive anche come impostare le variabili di ambiente da utilizzare con lo script post-startup.

Panoramica

Puoi utilizzare uno script post-avvio per eseguire attività dopo il processo di avvio del runtime di Colab Enterprise. Ad esempio, puoi utilizzare uno script post-avvio per installare pacchetti specifici o apportare modifiche specifiche alla VM del runtime.

Per utilizzare uno script post-avvio in Colab Enterprise, devi specificare lo script post-avvio quando crei un modello di runtime. Poi, quando crei un runtime basato su quel modello di runtime, lo script post-avvio viene eseguito al termine del processo di avvio.

Posizione dello script post-avvio

L'URI dello script post-avvio può essere uno dei seguenti:

Un URI Cloud Storage: ad esempio, gs://BUCKET_NAME/SCRIPT_FILE_NAME. Se lo script post-avvio è archiviato in Cloud Storage, devi utilizzare un runtime con le credenziali dell'utente finale abilitate. Questo perché Colab Enterprise utilizza le tue credenziali utente per accedere al bucket Cloud Storage.
Un URL HTTPS: ad esempio, https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME. L'utilizzo di un URL HTTPS non è supportato durante la creazione del modello di runtime utilizzando la console Google Cloud .

Comportamento dello script post-avvio

Puoi specificare il comportamento dello script post-avvio. Consulta la seguente tabella:

Comportamento	Descrizione
Esegui una volta (`RUN_ONCE`)	Valore predefinito. Colab Enterprise esegue lo script post-avvio solo una volta, durante la creazione del runtime.
Esegui a ogni avvio (`RUN_EVERY_START`)	Dopo ogni avvio, Colab Enterprise esegue lo script post-avvio. Ad esempio, se l'arresto inattivo interrompe il runtime, Colab Enterprise esegue di nuovo lo script post-avvio quando il runtime viene riavviato.
Scarica ed esegui a ogni avvio (`DOWNLOAD_AND_RUN_EVERY_START`)	Dopo ogni avvio, Colab Enterprise scarica nuovamente lo script post-avvio dalla sua origine e lo esegue.

Variabili di ambiente

Puoi specificare le variabili di ambiente nel modello di runtime e fare riferimento a queste variabili nello script post-avvio.

Ad esempio, puoi impostare il progetto di quota utilizzando una variabile di ambiente. Puoi impostare il progetto di quota su un ID progetto specifico utilizzando GOOGLE_CLOUD_QUOTA_PROJECT, una variabile comune utilizzata nelle librerie client Google Cloud.

Per utilizzare uno script post-avvio con variabili di ambiente, consulta Crea un modello di runtime con uno script post-avvio e variabili di ambiente.

Monitorare le modifiche agli script post-avvio e recuperarli

Per monitorare le modifiche apportate allo script post-avvio e consentire il recupero di una versione specifica dello script post-avvio, archivialo in un bucket Cloud Storage con il controllo delle versioni degli oggetti abilitato. Il controllo delle versioni degli oggetti conserva gli oggetti eliminati come oggetti non aggiornati con controllo delle versioni che rimangono accessibili nel bucket finché non vengono rimossi esplicitamente.

Per specificare una versione dello script post-avvio, aggiungi #GENERATION_NUMBER all'URI dello script post-avvio quando crei il modello di runtime, ad esempio gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER. Per saperne di più sul controllo delle versioni degli oggetti e sui numeri di generazione, consulta Controllo delle versioni degli oggetti.

Quando utilizzi la console Google Cloud per creare il modello di runtime, la specifica di un numero di generazione per lo script post-avvio non è supportata.

Prima di iniziare

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.

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 (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 (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

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare un modello di runtime in Colab Enterprise, chiedi all'amministratore di concederti il ruolo IAM Amministratore Colab Enterprise (roles/aiplatform.colabEnterpriseAdmin) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Uno o più dei ruoli richiesti includono l'autorizzazione dataform.repositories.list. Gli utenti a cui è stata concessa l'autorizzazione dataform.repositories.list o il ruolo Creatore di codice (roles/dataform.codeCreator) in un progetto possono elencare i nomi degli asset di codice in quel progetto utilizzando l'API Dataform o l'interfaccia a riga di comando (CLI) Dataform. Gli utenti non amministratori che utilizzano BigQuery Studio possono visualizzare solo gli asset di codice che hanno creato o che sono stati condivisi con loro.

Crea un modello di runtime che utilizza uno script post-avvio

Per creare un modello di runtime che utilizzi uno script post-avvio, puoi utilizzare la console Google Cloud , Google Cloud CLI o l'API REST.

Console

Per creare un modello di runtime che utilizza uno script post-avvio, svolgi le seguenti operazioni:

Nella console Google Cloud , vai alla pagina Modelli di runtime di Colab Enterprise.

Vai a Modelli di runtime
Fai clic su Nuovo modello.

Viene visualizzata la finestra di dialogo Crea nuovo modello di runtime.
Nella sezione Nozioni di base sul runtime, inserisci un Nome visualizzato.
Nel menu Regione, seleziona la regione in cui vuoi il modello di runtime.
Nella sezione Ambiente, nel campo Script post-avvio, fai clic su Sfoglia e poi vai a uno script post-avvio in Cloud Storage. Per saperne di più, consulta la sezione Posizione script di avvio-avvio.
Nell'URL dello script post-avvio, seleziona il comportamento dello script post-avvio. Il comportamento predefinito è Esegui una volta. Per saperne di più, consulta Comportamento script di avvio-avvio.
Nella sezione Networking e sicurezza, assicurati che sia selezionata l'opzione Abilita credenziali utente finale.
Completa il resto della finestra di dialogo e poi fai clic su Crea.

Il modello di runtime viene visualizzato nell'elenco della scheda Modelli di runtime.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

DISPLAY_NAME: il nome visualizzato del modello di runtime.
PROJECT_ID: il tuo ID progetto.
REGION: la regione in cui vuoi il modello di runtime.
POST_STARTUP_SCRIPT_URI: l'URI dello script post-avvio. Per saperne di più, vedi Posizione script di avvio-avvio.
POST_STARTUP_SCRIPT_BEHAVIOR: il comportamento dello script post-avvio. Consulta Comportamento script di avvio-avvio.

Esegui questo comando:

Linux, macOS o 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

Per saperne di più sul comando per creare un template di runtime dalla riga di comando, consulta la documentazione di gcloud CLI.

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

REGION: la regione in cui vuoi il modello di runtime.
PROJECT_ID: il tuo ID progetto.
DISPLAY_NAME: il nome visualizzato del modello di runtime.
POST_STARTUP_SCRIPT_URI: l'URI dello script post-avvio. Per saperne di più, vedi Posizione script di avvio-avvio.
POST_STARTUP_SCRIPT_BEHAVIOR: il comportamento dello script post-avvio. Consulta Comportamento script di avvio-avvio.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando:

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login . Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando:

$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

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

Per ulteriori informazioni, consulta la documentazione dell'API REST di notebookRuntimeTemplates.create.

Crea il runtime

Dopo aver creato un modello di runtime che utilizza lo script post-avvio, crea un runtime basato su questo modello. Il runtime viene avviato e lo script post-avvio viene eseguito in base al comportamento specificato. Vedi Creare un runtime.

Crea un modello di runtime con uno script post-avvio e variabili di ambiente

Per creare un modello di runtime che utilizzi uno script post-avvio e variabili di ambiente, puoi utilizzare la console Google Cloud , Google Cloud CLI o l'API REST.

Console

Per creare un modello di runtime che utilizza uno script di post-avvio e variabili di ambiente, procedi nel seguente modo:

Nella console Google Cloud , vai alla pagina Modelli di runtime di Colab Enterprise.

Vai a Modelli di runtime
Fai clic su Nuovo modello.

Viene visualizzata la finestra di dialogo Crea nuovo modello di runtime.
Nella sezione Nozioni di base sul runtime, inserisci un Nome visualizzato.
Nel menu Regione, seleziona la regione in cui vuoi il modello di runtime.
Nella sezione Ambiente, nel campo Script post-avvio, fai clic su Sfoglia e poi vai a uno script post-avvio in Cloud Storage. Per saperne di più, consulta la sezione Posizione script di avvio-avvio.
Nell'URL dello script post-avvio, seleziona il comportamento dello script post-avvio. Il comportamento predefinito è Esegui una volta. Per saperne di più, consulta Comportamento script di avvio-avvio.
Per aggiungere una variabile di ambiente, fai clic su Aggiungi variabile di ambiente, quindi inserisci una coppia Chiave e Valore. Per aggiungere altre variabili di ambiente, ripeti questo passaggio.
Nella sezione Networking e sicurezza, assicurati che sia selezionata l'opzione Abilita credenziali utente finale.
Completa il resto della finestra di dialogo e poi fai clic su Crea.

Il modello di runtime viene visualizzato nell'elenco della scheda Modelli di runtime.

gcloud

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

DISPLAY_NAME: il nome visualizzato del modello di runtime.
PROJECT_ID: il tuo ID progetto.
REGION: la regione in cui vuoi il modello di runtime.
POST_STARTUP_SCRIPT_URI: l'URI dello script post-avvio. Per saperne di più, vedi Posizione script di avvio-avvio.
POST_STARTUP_SCRIPT_BEHAVIOR: il comportamento dello script post-avvio. Consulta Comportamento script di avvio-avvio.
ENV_VARIABLE_NAME: il nome di una variabile di ambiente da impostare per il runtime.
ENV_VARIABLE_VALUE: il valore della variabile di ambiente da impostare per il runtime.

Esegui questo comando:

Linux, macOS o 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

Per saperne di più sul comando per creare un template di runtime dalla riga di comando, consulta la documentazione di gcloud CLI.

REST

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

REGION: la regione in cui vuoi il modello di runtime.
PROJECT_ID: il tuo ID progetto.
DISPLAY_NAME: il nome visualizzato del modello di runtime.
POST_STARTUP_SCRIPT_URI: l'URI dello script post-avvio. Per saperne di più, vedi Posizione script di avvio-avvio.
POST_STARTUP_SCRIPT_BEHAVIOR: il comportamento dello script post-avvio. Consulta Comportamento script di avvio-avvio.
ENV_VARIABLE_NAME: il nome di una variabile di ambiente da impostare per il runtime.
ENV_VARIABLE_VALUE: il valore della variabile di ambiente da impostare per il runtime.

Metodo HTTP e URL:

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

Corpo JSON della richiesta:

{
  "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
  }
}

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando:

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

Salva il corpo della richiesta in un file denominato request.json, ed esegui questo comando:

$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

In caso di esito positivo, il corpo della risposta contiene un'istanza di Operation.

Per ulteriori informazioni, consulta la documentazione dell'API REST di notebookRuntimeTemplates.create.

Crea il runtime

Limitazioni

Tieni presenti le seguenti limitazioni quando utilizzi gli script post-avvio con Colab Enterprise:

Per creare un runtime basato su un modello di runtime che include uno script post-avvio, devi essere il proprietario e il creatore di questo modello di runtime.
Il passaggio di variabili di ambiente tramite lo script post-startup non è supportato. Devi specificare le variabili di ambiente nella configurazione del software come descritto in questa guida.
Per utilizzare uno script post-avvio che si trova in Cloud Storage, devi utilizzare un runtime con le credenziali dell'utente finale abilitate e le tue credenziali utente devono avere accesso al bucket Cloud Storage.
Se utilizzi la console Google Cloud per creare il modello di runtime, lo script post-startup deve trovarsi in Cloud Storage. Gli script post-avvio in altre posizioni non sono supportati durante la creazione del modello di runtime utilizzando la console Google Cloud .
La specifica di un numero di generazione per lo script post-avvio non è supportata quando utilizzi la console Google Cloud per creare il modello di runtime.

Passaggi successivi

Crea un runtime e connettiti.
Per gestire il runtime, vedi Gestisci runtime.
Scopri di più su runtime e modelli di runtime.