Implantar um banco de dados de vetores PostgreSQL no GKE

Neste tutorial, mostramos como implantar um cluster de banco de dados de vetores PostgreSQL no Google Kubernetes Engine (GKE).

O PostgreSQL é fornecido com uma variedade de módulos e extensões que ampliam a funcionalidade do banco de dados. Neste tutorial, você vai instalar a extensão pgvector em um cluster atual do PostgreSQL implantado no GKE. A extensão Pgvector permite armazenar vetores nas tabelas do banco de dados ao adicionar tipos de vetores ao PostgreSQL. A Pgvector também faz pesquisas por similaridade executando consultas SQL comuns.

Para simplificar a implantação da extensão Pgvector, primeiro é preciso implantar o operador CloudnativePG, porque ele fornece uma versão agrupada dela.

Este tutorial é destinado a administradores e arquitetos de plataformas de nuvem, engenheiros de ML e profissionais de MLOps (DevOps) interessados em implantar clusters de banco de dados PostgreSQL no GKE.

Objetivos

Neste tutorial, você vai aprender a fazer o seguinte:

  • Implantar a infraestrutura do GKE para PostgreSQL.
  • Instalar a extensão Pgvector no cluster do PostgreSQL implantado no GKE.
  • Implantar e configurar o operador CloudNativePG do PostgreSQL com o Helm.
  • Fazer upload do conjunto de dados de demonstração e executar consultas de pesquisa com o Jupyter Notebook.

Custos

Neste documento, você usará os seguintes componentes faturáveis do Google Cloud:

Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços. Novos usuários do Google Cloud podem estar qualificados para uma avaliação gratuita.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Saiba mais em Limpeza.

Antes de começar

Neste tutorial, use o Cloud Shell para executar os comandos. O Cloud Shell é um ambiente shell para gerenciar recursos hospedados no Google Cloud. Ele vem pré-instalado com a CLI do Google Cloud, o kubectl, o Helm e ferramentas de linha de comando do Terraform. Se você não estiver usando o Cloud Shell, instale a CLI do Google Cloud.

  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. To initialize the gcloud CLI, run the following command: 

    gcloud init

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

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

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

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

    gcloud init

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

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

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

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

Configurar seu ambiente

Para configurar o ambiente com o Cloud Shell, siga estas etapas:

  1. Defina variáveis de ambiente para o projeto, a região e um prefixo de recurso de cluster do Kubernetes:

    export PROJECT_ID=PROJECT_ID
export KUBERNETES_CLUSTER_PREFIX=postgres
export REGION=us-central1
    • Substitua PROJECT_ID pelo ID do projeto do Google Cloud.

    Neste tutorial, usamos a região us-central1.

  2. Clone o repositório de exemplo de código do GitHub:

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

  3. Acesse o diretório postgres-pgvector:

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

Criar a infraestrutura do cluster

Nesta seção, você vai executar um script do Terraform para criar um cluster privado, altamente disponível e regional do GKE a fim de implantar o banco de dados do PostgreSQL.

É possível usar um cluster Standard ou Autopilot para a implantação do PostgreSQL. Cada um tem vantagens específicas e modelos de preços diferentes.

Piloto automático

Para implantar a infraestrutura do cluster Autopilot, execute os seguintes comandos no 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}

O GKE substitui as seguintes variáveis no ambiente de execução:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para recuperar um token de acesso que autentique interações com várias APIs do Google Cloud.
  • PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na seção Configurar seu ambiente e atribuídas às novas variáveis relevantes para o cluster do Autopilot que você está criando.

Quando solicitado, digite yes.

O Terraform cria os seguintes recursos:

  • Uma rede VPC personalizada e uma sub-rede particular para os nós do Kubernetes.
  • Um Cloud Router para acessar a Internet por meio da conversão de endereços de rede (NAT).
  • Um cluster do GKE particular na região us-central1.
  • Um ServiceAccount com permissões de geração de registros e monitoramento para o cluster.
  • Configuração do Google Cloud Managed Service para Prometheus para geração de alertas e monitoramento de clusters.

O resultado será assim:

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

Padrão

Para implantar a infraestrutura de cluster Standard, execute os seguintes comandos no 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}

O GKE substitui as seguintes variáveis no ambiente de execução:

  • GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para recuperar um token de acesso que autentique interações com várias APIs do Google Cloud.
  • PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na seção Configurar seu ambiente e atribuídas às novas variáveis relevantes para o cluster padrão que você está criando.

Quando solicitado, digite yes. Pode levar vários minutos para que esses comandos sejam concluídos e o cluster mostre um status pronto.

O Terraform cria os seguintes recursos:

  • Uma rede VPC personalizada e uma sub-rede particular para os nós do Kubernetes.
  • Um Cloud Router para acessar a Internet por meio da conversão de endereços de rede (NAT).
  • Um cluster do GKE particular na região us-central1 com escalonamento automático ativado (de um a dois nós por zona).
  • Um ServiceAccount com permissões de geração de registros e monitoramento para o cluster.
  • Configuração do Google Cloud Managed Service para Prometheus para geração de alertas e monitoramento de clusters.

O resultado será assim:

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

Conectar ao cluster

Configure kubectl para buscar credenciais e se comunicar com o novo cluster do GKE:

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

Implantar o operador CloudNativePG

Implante o CloudNativePG no cluster do Kubernetes usando um gráfico do Helm:

  1. Verifique a versão do Helm:

    helm version

    Atualize a versão se ela for anterior à 3.13:

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

  2. Adicionar o repositório de gráficos do Helm do operador CloudNativePG:

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

  3. Implantar o operador do CloudNativePG usando a ferramenta de linha de comando Helm:

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

    O resultado será assim:

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

Implantar o banco de dados de vetores do PostgreSQL

Nesta seção, você vai implantar o banco de dados de vetores do PostgreSQL.

  1. Crie um namespace pg-ns para o banco de dados:

    kubectl create ns pg-ns

  2. Aplique o manifesto para implantar o cluster do PostgreSQL. O manifesto do cluster ativa a extensão pgvector.

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

    O manifesto postgreSQL_cluster.yaml descreve a implantação:

    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. Verifique o status do cluster:

    kubectl get cluster -n pg-ns --watch

    Antes de prosseguir, aguarde até que o status Cluster in healthy state seja exibido na saída.

Fazer upload do conjunto de dados de demonstração e executar consultas de pesquisa com o Jupyter Notebook

Nesta seção, você vai fazer o upload de vetores para uma tabela do PostgreSQL e executar consultas de pesquisa semântica com a sintaxe SQL.

Neste exemplo, você usa um conjunto de dados de um arquivo CSV que contém uma lista de livros de diferentes gêneros. A Pgvector atua como um mecanismo de pesquisa, e o pod criado funciona como um cliente que consulta o banco de dados PostgreSQL.

  1. Aguarde até que o pod líder do PostgreSQL seja criado e esteja pronto:

    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. Crie o ConfigMap com books-dataset e execute o pod do Jupyter para interagir com o cluster do 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
    • O secret gke-pg-cluster-superuser, criado pelo operador CloudNativePG, é montado no pod cliente como as variáveis de ambiente CLIENTUSERNAME e CLIENTPASSWORD..
    • O ConfigMap books-dataset contém um arquivo csv com dados de livros para o banco de dados PostgreSQL.
    • O ConfigMap demo-app contém o código Python para criar a tabela do PostgreSQL por meio de books-dataset.

    O manifesto jupyter.yaml descreve a implantação de notebook e o respectivo serviço:

    ---
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. Aguarde o GKE iniciar o pod do Jupyter:

    kubectl wait pods -l app=jupyter-notebook --for condition=Ready --timeout=300s -n pg-ns

  4. Consiga o URL com o token de acesso para se conectar ao 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}|"

    O resultado será assim:

    http://34.123.21.1:8888/tree?token=a1d48d3531c48328695d6901004c94060aa0aa3554ff7463

  5. Abra o URL e clique no arquivo vector-database.ipynb.

  6. Clique em Run > Run all Cells. O Jupyter executa o código e faz uma consulta de pesquisa para o texto drama about people and unhappy love.

    Essa consulta realiza uma pesquisa semântica na tabela documents no PostgreSQL e recupera no máximo dois resultados com a maior pontuação de correspondência relevante para a consulta.

    O resultado será assim:

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

Limpar

Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.

Exclua o projeto

A maneira mais fácil de evitar o faturamento é excluir o projeto criado para o tutorial.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se você tiver excluído o projeto, a limpeza estará completa. Se você não excluiu o projeto, exclua os recursos individuais.

Excluir recursos individuais

  1. Defina variáveis de ambiente.

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

  2. Execute o 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}

    Substitua FOLDER por gke-autopilot ou gke-standard, dependendo do tipo de cluster do GKE que você criou.

    Quando solicitado, digite yes.

A seguir