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ê vai 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 um teste sem custo financeiro.

Ao concluir as tarefas descritas neste documento, é possível evitar o faturamento contínuo excluindo os recursos criados. Para mais informações, consulte 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 Google Cloud CLI, 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.

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloud, 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.

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

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 Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Cloud Resource Manager, Compute Engine, GKE e IAM Service Account Credentials:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

Instale a CLI do Google Cloud.

Observação:se você já instalou a CLI gcloud anteriormente, execute o comando gcloud components update para verificar se tem a versão mais recente.

Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.

Para inicializar a gcloud CLI, execute o seguinte comando:

gcloud init

Crie ou selecione um Google Cloud projeto.

Funções necessárias para selecionar ou criar um projeto

• Selecionar um projeto: não é necessário um papel específico do IAM para selecionar um projeto. Você pode escolher qualquer projeto em que tenha recebido um papel.
• Criar um projeto: para criar um projeto, é necessário ter o papel de Criador de projetos (roles/resourcemanager.projectCreator), que contém a permissão resourcemanager.projects.create. Saiba como conceder papéis.

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 Google Cloud que você está criando.

• Selecione o projeto Google Cloud que você criou:

  gcloud config set project PROJECT_ID

  Substitua PROJECT_ID pelo nome do projeto do Google Cloud .

Verifique se o faturamento está ativado para o projeto do Google Cloud .

Ative as APIs Cloud Resource Manager, Compute Engine, GKE e IAM Service Account Credentials:

Funções necessárias para ativar APIs

Para ativar as APIs, é necessário ter o papel do IAM de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin), que contém a permissão serviceusage.services.enable. Saiba como conceder papéis.

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

1. Atribua papéis à sua conta de usuário. Execute o seguinte comando uma vez 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:USER_IDENTIFIER" --role=ROLE

   Substitua:

   • PROJECT_ID: o ID do projeto.
   • USER_IDENTIFIER: o identificador da sua conta de usuário . Por exemplo, [e-mail].
   • ROLE: o papel do IAM concedido à sua conta de usuário.

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. É possível usar 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 seu 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.

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.

Cuidado: a exclusão de um projeto tem os seguintes efeitos:

• Tudo no projeto é excluído. Se você tiver usado um projeto atual para as tarefas neste documento, a exclusão dele incluirá a exclusão de quaisquer outros trabalhos feitos nele.
• Os IDs do projeto personalizados são perdidos. Ao criar o projeto, você pode ter criado um ID 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 explorar várias arquiteturas, tutoriais e guias de início rápido, a reutilização de projetos pode evitar que você exceda limites da cota.

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