Implementa una base de datos vectorial de PostgreSQL en GKE.

Autopilot estándar

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:

• GKE
• Google Cloud Managed Service for Prometheus

Para obtener una estimación de costos en función del uso previsto, usa la calculadora de precios.

Es posible que los usuarios de Google Cloud nuevos cumplan con los requisitos para acceder a una prueba gratuita.

Cuando completes las tareas que se describen en este documento, podrás borrar los recursos que creaste para evitar que se te siga facturando. Para obtener más información, consulta Realiza 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 comandos de 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 instalaste gcloud CLI anteriormente, asegúrate de tener la versión más reciente ejecutando gcloud components update.

Si usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI 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 role (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 instalaste gcloud CLI anteriormente, asegúrate de tener la versión más reciente ejecutando gcloud components update.

Si usas un proveedor de identidad externo (IdP), primero debes Acceder a la gcloud CLI 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 role (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.

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 --location ${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.

Ejecuta consultas con un notebook de Colab Enterprise de Vertex AI

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

Te conectas a tu base de datos de PostgreSQL con Colab Enterprise. Usas una plantilla de tiempo de ejecución dedicada para implementar en postgres-vpc, de modo que el notebook 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.

Crea una plantilla de entorno de ejecución

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

1. En la consola de Google Cloud , ve a la página Plantillas de entorno 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 New Template. Aparecerá la página Crear nueva plantilla de entorno de ejecución.

3. En la sección Conceptos básicos del entorno de ejecución, haz lo siguiente:

   • En el campo Nombre visible, escribe 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 procesamiento, haz lo siguiente:

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

5. En la sección Herramientas de redes y seguridad, haz lo siguiente:

   • En la lista desplegable Red, selecciona la red en la que reside tu clúster de GKE.
   • En la lista desplegable Subred, selecciona una subred correspondiente.
   • Desmarca la casilla de verificación Habilitar el acceso a Internet pública.

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

Crea un entorno de ejecución

Para crear un entorno de ejecución de Colab Enterprise, haz lo siguiente:

1. En la lista de plantillas de ejecución de la plantilla que acabas de crear, en la columna Acciones, haz clic en y, luego, en Crear tiempo de ejecución. Aparecerá el panel Crear entorno de ejecución de Vertex AI.

2. Para crear un entorno 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.

Importa el notebook

Para importar el notebook en Colab Enterprise, haz lo siguiente:

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

2. En Fuente de importación, selecciona URL.

3. En URLs de notebooks, ingresa el siguiente vínculo:

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

4. Haz clic en Importar.

Conéctate al entorno de ejecución y ejecuta consultas

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

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

2. Selecciona Conectar a un entorno de ejecución y, luego, Conectar a un entorno de ejecución existente.

3. Selecciona el entorno de ejecución que iniciaste y haz clic en Conectar.

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

El notebook contiene celdas de código y texto que describen cada bloque de código. Cuando se ejecuta una celda de código, se ejecutan sus comandos y se muestra un resultado. Puedes ejecutar las celdas en orden o ejecutar celdas individuales según sea necesario.

Realiza una limpieza

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.

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

• Se borra todo el contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
• Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Delete a Google Cloud project:

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?

• Explora cómo implementar clústeres de PostgreSQL en GKE con el operador CloudNativePG.
• Conoce las prácticas recomendadas para implementar bases de datos en GKE.
• Descubre soluciones para ejecutar cargas de trabajo con uso intensivo de datos con GKE.