Utiliser Terraform pour créer une instance de notebooks gérés par l'utilisateur

Dans ce tutoriel, vous allez apprendre à créer un fichier de configuration Terraform et à provisionner une instance de notebooks gérés par l'utilisateur dans Vertex AI en mode compte de service.

Utilisez les outils suivants pour suivre les étapes de ce tutoriel :

  • CLI Terraform : Terraform est préinstallé dans Cloud Shell. Vous n'avez pas besoin d'installer Terraform séparément pour pouvoir utiliser les commandes de CLI Terraform.

  • Éditeur Cloud Shell : utilisez l'éditeur Cloud Shell pour créer et gérer votre fichier de configuration Terraform, ainsi que pour gérer la structure des dossiers.

  • Terminal Cloud Shell : utilisez le terminal Cloud Shell pour exécuter les commandes de CLI Terraform suivantes, telles que terraform init, terraform plan, terraform apply et terraform destroy.

Avant de commencer

Avant de pouvoir créer l'infrastructure pour les ressources Vertex AI à l'aide de Terraform, configurez un projet Google Cloud et un environnement de développement. Cette section explique également comment activer l'API Vertex AI, que Terraform utilise pour interagir avec les ressources de votre projet.

  1. Connectez-vous à votre compte Google Cloud. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.

  2. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  3. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  4. Activez l'API Vertex AI

    Activer l'API

    5.

  5. Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.

    Accéder au sélecteur de projet

  6. Vérifiez que la facturation est activée pour votre projet Google Cloud.

  7. Activez l'API Vertex AI

    Activer l'API

    8.

Rôles requis

Si vous avez créé le projet, vous disposez du rôle IAM Propriétaire (roles/owner) sur le projet, qui inclut toutes les autorisations requises. Passez à la section suivante. Si vous n'êtes pas le créateur du projet, continuez dans cette section.

Pour vous assurer que votre compte utilisateur dispose des autorisations nécessaires pour créer une instance de notebooks gérés par l'utilisateur Vertex AI Workbench à l'aide de Terraform, demandez à votre administrateur d'attribuer les rôles IAM suivants à votre compte utilisateur sur le projet :

  • Administrateur Notebooks (roles/notebooks.admin) pour créer et supprimer des instances dans Vertex AI Workbench.
  • Utilisateur du compte de service (roles/iam.serviceAccountUser) pour exécuter des opérations en tant que compte de service. Ce tutoriel ne spécifie pas de compte de service. Par conséquent, votre instance de notebooks gérés par l'utilisateur utilise le compte de service Compute Engine par défaut.
  • Consommateur Service Usage (roles/serviceusage.serviceUsageConsumer) pour inspecter les états et les opérations des services, et les données de consommation de quotas et de facturation associées aux ressources du projet.

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

Votre administrateur peut également attribuer à votre compte utilisateur les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Créer la structure de dossiers et le fichier de configuration Terraform

  1. Dans la console Google Cloud, activez Cloud Shell.

    Activer Cloud Shell

    En bas de la fenêtre de la console Google Cloud, une session Cloud Shell démarre et affiche une invite de ligne de commande. Cloud Shell est un environnement shell dans lequel Google Cloud CLI est déjà installé, et dans lequel des valeurs sont déjà définies pour votre projet actuel. L'initialisation de la session peut prendre quelques secondes.

  1. Dans le terminal Cloud Shell, exécutez la commande suivante pour définir le répertoire d'accueil en tant que répertoire actif :
    cd
  2. Exécutez la commande suivante pour créer un dossier nommé terraform :
    mkdir terraform
  3. Lancer l'éditeur de code Cloud Shell
  4. Dans le volet Explorateur, effectuez un clic droit sur le dossier terraform, puis cliquez sur Nouveau fichier.
  5. Saisissez main.tf comme nom de fichier, puis cliquez sur OK.

Définir l'infrastructure dans le fichier de configuration Terraform

  1. Ouvrez le fichier main.tf dans l'éditeur Cloud Shell.

  2. Remplacez les espaces réservés PROJECT_NAME et LOCATION dans l'exemple de configuration Terraform suivant, puis copiez l'exemple dans le fichier main.tf :

    resource "google_project_service" "notebooks" {
  provider           = google
  service            = "notebooks.googleapis.com"
  disable_on_destroy = false
}

resource "google_notebooks_instance" "basic_instance" {
  project      = "PROJECT_ID"
  name         = "notebooks-instance-basic"
  provider     = google
  location     = "LOCATION"
  machine_type = "e2-medium"

  vm_image {
    project      = "deeplearning-platform-release"
    image_family = "tf-ent-2-9-cu113-notebooks"
  }

  depends_on = [
    google_project_service.notebooks
  ]
}

    • PROJECT_ID : saisissez l'ID de projet Google Cloud.

    • LOCATION : saisissez une région et une zone pour l'instance de notebooks gérés par l'utilisateur. Par exemple, us-west2-b. Pour obtenir les meilleures performances réseau, sélectionnez la région la plus proche de vous géographiquement. Découvrez les emplacements de notebooks gérés par l'utilisateur disponibles.

  3. Enregistrez le fichier main.tf.

Initialiser le répertoire de travail contenant le fichier de configuration Terraform

  1. Pour ouvrir le terminal Cloud Shell, cliquez sur Ouvrir le terminal dans la barre d'outils de l'éditeur Cloud Shell.

  2. Dans le terminal Cloud Shell, exécutez la commande suivante pour définir le dossier terraform comme répertoire de travail actuel :

    cd ~/terraform

  3. Exécutez la commande suivante :

    terraform init

  4. Terraform initialise le répertoire de travail. Le résultat suivant s'affiche :

    Terraform has been successfully initialized!

You may now begin working with Terraform. Try running "terraform plan" to see
any changes that are required for your infrastructure. All Terraform commands
should now work.

If you ever set or change modules or backend configuration for Terraform,
rerun this command to reinitialize your working directory. If you forget, other
commands will detect it and remind you to do so if necessary.

Prévisualiser le plan d'exécution basé sur la configuration Terraform

Le plan d'exécution Terraform indique les modifications que Terraform prévoit d'apporter à l'infrastructure et aux services Vertex AI;

Exécutez la commande suivante pour afficher le plan d'exécution Terraform.

terraform plan

Si vous êtes invité à autoriser Cloud Shell, cliquez sur Authorize (Autoriser). Cloud Shell utilise les identifiants de l'utilisateur par défaut lors de l'autorisation.

Un résultat semblable aux lignes suivantes s'affiche :

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  + create

Terraform will perform the following actions:

  # google_notebooks_instance.basic_instance will be created
  + resource "google_notebooks_instance" "basic_instance" {
      + create_time     = (known after apply)
      + id              = (known after apply)
      + labels          = (known after apply)
      + location        = "us-west2-b"
      + machine_type    = "e2-medium"
      + name            = "notebooks-instance-basic"
      + network         = (known after apply)
      + project         = "my_project"
      + proxy_uri       = (known after apply)
      + service_account = (known after apply)
      + state           = (known after apply)
      + subnet          = (known after apply)
      + update_time     = (known after apply)

      + shielded_instance_config {
          + enable_integrity_monitoring = (known after apply)
          + enable_secure_boot          = (known after apply)
          + enable_vtpm                 = (known after apply)
        }

      + vm_image {
          + image_family = "tf-ent-2-9-cu113-notebooks"
          + project      = "deeplearning-platform-release"
        }
    }

  # google_project_service.notebooks will be created
  + resource "google_project_service" "notebooks" {
      + disable_on_destroy = false
      + id                 = (known after apply)
      + project            = (known after apply)
      + service            = "notebooks.googleapis.com"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

  • my_project indique l'ID du projet Google Cloud que vous avez spécifié.

  • us-west2-b indique la région et la zone que vous avez spécifiées pour l'instance de notebooks gérés par l'utilisateur.

Appliquer les modifications proposées dans le plan d'exécution

  1. Exécutez la commande suivante pour appliquer les modifications du plan d'exécution à l'infrastructure Vertex AI et créer l'instance de notebooks gérés par l'utilisateur :

    terraform apply

  2. Un résultat semblable aux lignes suivantes s'affiche :

    Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following
symbols:
  + create

Terraform will perform the following actions:

  # google_notebooks_instance.basic_instance will be created
  + resource "google_notebooks_instance" "basic_instance" {
      + create_time     = (known after apply)
      + id              = (known after apply)
      + labels          = (known after apply)
      + location        = "us-west2-b"
      + machine_type    = "e2-medium"
      + name            = "notebooks-instance-basic"
      + network         = (known after apply)
      + project         = "my_project"
      + proxy_uri       = (known after apply)
      + service_account = (known after apply)
      + state           = (known after apply)
      + subnet          = (known after apply)
      + update_time     = (known after apply)

      + shielded_instance_config {
          + enable_integrity_monitoring = (known after apply)
          + enable_secure_boot          = (known after apply)
          + enable_vtpm                 = (known after apply)
        }

      + vm_image {
          + image_family = "tf-ent-2-9-cu113-notebooks"
          + project      = "deeplearning-platform-release"
        }
    }

  # google_project_service.notebooks will be created
  + resource "google_project_service" "notebooks" {
      + disable_on_destroy = false
      + id                 = (known after apply)
      + project            = (known after apply)
      + service            = "notebooks.googleapis.com"
    }

Plan: 2 to add, 0 to change, 0 to destroy.

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

    • my_project indique l'ID du projet Google Cloud que vous avez spécifié.

    • us-west2-b indique la région et la zone que vous avez spécifiées pour l'instance de notebooks gérés par l'utilisateur.

  3. Saisissez yes et appuyez sur Entrée. Un résultat semblable aux lignes suivantes s'affiche :

    Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Afficher votre instance de notebooks gérés par l'utilisateur

Dans Google Cloud Console, accédez à la page Notebooks gérés par l'utilisateur.

Accéder à la page Notebooks gérés par l'utilisateur

Le nouveau notebook nommé "notebooks-instance-basic" est répertorié dans le tableau. Notez que le provisionnement de la nouvelle instance de notebooks gérés par l'utilisateur peut prendre quelques minutes après l'exécution de terraform apply.

Nettoyer votre projet

Nettoyez les ressources Google Cloud que vous avez créées lors de ce tutoriel. Procédez comme suit pour éviter des frais inattendus engendrés par certaines ressources.

  1. Dans le terminal Cloud Shell, exécutez la commande suivante pour définir le dossier terraform comme répertoire de travail actuel :

    cd ~/terraform

  2. Pour supprimer les ressources Vertex AI que vous avez créées avec votre configuration Terraform, exécutez la commande suivante :

    terraform destroy

  3. Un résultat semblable aux lignes suivantes s'affiche :

    Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  - destroy

Terraform will perform the following actions:

  # google_notebooks_instance.basic_instance will be destroyed
  - resource "google_notebooks_instance" "basic_instance" {
      - create_time            = "2022-12-01T21:14:05.065893475Z" -> null
      - id                     = "projects/my_project/locations/us-west2-b/instances/notebooks-instance-basic" -> null
      - install_gpu_driver     = false -> null
      - labels                 = {
          - "goog-caip-notebook" = ""
        } -> null
      - location               = "us-west2-b" -> null
      - machine_type           = "e2-medium" -> null
      - name                   = "notebooks-instance-basic" -> null
      - network                = "http://www.googleapis.com/compute/v1/projects/my_project/global/networks/default" -> null
      - no_proxy_access        = false -> null
      - no_public_ip           = false -> null
      - project                = "my_project" -> null
      - service_account        = "[email protected]" -> null
      - service_account_scopes = [] -> null
      - state                  = "PROVISIONING" -> null
      - subnet                 = "http://www.googleapis.com/compute/v1/projects/my_project/regions/us-west2/subnetworks/default" -> null
      - tags                   = [] -> null
      - update_time            = "2022-12-01T21:14:19.048432376Z" -> null

      - shielded_instance_config {
          - enable_integrity_monitoring = true -> null
          - enable_secure_boot          = false -> null
          - enable_vtpm                 = true -> null
        }

      - vm_image {
          - image_family = "tf-ent-2-9-cu113-notebooks" -> null
          - project      = "deeplearning-platform-release" -> null
        }
    }

  # google_project_service.notebooks will be destroyed
  - resource "google_project_service" "notebooks" {
      - disable_on_destroy = false -> null
      - id                 = "my_project/notebooks.googleapis.com" -> null
      - project            = "my_project" -> null
      - service            = "notebooks.googleapis.com" -> null
    }

Plan: 0 to add, 0 to change, 2 to destroy.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value:

    • my_project indique l'ID du projet Google Cloud que vous avez spécifié.

    • us-west2-b indique la région et la zone que vous avez spécifiées pour l'instance de notebooks gérés par l'utilisateur.

  4. Saisissez yes et appuyez sur Entrée. Un résultat semblable aux lignes suivantes s'affiche :

    Destroy complete! Resources: 2 destroyed.

  5. Pour vérifier que l'instance de notebooks gérés par l'utilisateur a bien été supprimée, accédez à la page Notebooks gérés par l'utilisateur.

    Accéder à la page Notebooks gérés par l'utilisateur

  6. Lancer l'éditeur de code Cloud Shell

  7. Pour supprimer le dossier terraform et son contenu, effectuez un clic droit sur le dossier terraform dans le volet Explorateur, puis cliquez sur Supprimer.

  8. Lorsque vous y êtes invité, cliquez sur OK pour confirmer l'action.

Autres façons d'utiliser Terraform dans Vertex AI

Ce tutoriel vous a montré comment utiliser Terraform en créant un fichier de configuration unique et en provisionnant une infrastructure basée sur une ressource Terraform. Vous pouvez également utiliser Terraform dans les cas suivants :

  • Ajouter plusieurs ressources Terraform au même fichier de configuration Terraform. Pour obtenir la liste des ressources Terraform pour Vertex AI, consultez la section Ressources Terraform disponibles pour Vertex AI.

  • Créer une structure de répertoires comprenant plusieurs dossiers et fichiers de configuration Terraform. Par exemple, vous pouvez créer un dossier et un fichier de configuration Terraform distincts pour chaque type de ressource Terraform.

Étapes suivantes