Implemente uma base de dados vetorial PostgreSQL no GKE

Autopilot Padrão

Este tutorial mostra como implementar um cluster de base de dados vetorial PostgreSQL no Google Kubernetes Engine (GKE).

O PostgreSQL inclui uma variedade de módulos e extensões que expandem a funcionalidade da base de dados. Neste tutorial, instala a extensão pgvector num cluster PostgreSQL existente implementado no GKE. A extensão Pgvector permite-lhe armazenar vetores nas tabelas da base de dados adicionando tipos de vetores ao PostgreSQL. O Pgvector também oferece pesquisas de semelhanças através da execução de consultas SQL comuns.

Simplificamos a implementação da extensão PGvector implementando primeiro o operador CloudnativePG, uma vez que o operador fornece uma versão agrupada da extensão.

Este tutorial destina-se a administradores e arquitetos da plataforma na nuvem, engenheiros de ML e profissionais de MLOps (DevOps) interessados na implementação de clusters de bases de dados PostgreSQL no GKE.

Objetivos

Neste tutorial, vai aprender a:

• Implemente a infraestrutura do GKE para o PostgreSQL.
• Instale a extensão pgvector no cluster PostgreSQL implementado no GKE.
• Implemente e configure o operador PostgreSQL CloudNativePG com o Helm.
• Carregue um conjunto de dados de demonstração e execute consultas de pesquisa com o Jupyter Notebook.

Custos

Neste documento, usa os seguintes componentes faturáveis do Google Cloud:

• GKE
• Google Cloud Managed Service for Prometheus

Para gerar uma estimativa de custos com base na sua utilização prevista, use a calculadora de preços.

Os novos Google Cloud utilizadores podem ser elegíveis para uma avaliação gratuita.

Quando terminar as tarefas descritas neste documento, pode evitar a faturação contínua eliminando os recursos que criou. Para mais informações, consulte o artigo Limpe.

Antes de começar

Neste tutorial, vai usar a Cloud Shell para executar comandos. O Cloud Shell é um ambiente de shell para gerir recursos alojados no Google Cloud. É fornecido pré-instalado com as ferramentas de linha de comandos CLI do Google Cloud, kubectl, Helm e Terraform. Se não usar o Cloud Shell, tem de instalar a CLI Google Cloud.

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: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte 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: se instalou a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente executando gcloud components update.

Se estiver a usar um fornecedor de identidade (IdP) externo, tem primeiro de iniciar sessão na CLI gcloud com a sua identidade federada.

Para inicializar a CLI gcloud, execute o seguinte 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.

Configure o seu ambiente

Para configurar o seu ambiente com o Cloud Shell, siga estes passos:

1. Defina variáveis de ambiente para o seu projeto, 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 seu Google Cloud ID do projeto.

   Este tutorial usa a região us-central1.

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

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

3. Navegue para o diretório postgres-pgvector:

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

Crie a infraestrutura do cluster

Nesta secção, executa um script do Terraform para criar um cluster do GKE regional privado de alta disponibilidade para implementar a sua base de dados PostgreSQL.

Pode optar por implementar o PostgreSQL através de um cluster padrão ou do Autopilot. Cada um tem as suas próprias vantagens e modelos de preços diferentes.

Piloto automático

Para implementar a infraestrutura do cluster do 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 tempo de execução:

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

Quando lhe for pedido, escreva yes.

O Terraform cria os seguintes recursos:

• Uma rede VPC personalizada e uma sub-rede privada para os nós do Kubernetes.
• Um Cloud Router para aceder à Internet através da tradução de endereços de rede (NAT).
• Um cluster do GKE privado na região us-central1.
• Um ServiceAccount com autorizações de registo e monitorização para o cluster.
• Configuração do Google Cloud Managed Service for Prometheus para monitorização e alertas de clusters.

O resultado é semelhante ao seguinte:

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

Standard

Para implementar a infraestrutura do 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 tempo de execução:

• GOOGLE_OAUTH_ACCESS_TOKEN usa o comando gcloud auth print-access-token para obter um token de acesso que autentica as interações com várias APIs Google Cloud.
• PROJECT_ID, REGION e KUBERNETES_CLUSTER_PREFIX são as variáveis de ambiente definidas na secção Configure o seu ambiente e atribuídas às novas variáveis relevantes para o cluster padrão que está a criar.

Quando lhe for pedido, escreva yes. Estes comandos podem demorar vários minutos a serem concluídos e o cluster a apresentar o estado pronto.

O Terraform cria os seguintes recursos:

• Uma rede VPC personalizada e uma sub-rede privada para os nós do Kubernetes.
• Um Cloud Router para aceder à Internet através da tradução de endereços de rede (NAT).
• Um cluster do GKE privado na região us-central1 com a escala automática ativada (um a dois nós por zona).
• Um ServiceAccount com autorizações de registo e monitorização para o cluster.
• Configuração do Google Cloud Managed Service for Prometheus para monitorização e alertas de clusters.

O resultado é semelhante ao seguinte:

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

Estabeleça ligação ao cluster

Configure o kubectl para obter credenciais e comunicar com o seu novo cluster do GKE:

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

Implemente o operador CloudNativePG

Implemente o CloudNativePG no seu cluster do Kubernetes através de um gráfico do Helm:

1. Verifique a versão do Helm:

   helm version
   

   Atualize a versão se for anterior à 3.13:

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

2. Adicione o repositório do gráfico Helm do operador CloudNativePG:

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

3. Implemente o operador CloudNativePG através da ferramenta de linha de comandos Helm:

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

   O resultado é semelhante ao seguinte:

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

Implemente a base de dados vetorial PostgreSQL

Nesta secção, implementa a base de dados vetorial PostgreSQL.

1. Crie um espaço de nomes pg-ns para a base de dados:

   kubectl create ns pg-ns
   

2. Aplique o manifesto para implementar 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 implementaçã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 estado do cluster:

   kubectl get cluster -n pg-ns --watch
   

   Aguarde até que o resultado apresente o estado Cluster in healthy state antes de avançar para o passo seguinte.

Execute consultas com um bloco de notas do Vertex AI Colab Enterprise

Nesta secção, carrega vetores para uma tabela do PostgreSQL e executa consultas de pesquisa semântica através da sintaxe SQL.

Liga-se à sua base de dados PostgreSQL através do Colab Enterprise. Usa um modelo de tempo de execução dedicado para implementar no postgres-vpc, para que o bloco de notas possa 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.

Crie um modelo de tempo de execução

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

1. Na Google Cloud consola, aceda à página Modelos de tempo de execução do Colab Enterprise e certifique-se de que o seu projeto está selecionado:

   Aceda aos modelos do ambiente de execução

2. Clique em Novo modelo. É apresentada a página Criar novo modelo de tempo de execução.

3. Na secção Noções básicas do ambiente de execução:

   • No campo Nome a apresentar, introduza pgvector-connect.
   • Na lista pendente Região, selecione us-central1. É a mesma região que o seu cluster do GKE.

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

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

5. Na secção Redes e segurança:

   • Na lista pendente Rede, selecione a rede onde o seu cluster do GKE reside.
   • Na lista pendente Sub-rede, selecione uma sub-rede correspondente.
   • Desmarque a caixa de verificação Ativar acesso público à Internet.

6. Para concluir a criação do modelo de tempo de execução, clique em Criar. O modelo do ambiente de execução aparece na lista no separador Modelos do ambiente de execução.

Crie um tempo de execução

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

1. Na lista de modelos de tempo de execução do modelo que acabou de criar, na coluna Ações, clique em e, de seguida, clique em Criar tempo de execução. É apresentado o painel Criar tempo de execução do Vertex AI.

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

3. No separador Tempos de execução que é aberto, aguarde que o estado passe a Em bom estado.

Importe o bloco de notas

Para importar o bloco de notas no Colab Enterprise:

1. Aceda ao separador Os meus blocos de notas e clique em Importar. É apresentado o painel Importar blocos de notas.

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

3. Em URLs do notebook, introduza 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.

Ligue-se ao tempo de execução e execute consultas

Para se ligar ao tempo de execução e executar consultas:

1. No bloco de notas, junto ao botão Associar, clique em Opções de associação adicionais. É apresentado o painel Ligar ao tempo de execução do Vertex AI.

2. Selecione Ligar a um tempo de execução e, de seguida, selecione Ligar a um tempo de execução existente.

3. Selecione o tempo de execução que iniciou e clique em Associar.

4. Para executar as células do bloco de notas, clique no botão Executar célula junto a cada célula de código.

O bloco de notas contém células de código e texto que descrevem cada bloqueio de código. A execução de uma célula de código executa os respetivos comandos e apresenta uma saída. Pode executar as células por ordem ou executar células individuais conforme necessário.

Limpar

Para evitar incorrer em custos na sua conta do Google Cloud pelos recursos usados neste tutorial, elimine o projeto que contém os recursos ou mantenha o projeto e elimine os recursos individuais.

Elimine o projeto

A forma mais fácil de evitar a faturação é eliminar o projeto que criou para este tutorial.

Atenção: a eliminação de um projeto tem os seguintes efeitos:

• Tudo no projeto é eliminado. Se usou um projeto existente para as tarefas neste documento, quando o elimina, também elimina qualquer outro trabalho que tenha feito no projeto.
• Os IDs dos projetos personalizados são perdidos. Quando criou este projeto, pode ter criado um ID do projeto personalizado que quer usar no futuro. Para preservar os URLs que usam o ID do projeto, como um URL appspot.com, elimine os recursos selecionados no projeto em vez de eliminar o projeto inteiro.

Se planeia explorar várias arquiteturas, tutoriais ou inícios rápidos, a reutilização de projetos pode ajudar a evitar exceder os limites de quota de projetos.

Delete a Google Cloud project:

gcloud projects delete PROJECT_ID

Se eliminou o projeto, a limpeza está concluída. Se não eliminou o projeto, avance para a eliminação dos recursos individuais.

Elimine 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, consoante o tipo de cluster do GKE que criou.

   Quando lhe for pedido, escreva yes.

O que se segue?

• Explore como implementar clusters PostgreSQL no GKE através do operador CloudNativePG.
• Saiba mais sobre as práticas recomendadas para implementar bases de dados no GKE.
• Descubra soluções para executar cargas de trabalho com grande volume de dados com o GKE.