Esegui il deployment di un database vettoriale PostgreSQL su GKE

Autopilot Standard

---

Questo tutorial mostra come eseguire il deployment di un cluster di database vettoriale PostgreSQL su Google Kubernetes Engine (GKE).

PostgreSQL è dotato di una gamma di moduli ed estensioni che estendono la funzionalità del database. In questo tutorial, installi l'estensione pgvector su un cluster PostgreSQL esistente di cui è stato eseguito il deployment in GKE. L'estensione pgvector consente di archiviare i vettori nelle tabelle del database aggiungendo tipi di vettori a PostgreSQL. Pgvector fornisce anche ricerche di similarità eseguendo query SQL comuni.

Semplifichiamo l'implementazione dell'estensione PGvector eseguendo prima il deployment dell'operatore CloudnativePG, in quanto l'operatore fornisce una versione in bundle dell'estensione.

Questo tutorial è rivolto ad amministratori e architetti di piattaforme cloud, ML engineer e professionisti MLOps (DevOps) interessati al deployment di cluster di database PostgreSQL su GKE.

Obiettivi

In questo tutorial imparerai a:

• Esegui il deployment dell'infrastruttura GKE per PostgreSQL.
• Installa l'estensione pgvector sul cluster PostgreSQL di cui è stato eseguito il deployment su GKE.
• Esegui il deployment e configura l'operatore CloudNativePG PostgreSQL con Helm.
• Carica un set di dati demo ed esegui query di ricerca con Jupyter Notebook.

Costi

In questo documento utilizzi i seguenti componenti fatturabili di Google Cloud:

• GKE
• Google Cloud Managed Service for Prometheus

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il calcolatore prezzi.

I nuovi utenti di Google Cloud potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare l'addebito di ulteriori costi eliminando le risorse che hai creato. Per ulteriori informazioni, vedi Pulizia.

Prima di iniziare

In questo tutorial utilizzerai Cloud Shell per eseguire i comandi. Cloud Shell è un ambiente shell per la gestione delle risorse ospitate su Google Cloud. È preinstallato con gli strumenti a riga di comando Google Cloud CLI, kubectl, Helm e Terraform. Se non utilizzi Cloud Shell, devi installare Google Cloud CLI.

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.

Install the Google Cloud CLI.

Nota:se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

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

Install the Google Cloud CLI.

Nota:se hai installato gcloud CLI in precedenza, assicurati di avere l'ultima versione eseguendo gcloud components update.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere alla gcloud CLI con la tua identità federata.

Per inizializzare gcloud CLI, esegui questo comando:

gcloud init

Create or select a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

• Create a Google Cloud project:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID with a name for the Google Cloud project you are creating.

• Select the Google Cloud project that you created:

  gcloud config set project PROJECT_ID

  Replace PROJECT_ID with your Google Cloud project name.

Verify that billing is enabled for your Google Cloud project.

Enable the Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials APIs:

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

1. Grant roles to your user account. Run the following command once for each of the following IAM roles: 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

   Replace the following:

   • PROJECT_ID: your project ID.
   • USER_IDENTIFIER: the identifier for your user account—for example, [e-mail].
   • ROLE: the IAM role that you grant to your user account.

Configura l'ambiente

Per configurare l'ambiente con Cloud Shell:

1. Imposta le variabili di ambiente per il progetto, la regione e un prefisso della risorsa del cluster Kubernetes:

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

   • Sostituisci PROJECT_ID con l'ID del tuo progetto Google Cloud.

   Questo tutorial utilizza la regione us-central1.

2. Clona il repository del codice campione da GitHub:

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

3. Vai alla directory postgres-pgvector:

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

Crea l'infrastruttura del cluster

In questa sezione, esegui uno script Terraform per creare un cluster GKE regionale privato e a disponibilità elevata per eseguire il deployment del database PostgreSQL.

Puoi scegliere di eseguire il deployment di PostgreSQL utilizzando un cluster standard o Autopilot. Ognuno ha i suoi vantaggi e modelli di prezzi diversi.

Autopilot

Per eseguire il deployment dell'infrastruttura del cluster Autopilot, esegui questi comandi in 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 sostituisce le seguenti variabili in fase di runtime:

• GOOGLE_OAUTH_ACCESS_TOKEN utilizza il comando gcloud auth print-access-token per recuperare un token di accesso che autentica le interazioni con varie API Google Cloud
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX sono le variabili di ambiente definite nella sezione Configurare l'ambiente e assegnate alle nuove variabili pertinenti per il cluster Autopilot che stai creando.

Quando richiesto, digita yes.

Terraform crea le seguenti risorse:

• Una rete VPC personalizzata e una subnet privata per i nodi Kubernetes.
• Un router Cloud per accedere a internet tramite Network Address Translation (NAT).
• Un cluster GKE privato nella regione us-central1.
• Un ServiceAccount con autorizzazioni di logging e monitoraggio per il cluster.
• Configurazione di Google Cloud Managed Service per Prometheus per il monitoraggio e gli avvisi dei cluster.

L'output è simile al seguente:

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

Standard

Per eseguire il deployment dell'infrastruttura del cluster Standard, esegui questi comandi in 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 sostituisce le seguenti variabili in fase di runtime:

• GOOGLE_OAUTH_ACCESS_TOKEN utilizza il comando gcloud auth print-access-token per recuperare un token di accesso che autentica le interazioni con varie API Google Cloud.
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX sono le variabili di ambiente definite nella sezione Configura l'ambiente e assegnate alle nuove variabili pertinenti per il cluster Standard che stai creando.

Quando richiesto, digita yes. Potrebbero essere necessari diversi minuti prima che questi comandi vengano completati e che il cluster mostri lo stato Pronto.

Terraform crea le seguenti risorse:

• Una rete VPC personalizzata e una subnet privata per i nodi Kubernetes.
• Un router Cloud per accedere a internet tramite Network Address Translation (NAT).
• Un cluster GKE privato nella regione us-central1 con la scalabilità automatica abilitata (da uno a due nodi per zona).
• Un ServiceAccount con autorizzazioni di logging e monitoraggio per il cluster.
• Configurazione di Google Cloud Managed Service per Prometheus per il monitoraggio e gli avvisi dei cluster.

L'output è simile al seguente:

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

Connettiti al cluster

Configura kubectl per recuperare le credenziali e comunicare con il nuovo cluster GKE:

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

Esegui il deployment dell'operatore CloudNativePG

Esegui il deployment di CloudNativePG nel cluster Kubernetes utilizzando un grafico Helm:

1. Controlla la versione di Helm:

   helm version
   

   Aggiorna la versione se è precedente alla 3.13:

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

2. Aggiungi il repository del grafico Helm dell'operatore CloudNativePG:

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

3. Esegui il deployment dell'operatore CloudNativePG utilizzando lo strumento a riga di comando Helm:

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

   L'output è simile al seguente:

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

Esegui il deployment del database vettoriale PostgreSQL

In questa sezione, esegui il deployment del database vettoriale PostgreSQL.

1. Crea uno spazio dei nomi pg-ns per il database:

   kubectl create ns pg-ns
   

2. Applica il manifest per eseguire il deployment del cluster PostgreSQL. Il manifest del cluster attiva l'estensione pgvector.

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

   Il manifest postgreSQL_cluster.yaml descrive il deployment:

   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. Controlla lo stato del cluster:

   kubectl get cluster -n pg-ns --watch
   

   Attendi che l'output mostri lo stato Cluster in healthy state prima di passare al passaggio successivo.

Esegui query con un notebook Vertex AI Colab Enterprise

In questa sezione caricherai i vettori in una tabella PostgreSQL ed eseguirai query di ricerca semantica utilizzando la sintassi SQL.

Ti connetti al database PostgreSQL utilizzando Colab Enterprise. Utilizzi un modello di runtime dedicato per il deployment in postgres-vpc, in modo che il notebook possa comunicare con le risorse nel cluster GKE.

Per saperne di più su Vertex AI Colab Enterprise, consulta la documentazione di Colab Enterprise.

Creare un modello di runtime

Per creare un modello di runtime Colab Enterprise:

1. Nella console Google Cloud , vai alla pagina Modelli di runtime di Colab Enterprise e assicurati che il tuo progetto sia selezionato:

   Vai a Modelli di runtime

2. Fai clic su Nuovo modello. Viene visualizzata la pagina Crea nuovo modello di runtime.

3. Nella sezione Informazioni di base del runtime:

   • Nel campo Nome visualizzato, inserisci pgvector-connect.
   • Nell'elenco a discesa Regione, seleziona us-central1. Si tratta della stessa regione del cluster GKE.

4. Nella sezione Configura il calcolo:

   • Nell'elenco a discesa Tipo di macchina, seleziona e2-standard-2.
   • Nel campo Dimensione disco, inserisci 30.

5. Nella sezione Networking e sicurezza:

   • Nell'elenco a discesa Rete, seleziona la rete in cui si trova il cluster GKE.
   • Nell'elenco a discesa Subnet, seleziona una subnet corrispondente.
   • Deseleziona la casella di controllo Abilita l'accesso a internet pubblico.

6. Per completare la creazione del modello di runtime, fai clic su Crea. Il modello di runtime viene visualizzato nell'elenco della scheda Modelli di runtime.

Crea un runtime

Per creare un runtime Colab Enterprise:

1. Nell'elenco dei modelli di runtime per il modello appena creato, nella colonna Azioni, fai clic su e poi su Crea runtime. Viene visualizzato il riquadro Crea runtime di Vertex AI.

2. Per creare un runtime basato sul tuo modello, fai clic su Crea.

3. Nella scheda Runtime che si apre, attendi che lo stato diventi In buono stato.

Importa il notebook

Per importare il notebook in Colab Enterprise:

1. Vai alla scheda I miei notebook e fai clic su Importa. Viene visualizzato il riquadro Importa blocchi note.

2. In Origine importazione, seleziona URL.

3. In URL notebook, inserisci il seguente link:

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

4. Fai clic su Importa.

Connettiti al runtime ed esegui query

Per connetterti al runtime ed eseguire query:

1. Nel notebook, accanto al pulsante Connetti, fai clic su Opzioni di connessione aggiuntive. Viene visualizzato il riquadro Connetti al runtime di Vertex AI.

2. Seleziona Connetti a un runtime e poi Connetti a un runtime esistente.

3. Seleziona il runtime che hai avviato e fai clic su Connetti.

4. Per eseguire le celle del blocco note, fai clic sul pulsante Esegui cella accanto a ogni cella di codice.

Il blocco note contiene sia celle di codice sia testo che descrive ogni blocco di codice. L'esecuzione di una cella di codice esegue i relativi comandi e mostra un output. Puoi eseguire le celle in ordine o singole celle in base alle esigenze.

Esegui la pulizia

Per evitare che al tuo Account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial, elimina il progetto che contiene le risorse oppure mantieni il progetto ed elimina le singole risorse.

Elimina il progetto

Il modo più semplice per evitare la fatturazione è eliminare il progetto creato per questo tutorial.

Attenzione: l'eliminazione di un progetto ha i seguenti effetti:

• L'intero contenuto del progetto viene eliminato. Se hai utilizzato un progetto esistente per le attività descritte in questo documento, quando lo elimini, elimini anche tutto il lavoro che hai svolto nel progetto.
• Gli ID progetto personalizzati non sono più disponibili. Quando hai creato questo progetto, potresti aver creato un ID progetto personalizzato che vuoi utilizzare in futuro. Per conservare gli URL che utilizzano l'ID progetto, ad esempio un URL appspot.com, elimina le risorse selezionate all'interno del progetto anziché eliminare l'intero progetto.

Se intendi esplorare più architetture, tutorial o guide rapide, puoi riutilizzare i progetti ed evitare così di superare i limiti di quota.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se hai eliminato il progetto, la pulizia è completata. Se non hai eliminato il progetto, procedi con l'eliminazione delle singole risorse.

Elimina singole risorse

1. Imposta le variabili di ambiente.

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

2. Esegui il comando 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}
   

   Sostituisci FOLDER con gke-autopilot o gke-standard, a seconda del tipo di cluster GKE che hai creato.

   Quando richiesto, digita yes.

Passaggi successivi

• Scopri come eseguire il deployment di cluster PostgreSQL su GKE utilizzando l'operatore CloudNativePG.
• Scopri le best practice per il deployment dei database su GKE.
• Scopri le soluzioni per l'esecuzione di carichi di lavoro a uso intensivo di dati con GKE.