Desplegar una base de datos de vectores de PostgreSQL en GKE

Autopilot Standard

En este tutorial se muestra cómo desplegar un clúster de base de datos de vectores PostgreSQL en Google Kubernetes Engine (GKE).

PostgreSQL incluye una serie de módulos y extensiones que amplían la funcionalidad de la base de datos. En este tutorial, instalarás la extensión pgvector en un clúster de PostgreSQL desplegado en GKE. La extensión Pgvector te permite almacenar vectores en las tablas de la base de datos añadiendo tipos de vectores a PostgreSQL. Pgvector también ofrece búsquedas de similitud ejecutando consultas SQL comunes.

Simplificamos la implementación de la extensión PGvector desplegando primero el operador CloudnativePG, ya que este proporciona una versión empaquetada de la extensión.

Este tutorial está dirigido a administradores y arquitectos de plataformas en la nube, ingenieros de aprendizaje automático y profesionales de MLOps (DevOps) que estén interesados en desplegar clústeres de bases de datos PostgreSQL en GKE.

Objetivos

En este tutorial, aprenderás a hacer lo siguiente:

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

Costes

En este documento, se utilizan los siguientes componentes facturables de Google Cloud:

• GKE
• Google Cloud Managed Service for Prometheus

Para generar una estimación de costes basada en el uso previsto, utiliza la calculadora de precios.

Los usuarios nuevos Google Cloud pueden disfrutar de una prueba gratuita.

Cuando termines las tareas que se describen en este documento, puedes evitar que se te siga facturando eliminando los recursos que has creado. Para obtener más información, consulta la sección Limpiar.

Antes de empezar

En este tutorial, usarás Cloud Shell para ejecutar comandos. Cloud Shell es un entorno de shell para gestionar recursos alojados en Google Cloud. Viene preinstalado con las herramientas de línea de comandos Google Cloud CLI, kubectl, Helm y Terraform. Si no usas Cloud Shell, debes instalar 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: Si ya has instalado la CLI de gcloud, asegúrate de tener la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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

Install the Google Cloud CLI.

Nota: Si ya has instalado la CLI de gcloud, asegúrate de tener la versión más reciente ejecutando gcloud components update.

Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Create or select a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

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:

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

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.

Configurar un entorno

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

1. Define las variables de entorno de tu proyecto, región y prefijo de recurso de clúster de Kubernetes:

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

   • Sustituye PROJECT_ID por el ID de tu proyecto. Google Cloud

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

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

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

3. Ve al directorio postgres-pgvector:

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

Crear la infraestructura del clúster

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

Puedes desplegar PostgreSQL con un clúster estándar o de Autopilot. Cada una tiene sus propias ventajas y modelos de precios diferentes.

Autopilot

Para desplegar la infraestructura del clúster 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 sustituye las siguientes variables en el tiempo de ejecución:

• GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para obtener 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 Configurar el entorno y asignadas a las nuevas variables relevantes del clúster de Autopilot que estás creando.

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 monitorización para el clúster.
• Configuración de Google Cloud Managed Service para Prometheus para la monitorización y las alertas de clústeres.

El resultado debería ser similar al siguiente:

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

Estándar

Para desplegar la infraestructura del clúster Standard, 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 sustituye las siguientes variables en el tiempo de ejecución:

• GOOGLE_OAUTH_ACCESS_TOKEN usa el comando gcloud auth print-access-token para obtener 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 Configurar el entorno y asignadas a las nuevas variables relevantes del clúster estándar que estás creando.

Cuando se te solicite, escribe yes. Estos comandos pueden tardar varios minutos en completarse y el clúster en mostrar el estado "Listo".

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 privado de GKE en la región us-central1 con el autoescalado habilitado (de uno a dos nodos por zona).
• Un ServiceAccount con permisos de registro y monitorización para el clúster.
• Configuración de Google Cloud Managed Service para Prometheus para la monitorización y las alertas de clústeres.

El resultado debería ser similar al siguiente:

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

Conéctate al clúster

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

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

Desplegar el operador CloudNativePG

Despliega CloudNativePG en tu clúster de Kubernetes mediante un gráfico de Helm:

1. Comprueba 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. Añade el repositorio del gráfico de Helm del operador CloudNativePG:

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

3. Despliega el operador CloudNativePG con la herramienta de línea de comandos Helm:

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

   El resultado debería ser 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
   ...
   

Desplegar la base de datos de vectores PostgreSQL

En esta sección, desplegarás la base de datos de vectores PostgreSQL.

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

   kubectl create ns pg-ns
   

2. Aplica el manifiesto para desplegar 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
   

   El manifiesto postgreSQL_cluster.yaml describe la implementación:

   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. Comprueba el estado del clúster:

   kubectl get cluster -n pg-ns --watch
   

   Espera a que el resultado muestre el estado Cluster in healthy state antes de pasar al siguiente paso.

Ejecutar consultas con un cuaderno de Vertex AI Colab Enterprise

En esta sección, subirá vectores a una tabla de PostgreSQL y ejecutará consultas de búsqueda semántica mediante la sintaxis de SQL.

Para conectarte a tu base de datos de PostgreSQL, usa Colab Enterprise. Utilizas una plantilla de tiempo de ejecución específica para desplegar en postgres-vpc, de modo que el cuaderno pueda comunicarse con los recursos del clúster de GKE.

Para obtener más información sobre Vertex AI Colab Enterprise, consulta la documentación de Colab Enterprise.

Crear una plantilla de tiempo de ejecución

Para crear una plantilla de entorno de ejecución de Colab Enterprise, sigue estos pasos:

1. En la Google Cloud consola, ve a la página Plantillas de tiempo de ejecución de Colab Enterprise y asegúrate de que tu proyecto esté seleccionado:

   Ir a Plantillas de entorno de ejecución

2. Haz clic en Nueva plantilla. Aparecerá la página Crear plantilla de tiempo de ejecución.

3. En la sección Información básica de Runtime:

   • En el campo Nombre visible, introduce pgvector-connect.
   • En la lista desplegable Región, selecciona us-central1. Es la misma región que tu clúster de GKE.

4. En la sección Configurar recursos de computación:

   • En la lista desplegable Tipo de máquina, selecciona e2-standard-2.
   • En el campo Tamaño del disco, introduce 30.

5. En la sección Redes y seguridad:

   • En la lista desplegable Red, selecciona la red en la que se encuentra tu clúster de GKE.
   • En la lista desplegable Subred, selecciona la subred correspondiente.
   • Desmarca la casilla Habilitar el acceso público a Internet.

6. Para terminar de crear la plantilla de tiempo de ejecución, haga clic en Crear. Tu plantilla de entorno de ejecución aparece en la lista de la pestaña Plantillas de entorno de ejecución.

Crear un tiempo de ejecución

Para crear un entorno de ejecución de Colab Enterprise, sigue estos pasos:

1. En la lista de plantillas de tiempo de ejecución de la plantilla que acaba de crear, vaya a la columna Acciones, haga clic en y, a continuación, en Crear tiempo de ejecución. Aparecerá el panel Crear tiempo de ejecución de Vertex AI.

2. Para crear un tiempo de ejecución basado en tu plantilla, haz clic en Crear.

3. En la pestaña Tiempos de ejecución que se abre, espera a que el estado cambie a Correcto.

Importar el cuaderno

Para importar el cuaderno en Colab Enterprise, sigue estos pasos:

1. Ve a la pestaña Mis cuadernos y haz clic en Importar. Aparecerá el panel Importar cuadernos.

2. En Importar fuente, selecciona URL.

3. En URLs de cuadernos, introduce el siguiente enlace:

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

4. Haz clic en Importar.

Conectarse al entorno de ejecución y ejecutar consultas

Para conectarte al entorno de ejecución y ejecutar consultas, sigue estos pasos:

1. En el cuaderno, junto al botón Conectar, haz clic en Opciones de conexión adicionales. Aparecerá el panel Conectar con el entorno de ejecución de Vertex AI.

2. Selecciona Conectar a un tiempo de ejecución y, a continuación, Conectar a un tiempo de ejecución existente.

3. Selecciona el tiempo de ejecución que has iniciado y haz clic en Conectar.

4. Para ejecutar las celdas del cuaderno, haz clic en el botón Ejecutar celda situado junto a cada celda de código.

El cuaderno contiene celdas de código y texto que describe cada bloque de código. Al ejecutar una celda de código, se ejecutan sus comandos y se muestra un resultado. Puedes ejecutar las celdas en orden o ejecutar celdas concretas según sea necesario.

Limpieza

Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.

Eliminar el proyecto

La forma más fácil de evitar que te cobren es eliminar el proyecto que has creado para este tutorial.

Precaución: Eliminar un proyecto tiene los siguientes efectos:

• Se elimina todo el contenido del proyecto. Si has usado un proyecto que ya existía para las tareas de este documento, cuando lo elimines, también se eliminará cualquier otro trabajo que hayas realizado en él.
• Se pierden los IDs de proyecto personalizados. Cuando creaste este proyecto, es posible que hayas creado un ID de proyecto personalizado que quieras usar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, elimina los recursos seleccionados dentro del proyecto en lugar de eliminar todo el proyecto.

Si tienes previsto consultar varias arquitecturas, tutoriales o guías de inicio rápido, reutilizar los proyectos puede ayudarte a no superar los límites de cuota de proyectos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Si has eliminado el proyecto, ya has terminado. Si no has eliminado el proyecto, elimina los recursos individuales.

Eliminar recursos concretos

1. Define las 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}
   

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

Siguientes pasos

• Consulta cómo desplegar clústeres de PostgreSQL en GKE con el operador CloudNativePG.
• Consulta las prácticas recomendadas para desplegar bases de datos en GKE.
• Descubre soluciones para ejecutar cargas de trabajo con gran cantidad de datos con GKE.