O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Criar um cluster e a instância principal dele

Para implantar um ambiente de banco de dados para seus aplicativos no AlloyDB para PostgreSQL, crie um cluster e a instância principal dele. O cluster gerencia as configurações regionais de armazenamento e configuração, enquanto a instância principal fornece os recursos de computação para operações de leitura e gravação. É possível criar um cluster e a instância principal dele usando o console do Google Cloud , a Google Cloud CLI, a API REST ou o Terraform.

Antes de começar

O projeto do Google Cloud que você está usando precisa estar ativado para acessar o AlloyDB.
Uma rede de nuvem privada virtual (VPC) no projeto do Google Cloud que você está usando já precisa estar configurada para acesso a serviços particulares ao AlloyDB.
Para cargas de trabalho de desenvolvimento e sandbox, considere sua região e tipo de máquina. Para usar o formato de 1 vCPU, selecione uma região que seja compatível com ele. Para mais informações, consulte Considerações ao usar 1 vCPU.

Funções exigidas

Antes de criar seu primeiro cluster do AlloyDB, você precisa ter os papéis corretos do Identity and Access Management (IAM).

Você precisa ter um destes papéis do IAM no projeto do Google Cloud que está sendo usado:
- roles/alloydb.admin (o papel predefinido do IAM de Admin do AlloyDB)
- roles/owner (o papel básico do IAM de Proprietário)
- roles/editor (o papel básico do IAM de Editor)
Se você não tiver nenhum desses papéis, entre em contato com o Administrador da organização para solicitar o acesso.
Você também precisa ter a permissão compute.networks.list no projeto do Google Cloud que está usando. Para receber essa permissão seguindo o princípio de privilégio mínimo, peça ao administrador para conceder a você o papel de Usuário de rede do Compute (roles/compute.networkUser).

Criar um novo cluster e uma instância primária

Console

Acesse a página Clusters.

Acessar Clusters
Clique em Criar cluster.
Escolha uma configuração de cluster. Para mais informações sobre a diferença entre as configurações básica e de alta disponibilidade, consulte O que é uma instância do AlloyDB?.

Se você não tiver certeza se o novo cluster precisa de instâncias de pool de leitura, escolha uma das configurações sem pools de leitura. É possível adicionar instâncias de pool de leitura ao cluster posteriormente, sempre que necessário.
Clique em Continuar.
Na seção Configurar cluster, no campo ID do cluster, insira um ID para o cluster.
No campo Senha, insira uma senha inicial para o novo cluster. O AlloyDB atribui a senha fornecida ao usuário do banco de dados postgres ao criar o cluster.
Opcional: para definir a flag alloydb.iam_authentication manualmente, desmarque Criar um usuário de banco de dados do IAM. Para mais informações, consulte Configurar flags de banco de dados.

Por padrão, a opção Criar um usuário de banco de dados do IAM está selecionada, o que faz o seguinte:
- Ativa a flag alloydb.iam_authentication na instância principal.
- Cria um usuário de banco de dados do IAM para você.
No campo Versão do banco de dados, selecione a versão principal do PostgreSQL para o novo cluster do AlloyDB.
Selecione uma região. Para cargas de trabalho de desenvolvimento e sandbox, considere o formato de 1 vCPU, que está disponível em algumas regiões. Para mais informações, consulte Considerações ao usar 1 vCPU.
Selecione um caminho de rede.
Opcional: para aplicar um intervalo de endereços IP específico a esse cluster, em vez de permitir que o AlloyDB escolha um intervalo de endereços IP, siga estas etapas:
1. Clique em Mostrar opção de intervalo de IPs alocado.
2. Na lista Intervalo de IP alocado, selecione um intervalo de endereços IP.
Para mais informações sobre essa opção, consulte Criar um cluster com um intervalo de endereços IP específico.
Opcional: para criptografar esse cluster usando uma chave de criptografia gerenciada pelo cliente (CMEK) em vez da criptografia gerenciada pelo Google, siga estas etapas adicionais:
1. Clique em Opções avançadas de criptografia.
2. Selecione Chave de criptografia gerenciada pelo cliente (CMEK).
3. No menu exibido, selecione uma chave gerenciada pelo cliente.
  
  O console do Google Cloud limita essa lista às chaves no mesmo projeto Google Cloud e região do novo cluster. Para usar uma chave que não está nessa lista, clique em Não encontrou sua chave? Insira o nome do recurso da chave e digite o nome do recurso da chave na caixa de diálogo resultante.
  
  O uso da CMEK com o AlloyDB exige algumas configurações adicionais. Para mais informações, consulte Como usar a CMEK com o AlloyDB.
4. Clique em Continuar.
Configure a instância primária:
1. No campo ID da instância, insira um ID para a instância primária.
2. Selecione uma das seguintes séries de máquinas:
  - C4A (série de máquinas baseadas no Google Axion).
  - N2 (série de máquinas baseadas em x86). Essa é a série de máquinas padrão.
  - C4 (série de máquinas baseadas em x86).
  - Z3 (série de máquinas baseadas em Intel Xeon).
3. Selecione um tipo de máquina. Para mais informações, consulte Escolher um tipo de máquina.
  - A C4A é compatível com 1, 2, 4, 8, 16, 32, 48, 64 e 72 vCPUs.
  - A N2 é compatível com 2, 4, 8, 16, 32, 64, 96 e 128 vCPUs.
  - A C4 é compatível com 4, 8, 16, 24, 32, 48, 96, 144, 192 e 288 vCPUs.
  - A Z3 é compatível com 8, 14, 16, 22, 32, 44 e 88 vCPUs.
  Para mais informações sobre como usar a série de máquinas C4A baseada em Axion, incluindo o tipo de máquina com 1 vCPU, consulte Considerações ao usar a série de máquinas C4A baseada em Axion.
4. Opcional: defina flags personalizadas para sua instância. Para cada flag, siga estas etapas:
  1. Clique em Adicionar flag.
  2. Na lista Nova flag de banco de dados, selecione uma flag.
  3. Forneça um valor para a flag.
  4. Clique em Concluído.
Clique em Criar cluster.

Observação: depois de criar o cluster, é possível monitorar a integridade dele e das instâncias usando problemas de integridade priorizados no console do Google Cloud . Para mais informações, consulte Monitorar a integridade dos clusters e instâncias do AlloyDB.

gcloud

Para usar a CLI gcloud, você pode instalar e inicializar a Google Cloud CLI ou usar o Cloud Shell.

É necessário criar um cluster do AlloyDB e uma instância primária antes de começar a usar o AlloyDB.

Criar um cluster

Para criar o cluster com o acesso a serviços particulares ou o Private Service Connect ativado, use o comando gcloud alloydb clusters create.
Acesso privado a serviços
gcloud alloydb clusters create CLUSTER_ID \ --database-version=POSTGRES_VERSION \ --password=PASSWORD \ --region=REGION_ID \ --project=PROJECT_ID \ --network=NETWORK
Private Service Connect
gcloud alloydb clusters create CLUSTER_ID \ --database-version=POSTGRES_VERSION \ --password=PASSWORD \ --region=REGION_ID \ --project=PROJECT_ID \ --enable-private-service-connect
Substitua:
- CLUSTER_ID: o ID do cluster que você está criando. Ele precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.
- VERSION: a versão principal do PostgreSQL com que você quer que os servidores de banco de dados do cluster sejam compatíveis. Escolha uma destas opções:
  - 14, para compatibilidade com o PostgreSQL 14
  - 15, para compatibilidade com o PostgreSQL 15
  - 16, para compatibilidade com o PostgreSQL 16
  - 17, para compatibilidade com o PostgreSQL 17, que é a versão padrão compatível do PostgreSQL
  - 18, para compatibilidade com o PostgreSQL 18
- PASSWORD: a senha a ser usada para o usuário padrão postgres.
- NETWORK (opcional): o nome da rede VPC configurada para acesso a serviços particulares ao AlloyDB. Se você omitir a flag --network, o AlloyDB vai usar a rede default.
  
  Se você estiver usando uma rede VPC compartilhada, defina o caminho totalmente qualificado da rede VPC, por exemplo, projects/cymbal-project/global/networks/shared-vpc-network.
- --enable-private-service-connect (opcional): defina para ativar o Private Service Connect como o método de conectividade para o cluster e as instâncias dele.
- REGION_ID: a região em que você quer colocar o cluster.
Observação :para cargas de trabalho de desenvolvimento e sandbox, considere o formato de 1 vCPU, que está disponível em algumas regiões. Para mais informações, consulte Considerações ao usar 1 vCPU.
- PROJECT_ID: o ID do projeto em que você quer colocar o cluster.
Esse comando inicia uma operação de longa duração e retorna um ID de operação.
Opcional: para aplicar um intervalo de endereços IP específico a esse cluster, em vez de permitir que o AlloyDB escolha um intervalo de endereços IP, forneça o seguinte argumento:
```
--allocated-ip-range-name=RANGE
```
Substitua RANGE pelo nome do intervalo de endereços IP que você quer que esse cluster use para acesso a serviços particulares.

Para mais informações sobre essa opção, consulte Criar um cluster com um intervalo de endereços IP específico.
Opcional: para criptografar esse cluster usando uma chave de criptografia gerenciada pelo cliente (CMEK) em vez da criptografia padrão gerenciada pelo Google, forneça os seguintes argumentos:
```
--kms-key=KEY_ID \
--kms-keyring=KEYRING_ID \
--kms-location=LOCATION_ID \
--kms-project=PROJECT_ID
```
Substitua:
- KEY_ID: o ID da chave CMEK a ser usada.
- KEYRING_ID: o ID do keyring da chave.
- LOCATION_ID: o ID da região do keyring, que precisa ser igual à região do cluster.
- PROJECT_ID: o ID do projeto do keyring.
Observação :o uso da CMEK exige algumas configurações adicionais. Para mais informações, consulte Como usar a CMEK com o AlloyDB.

Confirme se a operação foi bem-sucedida.

gcloud alloydb operations describe OPERATION_ID \
    --region=REGION_ID \
    --project=PROJECT_ID

Substitua OPERATION_ID pelo ID da operação retornado na etapa anterior.

Depois de criar o cluster principal, você precisa criar uma instância principal.

Criar uma instância principal

Para criar uma instância principal, use o comando gcloud alloydb instances create.

    gcloud alloydb instances create INSTANCE_ID \
        --instance-type=PRIMARY \
        --region=REGION_ID \
        --cluster=CLUSTER_ID \
        --project=PROJECT_ID \
        --cpu-count=CPU_COUNT \
        --machine-type=MACHINE_TYPE \
        --allowed-psc-projects=ALLOWED_PROJECT_LIST

Substitua:

INSTANCE_ID: o ID da instância que você está criando. Ele precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.
REGION_ID: a região em que você quer que a instância esteja localizada.
CLUSTER_ID: o ID do cluster que você criou anteriormente.
PROJECT_ID: o ID do projeto em que o cluster foi criado.
CPU_COUNT: o número de vCPUs que você quer para a instância.
- É preciso especificar cpu_count ou machine_type.
- Se apenas cpu_count for fornecido, uma instância N2 será criada com as seguintes especificações:
  - 2: 2 vCPUs, 16 GB de RAM
  - 4: 4 vCPUs, 32 GB de RAM
  - 8: 8 vCPUs, 64 GB de RAM
  - 16: 16 vCPUs, 128 GB de RAM
  - 32: 32 vCPUs, 256 GB de RAM
  - 64: 64 vCPUs, 512 GB de RAM
  - 96: 96 vCPUs, 768 GB de RAM
  - 128: 128 vCPUs, 864 GB de RAM
- Se machine_type e cpu_count forem fornecidos, o valor de cpu_count precisará estar alinhado ao número de vCPUs especificado em machine_type. Por exemplo, se machine_type for n2-highmem-4, defina cpu_count como 4.
MACHINE_TYPE: selecione em uma lista de tipos de máquina compatíveis, como n2-highmem-4, c4-highmem-4-lssd ou c4a-highmem-4-lssd. Para mais informações, consulte Escolher um tipo de máquina do AlloyDB.

Quando você usa machine_type e cpu_count juntos, os valores em cpu_count e machine_type precisam ser iguais. Por exemplo, se machine_type for n2-highmem-4, defina cpu_count como 4.
ALLOWED_PROJECT_LIST: (opcional) se você estiver usando o Private Service Connect, ALLOWED_PROJECT_LIST é a lista separada por vírgulas de IDs de projeto ou o número do projeto que você quer permitir que acesse a instância.

Terraform

Criar um cluster e uma instância principal

Para criar um cluster e a instância primária dele, use um recurso do Terraform.

Confira a seguir um snippet de código para criar um cluster e uma instância principal com base no exemplo Instância completa do AlloyDB:

resource "google_alloydb_instance" "default" {
  cluster       = google_alloydb_cluster.default.name
  instance_id   = "alloydb-instance"
  instance_type = "PRIMARY"
  machine_config {
    cpu_count = 2
  }
  depends_on = [google_service_networking_connection.vpc_connection]
}

resource "google_alloydb_cluster" "default" {
  cluster_id       = "alloydb-cluster"
  location         = "us-central1"
  network_config {
    network = google_compute_network.default.id
  }
  database_version = "POSTGRES_17"
  initial_user {
    password = "alloydb-cluster"
  }
}

data "google_project" "project" {}

resource "google_compute_network" "default" {
  name = "alloydb-network"
}

resource "google_compute_global_address" "private_ip_alloc" {
  name          = "alloydb-cluster"
  address_type  = "INTERNAL"
  purpose       = "VPC_PEERING"
  prefix_length = 16
  network       = google_compute_network.default.id
}

resource "google_service_networking_connection" "vpc_connection" {
  network                 = google_compute_network.default.id
  service                 = "servicenetworking.googleapis.com"
  reserved_peering_ranges = [google_compute_global_address.private_ip_alloc.name]
}

Este exemplo cria uma instância N2. Para uma lista de outros tipos de máquina compatíveis, como n2-highmem-4, c4-highmem-4-lssd ou c4a-highmem-4-lssd, consulte Escolher um tipo de máquina do AlloyDB.

Preparar o Cloud Shell

Para aplicar a configuração do Terraform em um projeto do Google Cloud , prepare o Cloud Shell da seguinte maneira:

Inicie o Cloud Shell.
Defina o projeto padrão do Google Cloud em que você quer aplicar as configurações do Terraform.

Você só precisa executar esse comando uma vez por projeto, e ele pode ser executado em qualquer diretório.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
As variáveis de ambiente serão substituídas se você definir valores explícitos no arquivo de configuração do Terraform.

Preparar o diretório

Cada arquivo de configuração do Terraform precisa ter o próprio diretório, também chamado de módulo raiz.

No Cloud Shell, crie um diretório e um novo arquivo dentro dele. O nome de arquivo precisa ser um arquivo TF, por exemplo, main.tf. Neste documento, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Copie o exemplo de código no main.tf recém-criado. Se preferir, copie o código do GitHub. Isso é recomendado quando o snippet do Terraform faz parte de uma solução de ponta a ponta.
Revise o arquivo main.tf e modifique os parâmetros de amostra para aplicar ao seu ambiente.
Salve as alterações.
Inicialize o Terraform. Você só precisa fazer isso uma vez por diretório.
```
terraform init
```
Opcional: para usar a versão mais recente do provedor do Google, inclua a opção -upgrade:
```
terraform init -upgrade
```

Aplique as alterações

Revise a configuração para confirmar se as atualizações do Terraform correspondem às suas expectativas:
```
terraform plan
```
Faça as correções necessárias na configuração.
Para aplicar a configuração do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```
Aguarde até que o Terraform exiba a mensagem Apply complete!.
Abra seu projeto do Google Cloud para ver os resultados. No console do Google Cloud , navegue até seus recursos na UI para verificar se foram criados ou atualizados pelo Terraform.

REST v1

Criar um cluster

Este exemplo cria um cluster. Para uma lista completa de parâmetros dessa chamada, consulte Método: projects.locations.clusters.create. Para informações sobre as configurações do cluster, consulte Ver as configurações do cluster e da instância.

Não inclua informações sensíveis ou de identificação pessoal no ID do cluster, porque ele é visível externamente. Não é necessário incluir o ID do projeto no nome do cluster. Isso é feito automaticamente quando necessário, como nos arquivos de registros.

Para enviar a solicitação, salve o corpo dela em um arquivo chamado cluster_request.json:

{
  "databaseVersion": "<var>DATABASE_VERSION</var>",
  "initialUser": {
    "user": "<var>INITIAL_USERNAME</var>",
    "password": "<var>INITIAL_USER_PASSWORD</var>"
  },
  "labels": {
    "test": "alloydb-cluster-full"
  }
}

Faça as seguintes substituições:

DATABASE_VERSION: string de tipo enumerado da versão do banco de dados, por exemplo, POSTGRES_17.
INITIAL_USERNAME: o nome de usuário que você usa para o usuário padrão do postgres.
INITIAL_USER_PASSWORD: a senha que você usa para o usuário postgres padrão.

Use o seguinte método HTTP e URL:

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID

Faça as seguintes substituições:

PROJECT_ID: o ID do projeto em que você quer que o cluster esteja localizado.
LOCATION_ID: o ID da região do cluster.
CLUSTER_ID: o ID do cluster que você está criando. O ID do cluster precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.

Use o curl a seguir para executar a solicitação anterior:

curl -X POST   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters?cluster_id=CLUSTER_ID   -d @cluster_request.json

Criar uma instância principal

Este exemplo cria uma instância primária. Para uma lista completa de parâmetros dessa chamada, consulte Método: projects.locations.clusters.instances.create. Para informações sobre as configurações do cluster, consulte Ver as configurações do cluster e da instância.

Não inclua informações confidenciais ou de identificação pessoal no ID do cluster, porque ele é visível externamente. Não é necessário incluir o ID do projeto no nome do cluster, porque isso é feito automaticamente quando apropriado, por exemplo, nos arquivos de registro.

Para enviar sua solicitação, salve o corpo da solicitação a seguir em um arquivo chamado instance_request.json.

{
  "instance_type": "PRIMARY",
  "machine_config": {
    "cpu_count": VCPU_COUNT
  }
}

Faça a seguinte substituição:

VCPU_COUNT: o número de núcleos de CPU visíveis na instância que você quer criar.

O exemplo anterior cria uma instância N2 com as seguintes especificações:

2: 2 vCPUs, 16 GB de RAM
4: 4 vCPUs, 32 GB de RAM
8: 8 vCPUs, 64 GB de RAM
16: 16 vCPUs, 128 GB de RAM
32: 32 vCPUs, 256 GB de RAM
64: 64 vCPUs, 512 GB de RAM
96: 96 vCPUs, 768 GB de RAM
128: 128 vCPUs, 864 GB de RAM

O exemplo a seguir mostra como criar uma instância para um tipo de máquina:

"machine_config": {
  "machine_type": "MACHINE_TYPE"
}

Substitua MACHINE_TYPE por um tipo de máquina compatível, como n2-highmem-4, c4-highmem-4-lssd ou c4a-highmem-4-lssd. Para mais informações sobre os tipos de máquina compatíveis, consulte Escolher um tipo de máquina do AlloyDB.

Use o seguinte método HTTP e URL:

POST https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID

Faça as seguintes substituições:

PROJECT_ID: o ID do projeto em que você quer colocar o cluster.
LOCATION_ID: o ID da região do cluster.
CLUSTER_ID: o ID do cluster que você está criando. O ID precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.
INSTANCE_ID: o nome da instância primária que você quer criar.

Use curl para executar a solicitação, conforme mostrado no exemplo a seguir:

curl -X POST   -H "Authorization: Bearer $(gcloud auth print-access-token)"   -H "Content-Type: application/json"   https://alloydb.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/clusters/CLUSTER_ID/instances?instance_id=INSTANCE_ID   -d @instance_request.json

Clonar um cluster ativo

Para criar um clone de um cluster ativo, que contenha uma cópia de todos os dados do cluster de origem e seja executado na mesma região, realize uma recuperação pontual nesse cluster. É possível especificar um momento muito recente ao fazer isso, por exemplo, o primeiro segundo do minuto atual.

Esse processo copia apenas os dados do cluster de origem para o clone, não as configurações do cluster de origem. Para criptografar os dados do clone usando CMEK, é preciso especificar os detalhes da CMEK como parte do comando de recuperação pontual, mesmo que os dados do cluster de origem já estejam criptografados com CMEK. Depois que o novo cluster for criado, você precisará adicionar instâncias, flags de banco de dados, programações de backup e qualquer outra configuração necessária para atender às suas necessidades.

Um cluster criado dessa forma existe de maneira independente da origem, e os dados dele não têm relação com os dados do cluster de origem depois que a duplicação inicial é concluída. Se você quiser criar clusters secundários que rastreiem e repliquem automaticamente as alterações de dados feitas nos clusters de origem, consulte Sobre a replicação entre regiões.

Criar um cluster com um intervalo de endereços IP específico

O AlloyDB usa o acesso a serviços particulares para permitir que os recursos internos de um cluster se comuniquem entre si. Antes de criar um cluster, sua rede VPC precisa conter pelo menos um intervalo de endereços IP configurado com uma conexão de acesso a serviços particulares.

Considerações ao usar a série de máquinas C4A baseada em Axion

O AlloyDB oferece uma série de máquinas C4A baseada no Google Axion, o processador personalizado do Google baseado em Arm. As máquinas virtuais (VM) C4A estão disponíveis como configurações predefinidas para 1, 2, 4, 8, 16, 32, 48, 64 e 72 vCPUs, com até 576 GB de memória Double Data Rate 5 (DDR5).

Ao escolher a C4A, lembre-se do seguinte:

Para mudar uma instância N2 para uma C4A, modifique o machine_type da instância atual usando o console do Google Cloud , a CLI gcloud, o Terraform ou a API.
Não exclua a instância N2 e crie uma nova instância C4A no mesmo cluster.

O C4A está disponível nas seguintes regiões:

asia-east1
asia-southeast1
europe-west1
europe-west2
europe-west3
europe-west4
us-central1
us-east1
us-east4

Considerações ao usar o tipo de máquina com 1 vCPU

O AlloyDB oferece um formato de 1 vCPU com C4A e é destinado apenas para fins de desenvolvimento e teste. Para cargas de trabalho de produção, escolha duas ou mais vCPUs.

Ao escolher 1 vCPU, lembre-se das seguintes limitações:

1 vCPU é oferecida com 8 GB de memória sem suporte a cache ultrarrápido.
A configuração de 1 vCPU é recomendada para ambientes de desenvolvimento e sandbox com bancos de dados menores, na casa das dezenas de gigabytes. Para bancos de dados maiores e cargas de trabalho de produção, use 2 vCPUs ou mais.
É possível configurar com alta disponibilidade (HA), mas não são oferecidos SLAs de tempo de atividade.
Para saber onde é possível implantar 1 vCPU, consulte Regiões com disponibilidade C4A.

Criar um cluster e a instância principal dele Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Funções exigidas

Criar um novo cluster e uma instância primária

Console

gcloud

Criar um cluster

Acesso privado a serviços

Private Service Connect

Criar uma instância principal

Terraform

Criar um cluster e uma instância principal

Preparar o Cloud Shell

Preparar o diretório

Aplique as alterações

REST v1

Criar um cluster

Criar uma instância principal

Clonar um cluster ativo

Criar um cluster com um intervalo de endereços IP específico

Considerações ao usar a série de máquinas C4A baseada em Axion

O C4A está disponível nas seguintes regiões:

Considerações ao usar o tipo de máquina com 1 vCPU

A seguir

Criar um cluster e a instância principal dele