Implantar um banco de dados de vetores PostgreSQL no GKE

Autopilot Standard

---

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:

• GKE
• Google Cloud Managed Service for Prometheus

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. Faça login na sua conta do Google Cloud. Se você começou a usar o Google Cloud agora, crie uma conta para avaliar o desempenho de nossos produtos em situações reais. Clientes novos também recebem US$ 300 em créditos para executar, testar e implantar cargas de trabalho.
2. Instale a CLI do Google Cloud.

3. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

   Observação: se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.

4. Crie ou selecione um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   • Crie um projeto do Google Cloud:

     gcloud projects create PROJECT_ID

     Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

   • Selecione o projeto do Google Cloud que você criou:

     gcloud config set project PROJECT_ID

     Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

5. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

6. Ative as APIs 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. Instale a CLI do Google Cloud.

8. Para inicializar a CLI gcloud, execute o seguinte comando:

   gcloud init

   Observação: se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente executando gcloud components update.

9. Crie ou selecione um projeto do Google Cloud.

   Observação: se você não pretende manter os recursos criados neste procedimento, crie um projeto novo em vez de selecionar um que já existe. Depois de concluir essas etapas, é possível excluir o projeto. Para fazer isso, basta remover todos os recursos associados a ele.

   • Crie um projeto do Google Cloud:

     gcloud projects create PROJECT_ID

     Substitua PROJECT_ID por um nome para o projeto do Google Cloud que você está criando.

   • Selecione o projeto do Google Cloud que você criou:

     gcloud config set project PROJECT_ID

     Substitua PROJECT_ID pelo nome do projeto do Google Cloud.

10. Verifique se a cobrança está ativada para o seu projeto do Google Cloud.

11. Ative as APIs 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. Atribua os papéis à sua Conta do Google. Execute uma vez o seguinte comando para cada um dos seguintes papéis do 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

    • Substitua PROJECT_ID pela ID do seu projeto.
    • Substitua EMAIL_ADDRESS pelo seu endereço de e-mail.
    • Substitua ROLE por cada papel individual.

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.

Autopilot

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

Standard

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

Limpeza

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.

Cuidado: excluir um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto existente para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos no projeto.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um código do projeto personalizado para ser usado no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, exclua recursos específicos do projeto, em vez de excluir o projeto inteiro.

Se você planeja passar por várias arquiteturas, tutoriais ou guias de início rápido, a reutilização de projetos pode evitar que você exceda os limites da cota do projeto.

Exclua um projeto do Google Cloud:

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

• Saiba como implantar clusters do PostgreSQL no GKE usando o operador CloudNativePG.
• Conheça as práticas recomendadas para implantar bancos de dados no GKE.
• Descubra soluções para executar cargas de trabalho com uso intensivo de dados usando o GKE.