Implementa una base de datos vectorial de PostgreSQL en GKE.


En este instructivo, se muestra cómo implementar un clúster de base de datos vectoriales PostgreSQL en Google Kubernetes Engine (GKE).

PostgreSQL viene con una variedad de módulos y extensiones que extienden la funcionalidad de la base de datos. En este instructivo, instalarás la extensión pgvector en un clúster de PostgreSQL existente implementado en GKE. La extensión Pgvector te permite almacenar vectores en las tablas de la base de datos con la adición de tipos de vectores a PostgreSQL. Pgvector también proporciona búsquedas de similitud con la ejecución de consultas en SQL comunes.

Simplificamos la implementación de la extensión PGvector primero con la implementación del operador CloudnativePG, ya que proporciona una versión empaquetada de la extensión.

Este instructivo está dirigido a administradores y arquitectos de Cloud Platform, ingenieros del AA y profesionales de MLOps (DevOps) interesados en implementar clústeres de bases de datos de PostgreSQL en GKE.

Objetivos

En este instructivo, aprenderás a realizar lo siguiente:

  • Implementar la infraestructura de GKE para PostgreSQL.
  • Instala la extensión pgvector en el clúster de PostgreSQL implementado en GKE.
  • Implementa y configura el operador de CloudNativePG PostgreSQL con Helm.
  • Sube un conjunto de datos de demostración y ejecuta búsquedas con el notebook de Jupyter.

Costos

En este documento, usarás los siguientes componentes facturables de Google Cloud:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios. Es posible que los usuarios nuevos de Google Cloud califiquen para obtener una prueba gratuita.

Cuando finalices las tareas que se describen en este documento, puedes borrar los recursos que creaste para evitar que continúe la facturación. Para obtener más información, consulta Cómo realizar una limpieza.

Antes de comenzar

En este instructivo, usarás Cloud Shell para ejecutar comandos. Cloud Shell es un entorno de shell que se usa para administrar recursos alojados en Google Cloud. Viene preinstalado con las herramientas de línea de comando de Google Cloud CLI, kubectl, Helm y Terraform. Si no usas Cloud Shell, debes instalar Google Cloud CLI.

  1. Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
  2. Instala Google Cloud CLI.
  3. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init
  4. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  5. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  6. Habilita las APIs de Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials:

    gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com
  7. Instala Google Cloud CLI.
  8. Para inicializar la CLI de gcloud, ejecuta el siguiente comando:

    gcloud init
  9. Crea o selecciona un proyecto de Google Cloud.

    • Crea un proyecto de Google Cloud:

      gcloud projects create PROJECT_ID

      Reemplaza PROJECT_ID por un nombre para el proyecto de Google Cloud que estás creando.

    • Selecciona el proyecto de Google Cloud que creaste:

      gcloud config set project PROJECT_ID

      Reemplaza PROJECT_ID por el nombre del proyecto de Google Cloud.

  10. Asegúrate de que la facturación esté habilitada para tu proyecto de Google Cloud.

  11. Habilita las APIs de Cloud Resource Manager, Compute Engine, GKE, and IAM Service Account Credentials:

    gcloud services enable cloudresourcemanager.googleapis.com compute.googleapis.com container.googleapis.com iamcredentials.googleapis.com
  12. Otorga roles a tu Cuenta de Google. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: 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:EMAIL_ADDRESS" --role=ROLE
    • Reemplaza PROJECT_ID con el ID del proyecto.
    • Reemplaza EMAIL_ADDRESS por tu dirección de correo electrónico.
    • Reemplaza ROLE por cada rol individual.

Configura tu entorno

Para configurar tu entorno con Cloud Shell, sigue estos pasos:

  1. Configura las variables de entorno del proyecto, la región y el prefijo de recursos del clúster de Kubernetes:

    export PROJECT_ID=PROJECT_ID
    export KUBERNETES_CLUSTER_PREFIX=postgres
    export REGION=us-central1
    
    • Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

    En este instructivo, se usa la región us-central1.

  2. Clona el repositorio de código de muestra de GitHub:

    git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples
    
  3. Navega al directorio postgres-pgvector:

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

Crea la infraestructura del clúster

En esta sección, debes ejecutar una secuencia de comandos de Terraform para crear un clúster de GKE regional privado y con alta disponibilidad y poder implementar tu base de datos de PostgreSQL.

Puedes implementar PostgreSQL con un clúster de Standard o Autopilot. Cada uno tiene sus propias ventajas y diferentes modelos de precios.

Autopilot

Para implementar la infraestructura del clúster de Autopilot, ejecuta los siguientes comandos en 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 reemplaza las siguientes variables en el entorno de ejecución:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para recuperar un token de acceso que autentica las interacciones con varias APIs de Google Cloud
  • PROJECT_ID, REGION y KUBERNETES_CLUSTER_PREFIX son las variables de entorno definidas en la sección Configura tu entorno y asignadas a las nuevas variables relevantes para el clúster de Autopilot que creas.

Cuando se te solicite, escribe yes.

Terraform crea los siguientes recursos:

  • Una red de VPC personalizada y una subred privada para los nodos de Kubernetes
  • Un Cloud Router para acceder a Internet a través de la traducción de direcciones de red (NAT).
  • Un clúster de GKE privado en la región us-central1.
  • Un ServiceAccount con permisos de registro y supervisión para el clúster.
  • Configuración de Google Cloud Managed Service para Prometheus para la supervisión y las alertas de clústeres.

El resultado es similar al siguiente:

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

Standard

Para implementar la infraestructura del clúster Estándar, ejecuta los siguientes comandos en 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 reemplaza las siguientes variables en el entorno de ejecución:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para recuperar un token de acceso que autentica las interacciones con varias APIs de Google Cloud.
  • PROJECT_ID, REGION y KUBERNETES_CLUSTER_PREFIX son las variables de entorno definidas en la sección Configura tu entorno y asignadas a las nuevas variables relevantes para el clúster de Standard que creas.

Cuando se te solicite, escribe yes. Es posible que estos comandos tarden varios minutos en completarse y que el clúster muestre un estado de preparación.

Terraform crea los siguientes recursos:

  • Una red de VPC personalizada y una subred privada para los nodos de Kubernetes
  • Un Cloud Router para acceder a Internet a través de la traducción de direcciones de red (NAT).
  • Un clúster de GKE privado en la región us-central1 con el ajuste de escala automático habilitado (de uno a dos nodos por zona).
  • Un ServiceAccount con permisos de registro y supervisión para el clúster.
  • Configuración de Google Cloud Managed Service para Prometheus para la supervisión y las alertas de clústeres.

El resultado es similar al siguiente:

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

Conéctate al clúster

Configura kubectl para recuperar credenciales y comunicarte con tu clúster de GKE nuevo:

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

Implementa el operador CloudNativePG

Implementa CloudNativePG en tu clúster de Kubernetes con un gráfico de Helm:

  1. Verifica la versión de Helm:

    helm version
    

    Actualiza la versión si es anterior a la 3.13:

    curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
    
  2. Agrega el repositorio de gráficos de Helm para operadores de CloudNativePG:

    helm repo add cnpg https://cloudnative-pg.github.io/charts
    
  3. Implementa el operador de CloudNativePG con la herramienta de línea de comandos de Helm:

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

    El resultado es similar al siguiente:

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

Implementa la base de datos vectorial de PostgreSQL

En esta sección, implementarás la base de datos vectorial de PostgreSQL.

  1. Crea un espacio de nombres pg-ns para la base de datos:

    kubectl create ns pg-ns
    
  2. Aplicar el manifiesto para implementar el clúster de PostgreSQL. El manifiesto del clúster habilita la extensión pgvector.

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

    En el manifiesto postgreSQL_cluster.yaml, se describe el 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. Verifica el estado del clúster:

    kubectl get cluster -n pg-ns --watch
    

    Espera a que el resultado muestre un estado de Cluster in healthy state antes de continuar con el siguiente paso.

Sube un conjunto de datos de demostración y ejecuta búsquedas con el notebook de Jupyter

En esta sección, subirás vectores a una tabla de PostgreSQL y ejecutarás búsquedas semánticas con la sintaxis de SQL.

En el siguiente ejemplo, se usa un conjunto de datos de un archivo CSV que contiene una lista de libros de diferentes géneros. Pgvector sirve como motor de búsqueda, y el Pod que creas sirve como un cliente que consulta la base de datos de PostgreSQL.

  1. Espera a que se cree y esté listo el Pod líder de PostgreSQL:

    while [[ $(kubectl get pod -l cnpg.io/cluster=gke-pg-cluster,role=primary -n pg-ns -o 'jsonpath={..status.conditions[?(@.type=="Ready")].status}') != "True" ]]; do
    sleep 5
    done
    
  2. Crea el Configmap con el books-dataset y ejecuta el Pod de Jupyter para interactuar con tu clúster de PostgreSQL:

    kubectl create -n pg-ns configmap books-dataset --from-file=manifests/02-notebook/dataset.csv
    kubectl create -n pg-ns configmap notebook --from-file=manifests/02-notebook/vector-database.ipynb
    kubectl apply -n pg-ns -f manifests/02-notebook/jupyter.yaml
    
    • El secreto llamado gke-pg-cluster-superuser que crea el operador CloudNativePG se activa en el pod del cliente como variables de entorno llamadas CLIENTUSERNAME y CLIENTPASSWORD.
    • El ConfigMap books-dataset contiene un archivo csv con datos de libros para la base de datos de PostgreSQL.
    • El ConfigMap demo-app contiene código de Python para crear la tabla de PostgreSQL a partir de books-dataset.

    En el manifiesto de jupyter.yaml, se describe la implementación notebook y su Service:

    ---
    apiVersion: v1
    kind: Service
    metadata:
      labels: &labels
        app: jupyter-notebook
      name: notebook
    spec:
      ports:
      - port: 8888
      selector: *labels
      type: LoadBalancer
      # type: ClusterIP
    ---
    apiVersion: apps/v1
    kind: Deployment
    metadata:
      name: notebook
      labels: &labels
        app: jupyter-notebook
    spec:
      selector:
        matchLabels: *labels
      template:
        metadata: 
          labels: *labels
        spec:
          containers:
          - name: jupyter
            image: tensorflow/tensorflow:2.15.0-jupyter
            resources:
              requests:
                memory: "4500Mi"
                cpu: "1"
              limits:
                memory: "4500Mi"
                cpu: "1"
            ports:
            - containerPort: 8888
            env:
            - name: CLIENTPASSWORD
              valueFrom:
                secretKeyRef:
                  name: gke-pg-cluster-superuser
                  key: password
            - name: CLIENTUSERNAME
              valueFrom:
                secretKeyRef:
                  name: gke-pg-cluster-superuser
                  key: username
            volumeMounts:
            - name: books-dataset
              mountPath: /usr/local/dataset
            - name: notebook
              mountPath: /tf
          volumes:
          - name: books-dataset
            configMap:
              name: books-dataset
          - name: notebook
            configMap:
              name: notebook
  3. Espera a que GKE inicie el Pod de Jupyter:

    kubectl wait pods -l app=jupyter-notebook --for condition=Ready --timeout=300s -n pg-ns
    
  4. Obtén la URL con el token de acceso para conectarte a Jupyter:

    export EXTERNAL_IP=$(kubectl -n pg-ns get svc notebook --output jsonpath='{.status.loadBalancer.ingress[0].ip}')
    kubectl logs deploy/notebook -n pg-ns| grep '^ .*http://127'|sed "s|127.0.0.1|${EXTERNAL_IP}|"
    

    El resultado es similar al siguiente:

    http://34.123.21.1:8888/tree?token=a1d48d3531c48328695d6901004c94060aa0aa3554ff7463
    
  5. Abre esta URL y haz clic en el archivo vector-database.ipynb.

  6. Haz clic en Ejecutar > Ejecutar todas las celdas. Jupyter ejecuta el código y hace una consulta de búsqueda para el texto drama about people and unhappy love.

    Esta consulta hace una búsqueda semántica en la tabla documents en PostgreSQL y recupera un máximo de dos resultados con la puntuación de coincidencia más alta relevante para tu consulta.

    El resultado es similar al siguiente:

    Title: Romeo and Juliet, Author: William Shakespeare, Paul Werstine (Editor),
    Barbara A. Mowat (Editor), Paavo Emil Cajander (Translator)
    In Romeo and Juliet, Shakespeare creates a violent world, in which two young
    people fall in love. It is not simply that their families disapprove; the Montagues
    and the Capulets are engaged in a blood feud.In this death-filled setting, the
    movement from love at first sight to the lovers' final union in death seems
    almost inevitable. And yet, this play set in an extraordinary world has become
    the quintessential story of young love. In part because of its exquisite language,
    it is easy to respond as if it were about all young lovers.
    ---------
    Title: A Midsummer Night's Dream, Author: William Shakespeare, Paul Werstine (Editor),
    Barbara A. Mowat (Editor), Catherine Belsey (Contributor)
    Shakespeare's intertwined love polygons begin to get complicated from the start--Demetrius
    and Lysander both want Hermia but she only has eyes for Lysander. Bad news is,
    Hermia's father wants Demetrius for a son-in-law. On the outside is Helena,
    whose unreturned love burns hot for Demetrius. Hermia and Lysander plan to flee
    from the city under cover of darkness but are pursued by an enraged Demetrius
    (who is himself pursued by an enraptured Helena). In the forest, unbeknownst
    to the mortals, Oberon and Titania (King and Queen of the faeries) are having
    a spat over a servant boy. The plot twists up when Oberon's head mischief-maker,
    Puck, runs loose with a flower which causes people to fall in love with the
    first thing they see upon waking. Throw in a group of labourers preparing a
    play for the Duke's wedding (one of whom is given a donkey's head and Titania
    for a lover by Puck) and the complications become fantastically funny.
    ---------
    

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra el proyecto

La manera más fácil de evitar la facturación es borrar el proyecto que creaste para el instructivo.

Borra un proyecto de Google Cloud:

gcloud projects delete PROJECT_ID

Si borraste el proyecto, tu limpieza se completó. Si no borraste el proyecto, borra los recursos individuales.

Borra los recursos individuales

  1. Configurar variables de entorno

    export PROJECT_ID=${PROJECT_ID}
    export KUBERNETES_CLUSTER_PREFIX=postgres
    export REGION=us-central1
    
  2. Ejecuta el 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}
    

    Reemplaza FOLDER por gke-autopilot o gke-standard, según el tipo de clúster de GKE que hayas creado.

    Cuando se te solicite, escribe yes.

¿Qué sigue?