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.

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

Executar consultas com um notebook do Colab Enterprise da Vertex AI

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.

Você se conecta ao banco de dados do PostgreSQL usando o Colab Enterprise. Você usa um modelo de ambiente de execução dedicado para implantar no postgres-vpc, para que o notebook possa se comunicar com os recursos no cluster do GKE.

Para mais informações sobre o Vertex AI Colab Enterprise, consulte a documentação do Colab Enterprise.

Criar um modelo de ambiente de execução

Para criar um modelo de ambiente de execução do Colab Enterprise:

1. No console do Google Cloud , acesse a página Modelos de ambiente de execução do Colab Enterprise e verifique se o projeto está selecionado:

   Acessar "Modelos de ambiente de execução"

2. Clique em Novo modelo. A página Criar novo modelo de ambiente de execução é exibida.

3. Na seção Fundamentos do ambiente de execução:

   • No campo Nome de exibição, insira pgvector-connect.
   • Na lista suspensa Região, selecione us-central1. É a mesma região do cluster do GKE.

4. Na seção Configurar computação:

   • Na lista suspensa Tipo de máquina, selecione e2-standard-2.
   • No campo Tamanho do disco, digite 30.

5. Na seção Rede e segurança:

   • Na lista suspensa Rede, selecione a rede em que o cluster do GKE está localizado.
   • Na lista suspensa Sub-rede, selecione uma sub-rede correspondente.
   • Desmarque a caixa de seleção Ativar acesso à Internet pública.

6. Para concluir a criação do modelo de ambiente de execução, clique em Criar. Seu modelo de ambiente de execução aparece na lista da guia Modelos de ambiente de execução.

Criar um ambiente de execução

Para criar um ambiente de execução do Colab Enterprise:

1. Na lista de modelos de ambiente de execução do modelo que você acabou de criar, na coluna Ações, clique em e em Criar ambiente de execução. O painel Criar ambiente de execução da Vertex AI será exibido.

2. Para criar um ambiente de execução com base no modelo, clique em Criar.

3. Na guia Ambientes de execução que é aberta, aguarde até que o status mude para Íntegro.

Importar o notebook

Para importar o notebook no Colab Enterprise:

1. Acesse a guia Meus notebooks e clique em Importar. O painel Importar notebooks aparece.

2. Em Origem da importação, selecione URL.

3. Em URLs do notebook, insira o seguinte link:

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

4. Clique em Importar.

Conectar-se ao ambiente de execução e executar consultas

Para se conectar ao ambiente de execução e executar consultas:

1. No notebook, ao lado do botão Conectar, clique em Opções de conexão adicionais. O painel Conectar ao ambiente de execução da Vertex AI é exibido.

2. Selecione Conectar a um ambiente de execução e Conectar a um ambiente de execução.

3. Selecione o ambiente de execução iniciado e clique em Conectar.

4. Para executar as células do notebook, clique no botão Executar célula ao lado de cada célula de código.

O notebook contém células de código e texto que descrevem cada bloco de código. A execução de uma célula de código executa os comandos e mostra uma saída. É possível executar as células em ordem ou individualmente, conforme necessário.