Criar e gerenciar clusters do AlloyDB Express

Neste documento, descrevemos como criar, conectar, editar, visualizar, excluir e fazer upgrade de clusters e instâncias do AlloyDB Express.

Para mais informações sobre como os recursos do AlloyDB Express são diferentes dos recursos do AlloyDB, consulte Visão geral do AlloyDB Express. Para criar um cluster do AlloyDB, consulte Criar um cluster e a instância principal dele.

Antes de começar

Antes de criar ou gerenciar clusters do AlloyDB Express, conclua os seguintes pré-requisitos:

Funções exigidas

Para receber as permissões necessárias para criar e gerenciar clusters e instâncias do AlloyDB Express, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Criar um cluster e uma instância do AlloyDB Express

É possível criar um cluster do AlloyDB Express e a instância primária dele usando o console do Google Cloud , a Google Cloud CLI, a API REST do AlloyDB ou o servidor MCP remoto do AlloyDB.

Um cluster do AlloyDB Express é compatível com o PostgreSQL 18 e contém uma única instância primária zonal que começa com 1 vCPU (4 GB de RAM) e dimensiona o armazenamento automaticamente até 20 GB. Se você planeja fazer upgrade de uma instância de 1 vCPU para o AlloyDB mais tarde sem redimensionar para 2 vCPUs, crie o cluster em uma região que também seja compatível com a série de máquinas C4A.

As configurações de conectividade padrão dependem da ferramenta que você usa:

  • Google Cloud Console: ativa o DNS público na instância principal e o Private Service Connect no cluster por padrão. É possível configurar os projetos de consumidor do Private Service Connect Google Cloud mais tarde, editando as configurações de conectividade da instância.

  • CLI gcloud, API REST e servidor MCP remoto do AlloyDB: ativa apenas o Private Service Connect no cluster por padrão. Ao criar a instância principal, ative o DNS público se quiser se conectar por ele e inclua na lista de permissões os projetos de consumidor doGoogle Cloud em que você quer criar endpoints do Private Service Connect para a instância.

Console

  1. No console do Google Cloud , acesse a página Começar.

    Acesse "Começar".

    Se o projeto do Google Cloud já tiver clusters e você começar na página Clusters, clique em Criar cluster na barra de ferramentas para abrir a página Selecionar configuração. As duas páginas mostram cards de configuração de cluster predefinidos (AlloyDB Express, Produção (zona única) e Produção (multizona)).

  2. No card AlloyDB Express, clique em Criar cluster para abrir o painel Criar um cluster do AlloyDB Express.

  3. No painel Criar um cluster do AlloyDB Express, configure o cluster:

  4. Clique em Criar cluster.

    O console do Google Cloud cria o cluster do AlloyDB Express e a instância principal de 1 vCPU com o Private Service Connect e o DNS público ativados por padrão. Em seguida, ele abre o AlloyDB Studio para que você possa consultar o banco de dados.

    Não é possível alterar as configurações de conectividade durante a criação do cluster no console doGoogle Cloud , mas é possível atualizar as redes externas autorizadas ou as configurações do Private Service Connect mais tarde, editando as configurações de conectividade da instância.

gcloud

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

  1. Para criar um cluster do AlloyDB Express, execute o comando gcloud beta alloydb clusters create com a flag --enable-express:

    gcloud beta alloydb clusters create CLUSTER_ID \
    --region=REGION_ID \
    --password=PASSWORD \
    --enable-express \
    --project=PROJECT_ID

    Substitua:

    • CLUSTER_ID: o ID do cluster que você quer criar. O ID precisa começar com uma letra minúscula e pode conter letras minúsculas, números e hifens.
    • REGION_ID: a região com disponibilidade em que você quer criar o cluster. Se você planeja fazer upgrade de uma instância de 1 vCPU para o AlloyDB mais tarde, sem redimensionar para 2 vCPUs, escolha uma região que também seja compatível com a série de máquinas C4A.
    • PASSWORD: a senha inicial do usuário padrão do banco de dados postgres.
    • PROJECT_ID: o ID do projeto doGoogle Cloud em que você quer criar o cluster.

  2. Para criar a instância principal no cluster do AlloyDB Express, execute o comando gcloud beta alloydb instances create e escolha as flags de conectividade:

    • Somente DNS público: especifique --enable-public-dns e omita --allowed-psc-projects.
    • Somente Private Service Connect: omita --enable-public-dns e especifique --allowed-psc-projects=ALLOWED_PROJECT_ID para permitir conexões do Private Service Connect do seu projeto Google Cloud consumidor.
    • DNS público e Private Service Connect: especifique --enable-public-dns e --allowed-psc-projects=ALLOWED_PROJECT_ID.
    gcloud beta alloydb instances create INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --instance-type=PRIMARY \
    --cpu-count=1 \
    --enable-public-dns \
    --allowed-psc-projects=ALLOWED_PROJECT_ID \
    --project=PROJECT_ID

    Substitua:

    • INSTANCE_ID: o ID da instância principal que você quer criar.
    • ALLOWED_PROJECT_ID (opcional): uma lista separada por vírgulas de IDs ou números de projetos do Google Cloud que podem criar endpoints do Private Service Connect para essa instância. Omita --allowed-psc-projects se estiver configurando apenas o DNS público.

REST

  1. Para criar um cluster do AlloyDB Express, envie uma solicitação POST para o endpoint projects.locations.clusters.create com expressConfig.enabled definido como true.

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • REGION_ID: a região com disponibilidade em que você quer criar o cluster. Se você planeja fazer upgrade de uma instância de 1 vCPU para o AlloyDB mais tarde, sem redimensionar para 2 vCPUs, escolha uma região que também seja compatível com a série de máquinas C4A.
    • CLUSTER_ID: o ID do cluster que você quer criar.
    • INITIAL_USERNAME: o nome de usuário do usuário inicial do banco de dados (por exemplo, postgres).
    • INITIAL_USER_PASSWORD: a senha do usuário inicial do banco de dados.

    Método HTTP e URL:

    POST https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters?clusterId=CLUSTER_ID

    Corpo JSON da solicitação:

    {
  "databaseVersion": "POSTGRES_18",
  "expressConfig": {
    "enabled": true
  },
  "initialUser": {
    "user": "INITIAL_USERNAME",
    "password": "INITIAL_USER_PASSWORD"
  }
}

  2. Depois que a operação de criação do cluster for concluída, crie a instância principal enviando uma solicitação POST para o endpoint projects.locations.clusters.instances.create com machineConfig.cpuCount definido como 1 (especificar qualquer valor diferente de 1 falha na criação). Escolha os campos de conectividade no corpo da solicitação:

    • Somente DNS público: defina "networkConfig": {"publicDnsEnabled": true} e omita "pscInstanceConfig".
    • Somente Private Service Connect: omita "publicDnsEnabled" (que tem como padrão false) e defina "pscInstanceConfig": {"allowedConsumerProjects": ["ALLOWED_PROJECT_ID"]}.
    • DNS público e Private Service Connect: inclua "networkConfig": {"publicDnsEnabled": true} e "pscInstanceConfig": {"allowedConsumerProjects": ["ALLOWED_PROJECT_ID"]}.

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    • INSTANCE_ID: o ID da instância principal que você quer criar.
    • ALLOWED_PROJECT_ID (opcional): os Google Cloud IDs do projeto ou números de projeto que podem criar endpoints do Private Service Connect para essa instância.

    Método HTTP e URL:

    POST https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances?instanceId=INSTANCE_ID

    Corpo JSON da solicitação:

    {
  "instanceType": "PRIMARY",
  "availabilityType": "ZONAL",
  "machineConfig": {
    "cpuCount": 1
  },
  "networkConfig": {
    "publicDnsEnabled": true
  },
  "pscInstanceConfig": {
    "allowedConsumerProjects": [
      "ALLOWED_PROJECT_ID"
    ]
  }
}

MCP

Você pode usar um cliente MCP ou chamar o servidor MCP remoto do AlloyDB diretamente para criar um cluster do AlloyDB Express e a instância principal dele.

Em um cliente MCP, é possível usar um único comando para criar o cluster do AlloyDB Express e a instância principal dele. Seu cliente MCP chama automaticamente create_cluster, pesquisa get_operation e chama create_instance:

Create an AlloyDB Express cluster named CLUSTER_ID in REGION_ID with a primary instance named INSTANCE_ID.

Para executar cada etapa individualmente ou chamar as ferramentas do MCP diretamente, siga estas etapas:

  1. Para criar um cluster do AlloyDB Express, insira um comando no cliente MCP ou chame a ferramenta MCP create_cluster com express_config.enabled definido como true.

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    No cliente MCP, insira um comando semelhante ao seguinte:

    Create an AlloyDB Express cluster named CLUSTER_ID in REGION_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_cluster",
    "arguments": {
      "parent": "projects/PROJECT_ID/locations/REGION_ID",
      "cluster_id": "CLUSTER_ID",
      "express_config": {
        "enabled": true
      }
    }
  }
}

    Para tornar o Private Service Connect acessível em uma rede VPC, inclua na lista de permissões os projetos de consumidor Google Cloud em "psc_instance_config" ao criar ou atualizar a instância principal.

  2. A ferramenta create_cluster retorna uma operação de longa duração. Sonde o status da operação usando a ferramenta MCP get_operation até que done seja true e o cluster esteja no estado READY.

  3. Para criar a instância principal no cluster do AlloyDB Express, insira um comando no cliente MCP ou chame a ferramenta MCP create_instance. Escolha as configurações de conectividade:

    • Somente DNS público: defina "public_dns_enabled": true e omita "psc_instance_config".

    • Somente Private Service Connect: omita "public_dns_enabled" (que tem como padrão false) e defina "psc_instance_config" com "allowed_consumer_projects" (ou "psc_auto_connections" especificando "consumer_project" e "consumer_network").

    • DNS público e Private Service Connect: defina "public_dns_enabled": true e "psc_instance_config".

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    • INSTANCE_ID: o ID da instância principal que você quer criar.

    • ALLOWED_PROJECT_ID: opcional: os Google Cloud IDs do projeto ou números de projeto que podem criar endpoints do Private Service Connect para essa instância.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please create a primary instance named INSTANCE_ID in my AlloyDB Express cluster CLUSTER_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "create_instance",
    "arguments": {
      "parent": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID",
      "instance_id": "INSTANCE_ID",
      "type": "PRIMARY",
      "public_dns_enabled": true,
      "psc_instance_config": {
        "allowed_consumer_projects": [
          "ALLOWED_PROJECT_ID"
        ]
      }
    }
  }
}

  4. Sonde a operação de criação de instância usando a ferramenta MCP get_operation até que done seja true e a instância esteja no estado READY.

Conectar-se a uma instância do AlloyDB Express

O AlloyDB Express é compatível com as seguintes opções de conectividade de banco de dados de entrada:

  • DNS público (padrão): fornece um nome DNS roteável publicamente (networkInfo.publicDnsName) para que você possa se conectar de clientes fora de uma rede VPC.
  • Private Service Connect: permite que você se conecte de maneira privada à sua instância de dentro da rede VPC usando endpoints do Private Service Connect sem expor o banco de dados à Internet pública.

Conectar por DNS público

Ao se conectar por DNS público de fora de uma rede VPC, é possível fazer o seguinte:

Conectar-se diretamente usando um cliente PostgreSQL

Por padrão, o endpoint de DNS público rejeita todos os endereços IP de clientes diretos. É preciso colocar os blocos CIDR do cliente na lista de permissões antes de se conectar diretamente com o psql.

  1. Configure redes externas autorizadas na instância principal.

    Não é possível adicionar nem remover redes externas autorizadas individualmente. Cada atualização substitui a lista atual. Forneça uma lista separada por vírgulas de todos os blocos CIDR que você quer permitir.

    Console

    1. No Google Cloud console, acesse a página Clusters.

      Acessar Clusters

    2. Na coluna Nome do recurso, clique no nome do cluster do AlloyDB Express.

    3. Na página Visão geral, acesse Instâncias no seu cluster, localize a instância primária e clique em Ações da instância > Editar (ou acesse Conectividade no menu de navegação e clique em Editar).

    4. Em Conectividade, verifique se a conectividade pública está ativada.

    5. Em Redes externas autorizadas, insira uma lista separada por vírgulas de intervalos CIDR IPv4 (por exemplo, 203.0.113.0/24) ou clique em Usar meu IP para adicionar o endereço IPv4 /32 da sua máquina atual.

    6. Clique em Atualizar instância.

    gcloud

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

    Execute o comando gcloud alloydb instances update com a flag --authorized-external-networks:

    gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --authorized-external-networks=CIDR_RANGE1,CIDR_RANGE2 \
    --project=PROJECT_ID

    Substitua:

    • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
    • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
    • REGION_ID: a região em que o cluster está localizado.
    • CIDR_RANGE1, CIDR_RANGE2: uma lista separada por vírgulas de intervalos de endereços IPv4 em notação CIDR (por exemplo, 203.0.113.0/24).
    • PROJECT_ID: o ID do seu projeto do Google Cloud .

    REST

    Envie uma solicitação PATCH para o endpoint projects.locations.clusters.instances.patch com updateMask=networkConfig.authorizedExternalNetworks.

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .
    • REGION_ID: a região em que o cluster está localizado.
    • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
    • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
    • CIDR_RANGE1, CIDR_RANGE2: intervalos de endereços IPv4 na notação CIDR (por exemplo, 203.0.113.0/24).

    Método HTTP e URL:

    PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=networkConfig.authorizedExternalNetworks

    Corpo JSON da solicitação:

    {
  "networkConfig": {
    "authorizedExternalNetworks": [
      {
        "cidrRange": "CIDR_RANGE1"
      },
      {
        "cidrRange": "CIDR_RANGE2"
      }
    ]
  }
}

    MCP

    Insira um comando no cliente MCP ou chame a ferramenta MCP update_instance com o campo authorized_external_networks.

    Antes de usar os dados da solicitação, faça as substituições a seguir:

    • PROJECT_ID: o ID do seu projeto do Google Cloud .

    • REGION_ID: a região em que o cluster está localizado.

    • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

    • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

    • CIDR_RANGE1, CIDR_RANGE2: intervalos de endereços IPv4 na notação CIDR, como 203.0.113.0/24.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please update the AlloyDB instance INSTANCE_ID in cluster CLUSTER_ID to allow external connections from CIDR_RANGE1.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_instance",
    "arguments": {
      "instance": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID",
      "authorized_external_networks": [
        "CIDR_RANGE1",
        "CIDR_RANGE2"
      ]
    }
  }
}

  2. Recupere o nome DNS público da instância:

    Console

    1. No console do Google Cloud , acesse a página Clusters e clique no nome do cluster do AlloyDB Express.
    2. Acesse Conectividade (ou confira o card da instância principal na página Visão geral) e copie o nome de DNS público da instância.

    gcloud

    Execute o comando gcloud beta alloydb instances describe para recuperar o valor de networkInfo.publicDnsName:

    gcloud beta alloydb instances describe INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --format="value(networkInfo.publicDnsName)" \
    --project=PROJECT_ID

    A saída usa o seguinte formato:

    IDENTIFIER.IDENTIFIER.REGION_ID.alloydb.s.cloud.goog

    Nessa saída, IDENTIFIER é um identificador alfanumérico gerado pelo sistema.

    REST

    Envie uma solicitação GET para o endpoint projects.locations.clusters.instances.get e leia o campo networkInfo.publicDnsName da resposta:

    GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

    MCP

    Insira um comando no cliente MCP ou chame a ferramenta MCP get_instance e leia o campo networkInfo.publicDnsName da resposta.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please get the public DNS name of the AlloyDB instance INSTANCE_ID in cluster CLUSTER_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_instance",
    "arguments": {
      "name": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID"
    }
  }
}

  3. Conecte-se ao banco de dados usando um URI de conexão padrão do PostgreSQL e o nome DNS público da instância:

    psql postgresql://USERNAME@PUBLIC_DNS_NAME/DATABASE_NAME

    Substitua:

    • USERNAME: o nome de usuário do banco de dados PostgreSQL (por exemplo, postgres).
    • PUBLIC_DNS_NAME: o nome DNS público da instância do AlloyDB Express (por exemplo, 1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d.a.us-central1.alloydb.s.cloud.goog).
    • DATABASE_NAME: o nome do banco de dados a ser conectado (o banco de dados padrão é postgres).

  4. Quando solicitado, digite a senha do usuário do banco de dados.

Conectar usando CLI gcloud ou o proxy de autenticação

Para se conectar por DNS público sem configurar redes externas autorizadas, use o comando gcloud beta alloydb connect ou o cliente de proxy de autenticação independente (alloydb-auth-proxy) com a flag --public-ip. Embora o AlloyDB Express exiba um nome de DNS público em vez de um endereço IP público, o plano de controle provisiona uma conexão pública subjacente para a instância que o proxy de autenticação resolve automaticamente quando você especifica --public-ip.

Para iniciar uma instância local do proxy de autenticação e abrir uma sessão psql usando a CLI gcloud, execute o comando gcloud beta alloydb connect com a flag --public-ip:

gcloud beta alloydb connect INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --public-ip \
    --user=USERNAME \
    --database=DATABASE_NAME \
    --project=PROJECT_ID

Substitua:

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • REGION_ID: a região em que o cluster está localizado.
  • USERNAME: o nome de usuário do banco de dados (o padrão é postgres).
  • DATABASE_NAME: o nome do banco de dados (o padrão é postgres).
  • PROJECT_ID: o ID do seu projeto do Google Cloud .

Para mais informações sobre como se conectar com a CLI gcloud, incluindo a autenticação de banco de dados do IAM (--auto-iam-authn), consulte Conectar usando a gcloud CLI.

Como alternativa, é possível baixar e executar o cliente do proxy de autenticação independente com a flag --public-ip:

./alloydb-auth-proxy \
    "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID" \
    --public-ip

Para informações sobre como fazer o download, configurar e se conectar pelo cliente independente do proxy de autenticação, consulte Conectar usando o proxy de autenticação do AlloyDB.

Conectar pelo Private Service Connect

Para conectividade privada na sua rede VPC sem expor o banco de dados à Internet pública, configure o Private Service Connect na instância do AlloyDB Express. É possível se conectar a um endpoint do Private Service Connect diretamente de um cliente na sua rede VPC ou usando o proxy de autenticação. Para mais informações sobre como se conectar ao Private Service Connect, consulte Conectar-se a uma instância usando o Private Service Connect.

Ao seguir essas instruções para o AlloyDB Express, crie seu cluster e uma instância primária zonal de 1 vCPU, conforme descrito em Criar um cluster e uma instância do AlloyDB Express com o Private Service Connect ativado. O AlloyDB Express oferece suporte à conectividade de entrada do Private Service Connect com uma única instância primária zonal.

Editar uma instância do AlloyDB Express

É possível atualizar a contagem de CPUs (1 vCPU ou 2 vCPUs) ou as flags de banco de dados de uma instância principal do AlloyDB Express.

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Na coluna Nome do recurso, clique no nome do cluster do AlloyDB Express.

  3. Na página Visão geral, na seção Instâncias no cluster, localize a instância primária e clique em Editar primária (ou clique em Ações da instância > Editar).

  4. Na página Editar instância principal, atualize as configurações da instância:

    • Em Máquina, na lista Tipo de máquina, selecione 1 vCPU, 4 GB ou 2 vCPU, 8 GB.
    • Opcional: para configurar flags de banco de dados, expanda Flags (ou clique em Mostrar opções avançadas e expanda Flags) e clique em Adicionar flag. Selecione uma flag na lista Nova flag de banco de dados, forneça um valor e clique em Concluído.

  5. Clique em Atualizar instância.

gcloud

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

Para escalonar a instância alterando a contagem de CPUs (1 ou 2) ou para atualizar as flags de banco de dados, execute o comando gcloud alloydb instances update:

gcloud alloydb instances update INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --cpu-count=CPU_COUNT \
    --database-flags=FLAGS \
    --project=PROJECT_ID

Substitua:

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • REGION_ID: a região em que o cluster está localizado.
  • CPU_COUNT: o número de vCPUs da instância (1 para 1 vCPU, 4 GB de RAM ou 2 para 2 vCPUs, 8 GB de RAM).
  • FLAGS (opcional): uma lista separada por vírgulas de flags de banco de dados e valores no formato FLAG_NAME=VALUE. Se você estiver atualizando apenas a contagem de CPUs, omita a sinalização --database-flags. Para mais informações sobre as flags compatíveis, consulte Flags de banco de dados compatíveis.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • --enable-public-dns ou --no-enable-public-dns: ativa ou desativa o DNS público para a instância. Essa flag está disponível apenas no gcloud beta (gcloud beta alloydb instances update).
  • --allowed-psc-projects=[ALLOWED_PSC_PROJECTS,...]: atualiza a lista separada por vírgulas de IDs ou números de projetos do consumidor Google Cloud que podem criar endpoints do Private Service Connect para a instância.

REST

Para atualizar a contagem de CPUs ou as flags de banco de dados de uma instância primária do AlloyDB Express, envie uma solicitação PATCH para o endpoint projects.locations.clusters.instances.patch e especifique os campos que você está atualizando no parâmetro de consulta updateMask.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION_ID: a região em que o cluster está localizado.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
  • CPU_COUNT: o número de vCPUs da instância (1 ou 2).
  • FLAG_NAME e FLAG_VALUE (opcional): o nome e o valor da flag de banco de dados a serem definidos. Se você estiver atualizando apenas a contagem de CPUs, defina updateMask=machineConfig.cpuCount e omita databaseFlags do corpo da solicitação.

Método HTTP e URL:

PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID?updateMask=machineConfig.cpuCount,databaseFlags

Corpo JSON da solicitação:

{
  "machineConfig": {
    "cpuCount": CPU_COUNT
  },
  "databaseFlags": {
    "FLAG_NAME": "FLAG_VALUE"
  }
}

MCP

Para atualizar a contagem de CPUs ou as flags de banco de dados de uma instância principal do AlloyDB Express, insira um comando no cliente MCP ou chame a ferramenta MCP update_instance.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .

  • REGION_ID: a região em que o cluster está localizado.

  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

  • CPU_COUNT: o número de vCPUs da instância (1 ou 2).

  • FLAG_NAME e FLAG_VALUE: opcional: o nome e o valor da flag de banco de dados a serem definidos. Se você estiver atualizando apenas a contagem de CPUs, omita database_flags de arguments.

No cliente MCP, insira um comando semelhante ao seguinte:

Please update the AlloyDB instance INSTANCE_ID in cluster CLUSTER_ID to CPU_COUNT vCPUs.

Parâmetros da chamada de ferramenta:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_instance",
    "arguments": {
      "instance": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID",
      "cpu_count": CPU_COUNT,
      "database_flags": {
        "FLAG_NAME": "FLAG_VALUE"
      }
    }
  }
}

Ver detalhes do cluster e da instância do AlloyDB Express

É possível ver uma lista dos clusters do AlloyDB Express, conferir detalhes sobre um cluster ou uma instância específica do AlloyDB Express e verificar o uso de recursos computacionais e o uso do armazenamento do cluster.

Para mais informações, consulte Ver a lista de clusters, Ver detalhes do cluster e Ver detalhes da instância.

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

    Na coluna Nome do recurso, os clusters do AlloyDB Express exibem uma tag Express ao lado do nome do cluster.

  2. Para ver informações detalhadas sobre um cluster e a instância principal dele, clique no nome do cluster na coluna Nome do recurso.

  3. Na página Visão geral, confira os detalhes do cluster em Detalhes do cluster (incluindo a tag Express ao lado de ID do cluster e Armazenamento total usado do limite de 20 GB) e os detalhes da instância primária em Instâncias no cluster.

gcloud

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

  • Para ver uma lista de clusters no projeto, execute o comando gcloud alloydb clusters list:

    gcloud alloydb clusters list --project=PROJECT_ID

  • Para ver detalhes sobre um cluster específico, execute o comando gcloud alloydb clusters describe:

    gcloud alloydb clusters describe CLUSTER_ID \
    --region=REGION_ID \
    --project=PROJECT_ID

  • Para ver detalhes sobre uma instância específica, execute o comando gcloud alloydb instances describe:

    gcloud alloydb instances describe INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --project=PROJECT_ID

Substitua:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • REGION_ID: a região em que o cluster está localizado.
  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION_ID: a região em que o cluster está localizado.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

  • Para ver uma lista de clusters em uma região, envie uma solicitação GET para o endpoint projects.locations.clusters.list:

    GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters

  • Para ver detalhes sobre um cluster, envie uma solicitação GET ao endpoint projects.locations.clusters.get:

    GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID

  • Para ver detalhes sobre uma instância, envie uma solicitação GET ao endpoint projects.locations.clusters.instances.get:

    GET https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

MCP

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .

  • REGION_ID: a região em que o cluster está localizado.

  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

  • Para ver uma lista de clusters em uma região, insira um comando no cliente MCP ou chame a ferramenta MCP list_clusters.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please list the AlloyDB clusters in REGION_ID in project PROJECT_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_clusters",
    "arguments": {
      "parent": "projects/PROJECT_ID/locations/REGION_ID"
    }
  }
}

  • Para conferir detalhes sobre um cluster, insira um comando no cliente MCP ou chame a ferramenta MCP get_cluster.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please show the details of the AlloyDB cluster CLUSTER_ID in REGION_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_cluster",
    "arguments": {
      "name": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID"
    }
  }
}

  • Para conferir detalhes sobre uma instância, insira um comando no cliente MCP ou chame a ferramenta MCP get_instance.

    No cliente MCP, insira um comando semelhante ao seguinte:

    Please show the details of the AlloyDB instance INSTANCE_ID in cluster CLUSTER_ID.

    Parâmetros da chamada de ferramenta:

    {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_instance",
    "arguments": {
      "name": "projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID"
    }
  }
}

Ver o uso de recursos computacionais e uso do armazenamento

Para verificar o armazenamento e a computação usados pelo cluster e pela instância primária do AlloyDB Express, use o console do Google Cloud ou o Cloud Monitoring:

  • No console do Google Cloud , abra a página Visão geral do cluster:

    • Armazenamento usado: em Detalhes do cluster, confira Armazenamento total usado para ver quanto armazenamento o cluster está usando do limite de 20 GB.
    • Computação e conexões: confira os gráficos de Utilização da CPU e Conexões ativas na página Visão geral ou clique em Insights do sistema no menu de navegação para ver métricas detalhadas de CPU, memória e armazenamento.

  • No Metrics Explorer do Cloud Monitoring, consulte as seguintes métricas para os tipos de recursos monitorados alloydb.googleapis.com/Cluster e alloydb.googleapis.com/Instance:

    • Armazenamento utilizado: alloydb.googleapis.com/cluster/storage/usage
    • Uso da CPU: alloydb.googleapis.com/instance/cpu/average_utilization e alloydb.googleapis.com/instance/cpu/maximum_utilization
    • Conexões ativas: alloydb.googleapis.com/database/postgresql/backends

Excluir um cluster ou uma instância do AlloyDB Express

É possível excluir uma instância principal ou um cluster do AlloyDB Express quando não precisar mais deles.

Para mais informações, consulte Excluir uma instância e Excluir um cluster.

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Na coluna Nome do recurso, clique no nome do cluster do AlloyDB Express.

  3. Na página Visão geral, exclua a instância principal ou o cluster:

    • Para excluir a instância primária, acesse a seção Instâncias no cluster, clique em Ações da instância > Excluir, insira o ID da instância na caixa de diálogo e clique em Excluir.
    • Para excluir o cluster, primeiro exclua a instância principal no cluster e clique em Excluir cluster, insira o ID do cluster na caixa de diálogo Excluir cluster e clique em Excluir.

gcloud

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

  • Para excluir uma instância, execute o comando gcloud alloydb instances delete:

    gcloud alloydb instances delete INSTANCE_ID \
    --cluster=CLUSTER_ID \
    --region=REGION_ID \
    --project=PROJECT_ID

  • Para excluir um cluster, execute o comando gcloud alloydb clusters delete. Se o cluster ainda tiver a instância principal, inclua a flag --force para excluir a instância principal e o cluster juntos:

    gcloud alloydb clusters delete CLUSTER_ID \
    --region=REGION_ID \
    --force \
    --project=PROJECT_ID

Substitua:

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • REGION_ID: a região em que o cluster está localizado.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION_ID: a região em que o cluster está localizado.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

  • INSTANCE_ID: o ID da instância principal do AlloyDB Express.

  • Para excluir uma instância, envie uma solicitação DELETE ao endpoint projects.locations.clusters.instances.delete:

    DELETE https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID/instances/INSTANCE_ID

  • Para excluir um cluster (incluindo a instância principal ao especificar force=true), envie uma solicitação DELETE ao endpoint projects.locations.clusters.delete:

    DELETE https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID?force=true

Fazer upgrade de um cluster do AlloyDB Express para o AlloyDB

É possível fazer um upgrade no local do cluster do AlloyDB Express para um cluster do AlloyDB.

O upgrade preserva os dados, esquemas, extensões, credenciais de usuário, configuração de rede (incluindo o nome DNS público e os endpoints do Private Service Connect) e a contagem de vCPUs da instância principal.

A lista a seguir descreve os recursos e as configurações que mudam durante o processo de upgrade:

  • Contagem de CPUs, proporção de memória e capacidade de computação: sua instância mantém a contagem atual de vCPUs (1 ou 2 vCPUs) e faz upgrade da proporção de vCPU para memória de 1:4 do AlloyDB Express (4 GB ou 8 GB de RAM) para a proporção de vCPU para memória de 1:8 do AlloyDB (8 GB de RAM para 1 vCPU ou 16 GB de RAM para 2 vCPUs). Após o upgrade, será possível escalonar a computação para até 288 vCPUs.
    • Ao fazer upgrade de uma instância de 1 vCPU, você fica limitado às regiões que aceitam a série de máquinas C4A. Para regiões com disponibilidade, consulte Disponibilidade regional para C4A.
    • Se a instância do AlloyDB Express não estiver em uma região que aceite tipos de máquina C4A, primeiro atualize a instância principal para uma configuração de 2 vCPUs antes de fazer o upgrade. No console do Google Cloud , se você clicar em Fazer upgrade para uma instância de 1 vCPU em uma região sem suporte, uma mensagem vai solicitar que você redimensione a instância para 2 vCPUs primeiro.
  • Computação e faturamento provisionados: o upgrade desativa a computação com redução da escala a zero, e a instância é executada como uma instância do AlloyDB sempre ativa, faturada de acordo com as tarifas do AlloyDB.
  • Capacidade de armazenamento: o upgrade remove o limite de 20 GB. O armazenamento é escalonado até uma cota padrão de 16 TiB por cluster, e é possível solicitar um aumento da cota de armazenamento para escalonar verticalmente até 128 TiB.
  • Recursos corporativos: o upgrade desbloqueia a alta disponibilidade (HA) regional, que é coberta pelo contrato de nível de serviço (SLA) de 99,99% de tempo de atividade. Ele também desbloqueia instâncias de pool de leitura, replicação entre regiões, backup e recuperação contínuos e backups automatizados e sob demanda.

Para fazer upgrade do cluster do AlloyDB Express para um cluster do AlloyDB, siga estas etapas:

Console

  1. No Google Cloud console, acesse a página Clusters.

    Acessar Clusters

  2. Na coluna Nome do recurso, clique no nome do cluster do AlloyDB Express.

  3. Na página Visão geral, em Detalhes do cluster, localize ID do cluster e clique em Fazer upgrade.

    Se a instância principal for de 1 vCPU em uma região que não é compatível com a série de máquinas C4A, uma mensagem será exibida:

    Upgrading to AlloyDB requires a 2 vCPU instance in the REGION_ID region. Resize your instance to 2 vCPUs first.

    Para redimensionar a instância para 2 vCPUs, clique em Editar instância. Depois de redimensionar a instância, clique em Fazer upgrade novamente.

  4. No painel Fazer upgrade do AlloyDB Express, insira o ID do cluster para confirmar o upgrade e clique em Confirmar.

gcloud

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

Para fazer upgrade do cluster do AlloyDB Express para um cluster do AlloyDB, execute o comando gcloud beta alloydb clusters update com a flag --no-enable-express:

gcloud beta alloydb clusters update CLUSTER_ID \
    --region=REGION_ID \
    --no-enable-express \
    --project=PROJECT_ID

Substitua:

  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.
  • REGION_ID: a região em que o cluster está localizado.
  • PROJECT_ID: o ID do seu projeto do Google Cloud .

Se a instância principal for uma instância de 1 vCPU em uma região que não aceita a série de máquinas C4A, o comando vai falhar com o seguinte erro:

Upgrading to AlloyDB is not supported for 1-vCPU instances in location "REGION_ID". Please update the instance to use 2 vCPUs and try the upgrade again.

Para resolver esse erro, atualize sua instância principal para 2 vCPUs (--cpu-count=2) e execute o comando de upgrade novamente.

REST

Para fazer upgrade do cluster do AlloyDB Express para um cluster do AlloyDB, envie uma solicitação PATCH ao endpoint projects.locations.clusters.patch com updateMask=expressConfig.enabled e defina expressConfig.enabled como false.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do seu projeto do Google Cloud .
  • REGION_ID: a região em que o cluster está localizado.
  • CLUSTER_ID: o ID do seu cluster do AlloyDB Express.

Método HTTP e URL:

PATCH https://alloydb.googleapis.com/v1beta/projects/PROJECT_ID/locations/REGION_ID/clusters/CLUSTER_ID?updateMask=expressConfig.enabled

Corpo JSON da solicitação:

{
  "expressConfig": {
    "enabled": false
  }
}

Se a instância principal for de 1 vCPU em uma região que não aceita a série de máquinas C4A, a solicitação vai falhar com o seguinte erro:

Upgrading to AlloyDB is not supported for 1-vCPU instances in location "REGION_ID". Please update the instance to use 2 vCPUs and try the upgrade again.

Para resolver esse erro, atualize sua instância principal para 2 vCPUs ("machineConfig": {"cpuCount": 2}) e envie a solicitação de upgrade novamente.

A seguir