Déployer une base de données vectorielle PostgreSQL sur GKE

Autopilot Standard

Ce tutoriel vous explique comment déployer un cluster de base de données vectorielle PostgreSQL sur Google Kubernetes Engine (GKE).

PostgreSQL est fourni avec un éventail de modules et d'extensions qui étendent les fonctionnalités de la base de données. Dans ce tutoriel, vous allez installer l'extension pgvector sur un cluster PostgreSQL existant déployé dans GKE. L'extension Pgvector vous permet de stocker des vecteurs dans les tables de base de données en ajoutant des types de vecteurs à PostgreSQL. Pgvector propose également des recherches de similarités en exécutant des requêtes SQL courantes.

Nous simplifions le déploiement de l'extension PGvector en déployant d'abord l'opérateur CloudnativePG, car l'opérateur fournit une version groupée de l'extension.

Ce tutoriel est destiné aux administrateurs et architectes de plate-forme cloud, aux ingénieurs en ML et aux professionnels du MLOps (DevOps) qui souhaitent déployer des clusters de base de données PostgreSQL sur GKE.

Objectifs

Dans ce tutoriel, vous allez apprendre à effectuer les opérations suivantes :

• Déployer l'infrastructure GKE pour PostgreSQL.
• Installer l'extension pgvector sur le cluster PostgreSQL déployé sur GKE.
• Déployer et configurer l'opérateur CloudNativePG PostgreSQL avec Helm.
• Importer un ensemble de données de démonstration et exécuter des requêtes de recherche avec un notebook Jupyter.

Coûts

Dans ce document, vous utilisez les composants facturables suivants de Google Cloud :

• GKE
• Google Cloud Managed Service for Prometheus

Pour obtenir une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Une fois que vous avez terminé les tâches décrites dans ce document, supprimez les ressources que vous avez créées pour éviter que des frais vous soient facturés. Pour en savoir plus, consultez la section Effectuer un nettoyage.

Avant de commencer

Dans ce tutoriel, vous utilisez Cloud Shell pour exécuter des commandes. Cloud Shell est un environnement shell permettant de gérer les ressources hébergées sur Google Cloud. Il est doté des outils de ligne de commande préinstallés suivants : Google Cloud CLI, kubectl, Helm et Terraform. Si vous n'utilisez pas Cloud Shell, vous devez installer la Google Cloud CLI.

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 sans frais pour exécuter, tester et déployer des charges de travail.

Installez la Google Cloud CLI.

Remarque : Si vous avez déjà installé la gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez les API Cloud Resource Manager, Compute Engine, GKE et IAM Service Account Credentials :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com

Installez la Google Cloud CLI.

Remarque : Si vous avez déjà installé la gcloud CLI, assurez-vous que vous disposez de la dernière version en exécutant gcloud components update.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Pour initialiser la gcloud CLI, exécutez la commande suivante :

gcloud init

Créez ou sélectionnez un projet Google Cloud .

Rôles requis pour sélectionner ou créer un projet

• Sélectionnez un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique. Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
• Créer un projet : pour créer un projet, vous devez disposer du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

Remarque : Si vous ne comptez pas conserver les ressources créées dans cette procédure, créez un projet au lieu de sélectionner un projet existant. Après avoir suivi ces étapes, vous pouvez supprimer le projet. Cela entraîne la suppression de toutes les ressources qui lui sont associées.

• Créez un projet Google Cloud  :

  gcloud projects create PROJECT_ID

  Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.

• Sélectionnez le projet Google Cloud que vous avez créé :

  gcloud config set project PROJECT_ID

  Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez les API Cloud Resource Manager, Compute Engine, GKE et IAM Service Account Credentials :

Rôles requis pour activer les API

Pour activer les API, vous avez besoin du rôle IAM Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin), qui contient l'autorisation serviceusage.services.enable. Découvrez comment attribuer des rôles.

gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com

1. Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/compute.securityAdmin, roles/compute.viewer, roles/container.clusterAdmin, roles/container.admin, roles/iam.serviceAccountAdmin, roles/iam.serviceAccountUser

   gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

   Remplacez les éléments suivants :

   • PROJECT_ID : ID de votre projet
   • USER_IDENTIFIER : identifiant de votre compte d'utilisateur. Par exemple, [e-mail].
   • ROLE : rôle IAM que vous accordez à votre compte utilisateur.

Configurer votre environnement

Pour configurer votre environnement avec Cloud Shell, procédez comme suit :

1. Définissez des variables d'environnement pour votre projet, une région et un préfixe de ressource de cluster Kubernetes :

   export PROJECT_ID=PROJECT_ID
   export KUBERNETES_CLUSTER_PREFIX=postgres
   export REGION=us-central1
   

   • Remplacez PROJECT_ID par l'ID de votre projet Google Cloud.

   Ce tutoriel utilise la région us-central1.

2. Clonez l'exemple de dépôt de code depuis GitHub :

   git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
   

3. Accédez au répertoire postgres-pgvector :

   cd kubernetes-engine-samples/databases/postgres-pgvector
   

Créer l'infrastructure de votre cluster

Dans cette section, vous allez exécuter un script Terraform pour créer un cluster GKE régional, privé et à disponibilité élevée pour déployer votre base de données PostgreSQL.

Vous pouvez choisir de déployer PostgreSQL à l'aide d'un cluster Standard ou Autopilot. Chacun présente ses propres avantages et différents modèles de tarification.

Autopilot

Pour déployer l'infrastructure du cluster Autopilot, exécutez les commandes suivantes dans Cloud Shell :

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-autopilot init
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-autopilot apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE remplace les variables suivantes lors de l'exécution :

• GOOGLE_OAUTH_ACCESS_TOKEN utilise la commande gcloud auth print-access-token pour récupérer un jeton d'accès qui authentifie les interactions avec diverses API Google Cloud.
• PROJECT_ID, REGION et KUBERNETES_CLUSTER_PREFIX sont les variables d'environnement définies dans la section Configurer votre environnement et attribuées aux nouvelles variables pertinentes pour le cluster Autopilot que vous êtes en train de créer.

Lorsque vous y êtes invité, saisissez yes.

Terraform crée les ressources suivantes :

• Un réseau VPC personnalisé et un sous-réseau privé pour les nœuds Kubernetes
• Un routeur cloud pour accéder à Internet via la traduction d'adresse réseau (NAT)
• Un cluster GKE privé dans la région us-central1.
• Un ServiceAccount avec les autorisations de journalisation et de surveillance pour le cluster
• Configuration de Google Cloud Managed Service pour Prometheus pour la surveillance et les alertes relatives au cluster.

Le résultat ressemble à ce qui suit :

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

Standard

Pour déployer l'infrastructure du cluster standard, exécutez les commandes suivantes dans Cloud Shell :

export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-standard init
terraform -chdir=../postgresql-cloudnativepg/terraform/gke-standard apply \
-var project_id=${PROJECT_ID} \
-var region=${REGION} \
-var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}

GKE remplace les variables suivantes lors de l'exécution :

• GOOGLE_OAUTH_ACCESS_TOKEN utilise la commande gcloud auth print-access-token pour récupérer un jeton d'accès qui authentifie les interactions avec diverses API Google Cloud.
• PROJECT_ID, REGION et KUBERNETES_CLUSTER_PREFIX sont les variables d'environnement définies dans la section Configurer votre environnement et attribuées aux nouvelles variables pertinentes pour le cluster Standard que vous êtes en train de créer.

Lorsque vous y êtes invité, saisissez yes. L'exécution de ces commandes et le passage du cluster à l'état prêt peuvent prendre plusieurs minutes.

Terraform crée les ressources suivantes :

• Un réseau VPC personnalisé et un sous-réseau privé pour les nœuds Kubernetes
• Un routeur cloud pour accéder à Internet via la traduction d'adresse réseau (NAT)
• Un cluster GKE privé dans la région us-central1 avec l'autoscaling activé (un à deux nœuds par zone)
• Un ServiceAccount avec les autorisations de journalisation et de surveillance pour le cluster
• Configuration de Google Cloud Managed Service pour Prometheus pour la surveillance et les alertes relatives au cluster.

Le résultat ressemble à ce qui suit :

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

Se connecter au cluster

Configurez kubectl pour récupérer les identifiants et communiquer avec votre nouveau cluster GKE :

gcloud container clusters get-credentials \
    ${KUBERNETES_CLUSTER_PREFIX}-cluster --location ${REGION} --project ${PROJECT_ID}

Déployer l'opérateur CloudNativePG

Déployez CloudNativePG sur votre cluster Kubernetes à l'aide d'un chart Helm :

1. Vérifiez la version de Helm :

   helm version
   

   Mettez à jour la version si elle est antérieure à la version 3.13 :

   curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
   

2. Ajoutez le dépôt du chart Helm de l'opérateur CloudNativePG :

   helm repo add cnpg https://cloudnative-pg.github.io/charts
   

3. Déployez l'opérateur CloudNativePG à l'aide de l'outil de ligne de commande Helm :

   helm upgrade --install cnpg \
       --namespace cnpg-system \
       --create-namespace \
       cnpg/cloudnative-pg
   

   Le résultat ressemble à ce qui suit :

   Release "cnpg" does not exist. Installing it now.
   NAME: cnpg
   LAST DEPLOYED: Fri Oct 13 13:52:36 2023
   NAMESPACE: cnpg-system
   STATUS: deployed
   REVISION: 1
   TEST SUITE: None
   ...
   

Déployer la base de données vectorielle PostgreSQL

Dans cette section, vous allez déployer la base de données vectorielle PostgreSQL.

1. Créez un espace de noms pg-ns pour la base de données :

   kubectl create ns pg-ns
   

2. Appliquez le fichier manifeste pour déployer le cluster PostgreSQL. Le fichier manifeste du cluster active l'extension pgvector.

   kubectl apply -n pg-ns -f manifests/01-basic-cluster/postgreSQL_cluster.yaml
   

   Le fichier manifeste postgreSQL_cluster.yaml décrit le déploiement :

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: gke-pg-cluster
   spec:
     description: "Standard GKE PostgreSQL cluster"
     imageName: ghcr.io/cloudnative-pg/postgresql:16.2
     enableSuperuserAccess: true
     instances: 3
     startDelay: 300
     primaryUpdateStrategy: unsupervised
     postgresql:
       pg_hba:
         - host all all 10.48.0.0/20 md5
     bootstrap:
       initdb:
         postInitTemplateSQL:
           - CREATE EXTENSION IF NOT EXISTS vector;
         database: app
     storage:
       storageClass: premium-rwo
       size: 2Gi
     resources:
       requests:
         memory: "1Gi"
         cpu: "1000m"
       limits:
         memory: "1Gi"
         cpu: "1000m"
     affinity:
       enablePodAntiAffinity: true
       tolerations:
       - key: cnpg.io/cluster
         effect: NoSchedule
         value: gke-pg-cluster
         operator: Equal
       additionalPodAffinity:
         preferredDuringSchedulingIgnoredDuringExecution:
         - weight: 1
           podAffinityTerm:
             labelSelector:
               matchExpressions:
               - key: app.component
                 operator: In
                 values:
                 - "pg-cluster"
             topologyKey: topology.kubernetes.io/zone
     monitoring:
       enablePodMonitor: true

3. Vérifiez l'état du cluster :

   kubectl get cluster -n pg-ns --watch
   

   Attendez que le résultat affiche l'état Cluster in healthy state avant de passer à l'étape suivante.

Exécuter des requêtes avec un notebook Vertex AI Colab Enterprise

Dans cette section, vous allez importer des vecteurs dans une table PostgreSQL et exécuter des requêtes de recherche sémantique à l'aide de la syntaxe SQL.

Vous vous connectez à votre base de données PostgreSQL à l'aide de Colab Enterprise. Vous utilisez un modèle d'exécution dédié pour déployer le postgres-vpc. Le notebook peut ainsi communiquer avec les ressources du cluster GKE.

Pour en savoir plus sur Vertex AI Colab Enterprise, consultez la documentation Colab Enterprise.

Créer un modèle d'environnement d'exécution

Pour créer un modèle d'exécution Colab Enterprise :

1. Dans la console Google Cloud , accédez à la page Modèles d'exécution de Colab Enterprise et assurez-vous que votre projet est sélectionné :

   Accéder aux modèles d'exécution

2. Cliquez sur  Nouveau modèle. La page Créer un modèle d'exécution s'affiche.

3. Dans la section Principes de base de l'exécution :

   • Dans le champ Nom à afficher, saisissez pgvector-connect.
   • Dans la liste déroulante Région, sélectionnez us-central1. Il s'agit de la même région que votre cluster GKE.

4. Dans la section Configurer le calcul :

   • Dans la liste déroulante Type de machine, sélectionnez e2-standard-2.
   • Dans le champ Taille de disque disponible, saisissez 30.

5. Dans la section Mise en réseau et sécurité :

   • Dans la liste déroulante Réseau, sélectionnez le réseau sur lequel réside votre cluster GKE.
   • Dans la liste déroulante Sous-réseau, sélectionnez un sous-réseau correspondant.
   • Décochez la case Activer l'accès Internet public.

6. Pour terminer la création du modèle d'exécution, cliquez sur Créer. Votre modèle d'exécution apparaît dans la liste sur l'onglet Modèles d'exécution.

Créer un environnement d'exécution

Pour créer un environnement d'exécution Colab Enterprise :

1. Dans la liste des modèles d'exécution, dans la colonne Actions du modèle que vous venez de créer, cliquez sur , puis sur Créer une exécution. Le volet Créer un environnement d'exécution Vertex AI s'affiche.

2. Pour créer un environnement d'exécution basé sur votre modèle, cliquez sur Créer.

3. Dans l'onglet Environnements d'exécution qui s'ouvre, attendez que l'état passe à Sain.

Importer le notebook

Pour importer le notebook dans Colab Enterprise :

1. Accédez à l'onglet Mes notebooks, puis cliquez sur Importer. Le volet Importer des notebooks s'affiche.

2. Dans Source d'importation, sélectionnez URL.

3. Sous URL de notebook, saisissez le lien suivant :

   https://raw.githubusercontent.com/epam/kubernetes-engine-samples/internal_lb/databases/postgres-pgvector/manifests/02-notebook/vector-database.ipynb
   

4. Cliquez sur Importer.

Se connecter à l'environnement d'exécution et exécuter des requêtes

Pour vous connecter à l'environnement d'exécution et exécuter des requêtes :

1. Dans le notebook, à côté du bouton Connecter, cliquez sur Options de connexion supplémentaires. Le volet Se connecter à l'environnement d'exécution Vertex AI s'affiche.

2. Sélectionnez Se connecter à un environnement d'exécution, puis Se connecter à un environnement d'exécution existant.

3. Sélectionnez l'environnement d'exécution que vous avez lancé, puis cliquez sur Connect (Se connecter).

4. Pour exécuter les cellules du notebook, cliquez sur le bouton Exécuter la cellule à côté de chaque cellule de code.

Le notebook contient à la fois des cellules de code et du texte qui décrit chaque bloc de code. L'exécution d'une cellule de code exécute ses commandes et affiche un résultat. Vous pouvez exécuter les cellules dans l'ordre ou exécuter des cellules individuelles selon vos besoins.

Effectuer un nettoyage

Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.

Supprimer le projet

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

• Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
• Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Supprimer un projet Google Cloud  :

gcloud projects delete PROJECT_ID

Si vous avez supprimé le projet, le nettoyage est terminé. Si vous n'avez pas supprimé le projet, suivez les étapes ci-après afin de supprimer les ressources individuelles.

Supprimer des ressources individuelles

1. Définissez les variables d'environnement.

   export PROJECT_ID=${PROJECT_ID}
   export KUBERNETES_CLUSTER_PREFIX=postgres
   export REGION=us-central1
   

2. Exécutez la commande terraform destroy :

   export GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)
   terraform  -chdir=../postgresql-cloudnativepg/terraform/FOLDER destroy \
   -var project_id=${PROJECT_ID} \
   -var region=${REGION} \
   -var cluster_prefix=${KUBERNETES_CLUSTER_PREFIX}
   

   Remplacez FOLDER par gke-autopilot ou gke-standard, selon le type de cluster GKE que vous avez créé.

   Lorsque vous y êtes invité, saisissez yes.

Étapes suivantes

• Découvrez comment déployer des clusters PostgreSQL sur GKE à l'aide de l'opérateur CloudNativePG.
• Découvrez les bonnes pratiques pour le déploiement de bases de données sur GKE.
• Découvrez des solutions pour exécuter des charges de travail utilisant beaucoup de données avec GKE.