Esegui il deployment di un database vettoriale PostgreSQL su GKE

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

PostgreSQL è dotato di una serie 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 ti consente di archiviare i vettori nelle tabelle di database aggiungendo tipi di vettori a PostgreSQL. Pgvector fornisce anche ricerche di similarità eseguendo query SQL comuni.

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

Questo tutorial è rivolto ad amministratori e architetti della piattaforma cloud, ML engineer e professionisti di MLOps (DevOps) interessati a eseguire il 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 in GKE.
  • Esegui il deployment e configura l'operatore PostgreSQL CloudNativePG con Helm.
  • Carica un set di dati di esempio ed esegui query di ricerca con Jupyter Notebook.

Costi

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

Per generare una stima dei costi in base all'utilizzo previsto, utilizza il Calcolatore prezzi. I nuovi Google Cloud utenti potrebbero avere diritto a una prova gratuita.

Al termine delle attività descritte in questo documento, puoi evitare la fatturazione continua eliminando le risorse che hai creato. Per ulteriori informazioni, consulta la sezione Pulizia.

Prima di iniziare

In questo tutorial utilizzerai Cloud Shell per eseguire 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.

  1. 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.
  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. To initialize the gcloud CLI, run the following command: 

    gcloud init

  5. Create or select a Google Cloud 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.

  6. Make sure that billing is enabled for your Google Cloud project.

  7. 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
  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. To initialize the gcloud CLI, run the following command: 

    gcloud init

  11. Create or select a Google Cloud 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.

  12. Make sure that billing is enabled for your Google Cloud project.

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

  14. 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 PROJECT_ID with your project ID.

    • Replace USER_IDENTIFIER with the identifier for your user account. For example, user:myemail@example.com.

    • Replace ROLE with each individual role.

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 il tuo Google Cloud ID progetto.

    Questo tutorial utilizza la regione us-central1.

  2. Clona il repository di codice di esempio 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 ad alta disponibilità 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 i seguenti 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 l'invio di avvisi per i 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 i seguenti 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 Configurare 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 di disponibilità.

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 l'invio di 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 tuo 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 di vettori PostgreSQL

In questa sezione, esegui il deployment del database di vettori 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.

Eseguire query con un blocco note Vertex AI Colab Enterprise

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

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

Per ulteriori informazioni su Vertex AI Colab Enterprise, consulta la documentazione di Colab Enterprise.

Creare un modello di runtime

Per creare un modello di runtime di Colab Enterprise:

  1. Nella console Google Cloud, vai alla pagina Modelli di runtime di Colab Enterprise e assicurati che il 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 Nozioni 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 Attiva 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.

Creare un runtime

Per creare un runtime di 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 in base al modello, fai clic su Crea.

  3. Nella scheda Runtime che si apre, attendi che lo stato passi a Intatto.

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

  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 Altre opzioni di connessione. 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 notebook 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 eseguire 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 che hai creato per questo tutorial.

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