Cette page a été traduite par l'API Cloud Translation.

Utiliser un script post-démarrage

Ce guide explique comment utiliser un script post-démarrage avec Colab Enterprise. Ce guide explique également comment définir des variables d'environnement à utiliser avec votre script post-démarrage.

Présentation

Vous pouvez utiliser un script post-démarrage pour effectuer des tâches après le processus de démarrage de votre environnement d'exécution Colab Enterprise. Par exemple, vous pouvez utiliser un script post-démarrage pour installer des packages spécifiques ou apporter des modifications spécifiques à la VM de votre environnement d'exécution.

Pour utiliser un script post-démarrage dans Colab Enterprise, vous devez le spécifier lorsque vous créez un modèle d'exécution. Ensuite, lorsque vous créez un environnement d'exécution basé sur ce modèle d'exécution, le script de post-démarrage s'exécute à la fin du processus de démarrage.

Emplacement du script post-démarrage

L'URI de votre script post-démarrage peut être l'un des suivants :

URI Cloud Storage : par exemple, gs://BUCKET_NAME/SCRIPT_FILE_NAME. Si votre script post-démarrage est stocké dans Cloud Storage, vous devez utiliser un environnement d'exécution avec les identifiants de l'utilisateur final activés. En effet, Colab Enterprise utilise vos identifiants utilisateur pour accéder au bucket Cloud Storage.
URL HTTPS : par exemple, https://example.com/FOLDER_NAME/SCRIPT_FILE_NAME. L'utilisation d'une URL HTTPS n'est pas acceptée lorsque vous créez votre modèle d'exécution à l'aide de la console Google Cloud .

Comportement du script post-démarrage

Vous pouvez spécifier le comportement de votre script post-démarrage. Consultez le tableau suivant :

Comportement	Description
Exécuter une fois (`RUN_ONCE`)	Par défaut. Colab Enterprise n'exécute le script de post-démarrage qu'une seule fois, lors de la création de l'environnement d'exécution.
Exécuter à chaque démarrage (`RUN_EVERY_START`)	À chaque démarrage, Colab Enterprise exécute le script post-démarrage. Par exemple, si l'arrêt en cas d'inactivité arrête l'environnement d'exécution, Colab Enterprise exécute à nouveau le script post-démarrage lorsque l'environnement d'exécution est redémarré.
Télécharger et exécuter à chaque démarrage (`DOWNLOAD_AND_RUN_EVERY_START`)	À chaque démarrage, Colab Enterprise télécharge à nouveau le script post-démarrage à partir de sa source, puis l'exécute.

Variables d'environnement

Vous pouvez spécifier des variables d'environnement dans votre modèle d'exécution et faire référence à ces variables dans votre script post-démarrage.

Par exemple, vous pouvez définir le projet de quota à l'aide d'une variable d'environnement. Vous pouvez définir votre projet de quota sur un ID de projet spécifique à l'aide de GOOGLE_CLOUD_QUOTA_PROJECT, une variable courante utilisée dans les bibliothèques clientes Google Cloud.

Pour utiliser un script post-démarrage avec des variables d'environnement, consultez Créer un modèle d'exécution avec un script post-démarrage et des variables d'environnement.

Suivre les modifications apportées aux scripts post-démarrage et les récupérer

Pour suivre les modifications apportées à votre script post-démarrage et permettre la récupération d'une version spécifique de ce script, stockez-le dans un bucket Cloud Storage avec la gestion des versions d'objets activée. La gestion des versions des objets conserve les objets supprimés en tant qu'objets archivés, avec des versions gérées, qui restent accessibles dans votre bucket jusqu'à leur suppression explicite.

Pour spécifier une version de votre script post-démarrage, ajoutez #GENERATION_NUMBER à l'URI de votre script post-démarrage lorsque vous créez votre modèle de runtime. Par exemple, gs://BUCKET_NAME/FOLDER_NAME/FILE_NAME.py#GENERATION_NUMBER. Pour en savoir plus sur la gestion des versions d'objets et les numéros de génération, consultez Gestion des versions d'objets.

Lorsque vous utilisez la console Google Cloud pour créer votre modèle d'environnement d'exécution, il n'est pas possible de spécifier un numéro de génération pour votre script post-démarrage.

Avant de commencer

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

Rôles requis

Pour obtenir les autorisations nécessaires pour créer un modèle d'exécution dans Colab Enterprise, demandez à votre administrateur de vous accorder le rôle IAM Administrateur Colab Enterprise (roles/aiplatform.colabEnterpriseAdmin) sur le projet. Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.

Un ou plusieurs des rôles requis incluent l'autorisation dataform.repositories.list. Les utilisateurs disposant de l'autorisation dataform.repositories.list ou du rôle Créateur de code (roles/dataform.codeCreator) dans un projet peuvent lister les noms des composants de code de ce projet à l'aide de l'API Dataform ou de l'interface de ligne de commande (CLI) Dataform. Les utilisateurs sans droits d'administrateur qui utilisent BigQuery Studio ne peuvent voir que les composants de code qu'ils ont créés ou qui ont été partagés avec eux.

Créer un modèle d'environnement d'exécution qui utilise un script post-démarrage

Pour créer un modèle d'exécution qui utilise un script post-démarrage, vous pouvez utiliser la console Google Cloud , la Google Cloud CLI ou l'API REST.

Console

Pour créer un modèle d'exécution qui utilise un script post-démarrage :

Dans la console Google Cloud , accédez à la page Modèles d'exécution de Colab Enterprise.

Accéder à la page "Modèles d'exécution"
Cliquez sur Nouveau modèle.

La boîte de dialogue Créer un modèle d'exécution s'affiche.
Dans la section Blocs de base de l'environnement d'exécution, saisissez un nom à afficher.
Dans le menu Région, sélectionnez la région dans laquelle vous souhaitez créer votre modèle d'exécution.
Dans la section Environnement, dans le champ Script post-démarrage, cliquez sur Parcourir, puis accédez à un script post-démarrage situé dans Cloud Storage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
Sous l'URL du script post-démarrage, sélectionnez le comportement de votre script post-démarrage. Le comportement par défaut est Exécuter une fois. Pour en savoir plus, consultez Comportement des scripts post-démarrage.
Dans la section Mise en réseau et sécurité, assurez-vous que l'option Activer les identifiants de l'utilisateur final est sélectionnée.
Renseignez le reste de la boîte de dialogue, puis cliquez sur Créer.

Votre modèle d'exécution apparaît dans la liste de l'onglet Modèles d'exécution.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

DISPLAY_NAME : nom à afficher de votre modèle d'exécution
PROJECT_ID : ID de votre projet
REGION : région dans laquelle vous souhaitez placer votre modèle d'exécution
POST_STARTUP_SCRIPT_URI : URI de votre script post-démarrage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
POST_STARTUP_SCRIPT_BEHAVIOR : comportement du script post-démarrage. Consultez la section Comportement du script post-démarrage.

Exécutez la commande suivante :

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

Pour en savoir plus sur la commande permettant de créer un modèle d'exécution à partir de la ligne de commande, consultez la documentation de la gcloud CLI.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

REGION : région dans laquelle vous souhaitez placer votre modèle d'exécution
PROJECT_ID : ID de votre projet
DISPLAY_NAME : nom à afficher de votre modèle d'exécution
POST_STARTUP_SCRIPT_URI : URI de votre script post-démarrage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
POST_STARTUP_SCRIPT_BEHAVIOR : comportement du script post-démarrage. Consultez la section Comportement du script post-démarrage.

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Si elle aboutit, le corps de la réponse contient une instance d'Operation.

Pour en savoir plus, reportez-vous à la. documentation de l'API REST notebookRuntimeTemplates.create.

Créer l'environnement d'exécution

Après avoir créé un modèle d'exécution qui utilise votre script post-démarrage, créez une exécution basée sur ce modèle d'exécution. L'environnement d'exécution démarre et le script post-démarrage s'exécute selon le comportement spécifié. Consultez Créer un environnement d'exécution.

Créer un modèle d'environnement d'exécution avec un script post-démarrage et des variables d'environnement

Pour créer un modèle d'exécution qui utilise un script post-démarrage et des variables d'environnement, vous pouvez utiliser la console Google Cloud , la Google Cloud CLI ou l'API REST.

Console

Pour créer un modèle d'exécution qui utilise un script post-démarrage et des variables d'environnement :

Dans la console Google Cloud , accédez à la page Modèles d'exécution de Colab Enterprise.

Accéder à la page "Modèles d'exécution"
Cliquez sur Nouveau modèle.

La boîte de dialogue Créer un modèle d'exécution s'affiche.
Dans la section Blocs de base de l'environnement d'exécution, saisissez un nom à afficher.
Dans le menu Région, sélectionnez la région dans laquelle vous souhaitez créer votre modèle d'exécution.
Dans la section Environnement, dans le champ Script post-démarrage, cliquez sur Parcourir, puis accédez à un script post-démarrage situé dans Cloud Storage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
Sous l'URL du script post-démarrage, sélectionnez le comportement de votre script post-démarrage. Le comportement par défaut est Exécuter une fois. Pour en savoir plus, consultez Comportement des scripts post-démarrage.
Pour ajouter une variable d'environnement, cliquez sur Ajouter une variable d'environnement, puis saisissez une paire Clé et Valeur. Pour ajouter d'autres variables d'environnement, répétez cette étape.
Dans la section Mise en réseau et sécurité, assurez-vous que l'option Activer les identifiants de l'utilisateur final est sélectionnée.
Renseignez le reste de la boîte de dialogue, puis cliquez sur Créer.

Votre modèle d'exécution apparaît dans la liste de l'onglet Modèles d'exécution.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

DISPLAY_NAME : nom à afficher de votre modèle d'exécution
PROJECT_ID : ID de votre projet
REGION : région dans laquelle vous souhaitez placer votre modèle d'exécution
POST_STARTUP_SCRIPT_URI : URI de votre script post-démarrage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
POST_STARTUP_SCRIPT_BEHAVIOR : comportement du script post-démarrage. Consultez la section Comportement du script post-démarrage.
ENV_VARIABLE_NAME : nom d'une variable d'environnement à définir pour votre environnement d'exécution
ENV_VARIABLE_VALUE : valeur de la variable d'environnement à définir pour votre environnement d'exécution

Exécutez la commande suivante :

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

Pour en savoir plus sur la commande permettant de créer un modèle d'exécution à partir de la ligne de commande, consultez la documentation de la gcloud CLI.

REST

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

REGION : région dans laquelle vous souhaitez placer votre modèle d'exécution
PROJECT_ID : ID de votre projet
DISPLAY_NAME : nom à afficher de votre modèle d'exécution
POST_STARTUP_SCRIPT_URI : URI de votre script post-démarrage. Pour en savoir plus, consultez Emplacement du script post-démarrage.
POST_STARTUP_SCRIPT_BEHAVIOR : comportement du script post-démarrage. Consultez la section Comportement du script post-démarrage.
ENV_VARIABLE_NAME : nom d'une variable d'environnement à définir pour votre environnement d'exécution
ENV_VARIABLE_VALUE : valeur de la variable d'environnement à définir pour votre environnement d'exécution

Méthode HTTP et URL :

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

Corps JSON de la requête :

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

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

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$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

Si elle aboutit, le corps de la réponse contient une instance d'Operation.

Pour en savoir plus, reportez-vous à la. documentation de l'API REST notebookRuntimeTemplates.create.

Créer l'environnement d'exécution

Limites

Tenez compte des limitations suivantes lorsque vous utilisez des scripts post-démarrage avec Colab Enterprise :

Pour créer un environnement d'exécution basé sur un modèle d'exécution qui inclut un script post-démarrage, vous devez être le propriétaire et le créateur de ce modèle d'exécution.
Il n'est pas possible de transmettre des variables d'environnement via le script post-démarrage. Vous devez spécifier les variables d'environnement dans la configuration du logiciel, comme décrit dans ce guide.
Pour utiliser un script post-démarrage situé dans Cloud Storage, vous devez utiliser un environnement d'exécution avec les identifiants de l'utilisateur final activés. De plus, vos identifiants utilisateur doivent avoir accès au bucket Cloud Storage.
Si vous utilisez la console Google Cloud pour créer votre modèle d'exécution, votre script post-démarrage doit se trouver dans Cloud Storage. Les scripts post-démarrage situés à d'autres emplacements ne sont pas compatibles lorsque vous créez votre modèle d'exécution à l'aide de la console Google Cloud .
Il n'est pas possible de spécifier un numéro de génération pour votre script post-démarrage lorsque vous utilisez la console Google Cloud pour créer votre modèle d'environnement d'exécution.

Étapes suivantes

Créez un environnement d'exécution et connectez-vous à celui-ci.
Pour gérer votre environnement d'exécution, consultez Gérer les environnements d'exécution.
Obtenez plus d'informations sur les environnements d'exécution et les modèles d'exécution.