Clonar instâncias

MySQL | PostgreSQL | SQL Server

Nesta página, explicamos a clonagem e descrevemos como clonar uma instância.

Visão geral

A clonagem de uma instância do Cloud SQL cria uma nova instância, que é uma cópia da instância de origem. Essa nova instância é completamente independente da instância de origem.

Perguntas frequentes

Pergunta	Resposta
A clonagem afeta o desempenho?	Não. A clonagem não afeta o desempenho da instância de origem.
Os backups são copiados para a nova instância?	Não. A nova instância cria novos backups automatizados. Os backups manuais não são copiados da instância de origem.
A nova instância tem o mesmo endereço ou os mesmos endereços IP?	Não. A nova instância tem um novo endereço ou novos endereços IP.
A nova instância tem as mesmas definições de configuração?	Sim. A nova instância tem as mesmas configurações, como flags de banco de dados, opções de conectividade, tipo de máquina e configurações de armazenamento e memória.
As réplicas são copiadas para a nova instância?	Não. Você precisa criar novas réplicas para a nova instância.
É possível clonar uma réplica?	Não é possível clonar uma réplica.
É possível fazer uma clonagem de um momento anterior?	Sim. A recuperação pontual usa clonagem para restaurar uma instância de um momento anterior. Isso ajuda você a recuperar seu banco de dados de um evento destrutivo.
As configurações de manutenção da instância de origem são copiadas de maneira automática para a instância clone?	Não. É necessário definir as configurações de manutenção para a instância clone.
É possível clonar uma instância quando a zona da instância não estiver disponível?	Sim. Se você clonar uma instância por zona, poderá especificar uma zona primária diferente para ela. Se você clonar uma instância de alta disponibilidade (regional), poderá especificar zonas primária e secundária diferentes para a instância.
Posso clonar um banco de dados para outro projeto?	Não é possível clonar um banco de dados para outro projeto.
É possível clonar uma instância que já foi um clone?	Sim. É permitido clonar uma instância que foi clonada de outra instância.
Os usuários do banco de dados são copiados para a nova instância?	Sim, os usuários do banco de dados são copiados para a nova instância. As senhas desses usuários também são copiadas para que não precisem ser recriadas.

Clonar uma instância

Você pode clonar uma instânica do Cloud SQL usando o console do Google Cloud, gcloud CLI, Terraform ou a API.

Console

No console do Google Cloud, acesse a página Instâncias do Cloud SQL.

Acesse "Instâncias do Cloud SQL"
Encontre a linha da instância a ser clonada.
Na coluna Ações, clique no menu Mais ações .
Clique em Criar clone.
Na página Criar um clone, atualize o ID da instância, se necessário, e clique em Criar clone, saindo de Clonar o estado atual da instância selecionado.
Você retorna à página de listagem de instâncias e o clone é inicializado.

gcloud

Para clonar uma instância, use o comando gcloud sql instances clone:

gcloud sql instances clone SOURCE_INSTANCE_NAME DESTINATION_INSTANCE_NAME \
--project PROJECT_ID \
--preferred-zone ZONE_NAME \
--preferred-secondary-zone SECONDARY_ZONE_NAME

Faça as seguintes substituições:

SOURCE_INSTANCE_NAME: o nome da instância do Cloud SQL a ser clonada
DESTINATION_INSTANCE_NAME: o nome da instância clonada
PROJECT_ID: o ID ou número do projeto do Google Cloud que contém as instâncias de origem e destino.
ZONE_NAME: opcional. O nome da zona principal da instância de destino. Use essa opção se quiser que a instância de destino esteja em uma zona primária diferente da instância do Cloud SQL que você está clonando. Para uma instância regional, esta zona substitui a zona principal, mas a zona secundária permanece igual à instância.
SECONDARY_ZONE_NAME: opcional. O nome da zona secundária da instância de destino. Use-o para especificar uma zona secundária diferente para a instância regional do Cloud SQL que você quer clonar.

Se você estiver usando os parâmetros --preferred-zone e --preferred-secondary-zone, as seguintes condições serão aplicadas:

As zonas principal e secundária precisam ser válidas.
As duas zonas precisam pertencer à mesma região da instância de origem.
As zonas principal e secundária precisam ser diferentes.
Para instâncias zonais, não é possível usar o parâmetro --preferred-secondary-zone. Se você fizer isso, o processo de clonagem da instância vai falhar.
Se você não especificar valores para os parâmetros --preferred-zone ou --preferred-secondary-zone, a instância clonada terá as mesmas zonas principal e secundária da instância de origem.

Para executar o comando gcloud sql instances clone, você precisa ter a permissão cloudsql.instances.clone. Para mais informações sobre as permissões necessárias para executar os comandos da CLI gcloud, consulte Permissões do Cloud SQL.

Terraform

Para clonar a instância, use um recurso do Terraform

resource "google_sql_database_instance" "clone" {
  name             = "postgres-instance-clone-name"
  region           = "us-central1"
  database_version = "POSTGRES_12"
  clone {
    source_instance_name = google_sql_database_instance.source.id
  }
  # set `deletion_protection` to true, will ensure that one cannot accidentally delete this instance by
  # use of Terraform whereas `deletion_protection_enabled` flag protects this instance at the GCP level.
  deletion_protection = false
}

Aplique as alterações

Para aplicar a configuração do Terraform em um projeto do Google Cloud, conclua as etapas nas seções a seguir.

Preparar o Cloud Shell

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 do arquivo precisa ter a extensão .tf, por exemplo, main.tf. Neste tutorial, o arquivo é chamado de main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Se você estiver seguindo um tutorial, poderá copiar o exemplo de código em cada seção ou etapa.

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 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
```
Opcionalmente, 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 e verifique se os recursos que o Terraform vai criar ou atualizar 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 IU para verificar se foram criados ou atualizados pelo Terraform.

Excluir as alterações

Para excluir as mudanças, faça o seguinte:

Para desativar a proteção contra exclusão, no arquivo de configuração do Terraform, defina o argumento deletion_protection como false.
```
deletion_protection =  "false"
```
Para aplicar a configuração atualizada do Terraform, execute o comando a seguir e digite yes no prompt:
```
terraform apply
```

Remova os recursos aplicados anteriormente com a configuração do Terraform executando o seguinte comando e inserindo yes no prompt:
```
terraform destroy
```

REST v1

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

PROJECT_ID: o ID ou número do projeto do Google Cloud que contém as instâncias de origem e destino.
SOURCE_INSTANCE_NAME: o nome da instância do Cloud SQL a ser clonada
DESTINATION_INSTANCE_NAME: o nome da instância clonada
ZONE_NAME: opcional. O nome da zona principal da instância de destino. Use essa opção se quiser que a instância de destino esteja em uma zona primária diferente da instância do Cloud SQL que você está clonando. Para uma instância regional, esta zona substitui a zona principal, mas a zona secundária permanece igual à instância.
SECONDARY_ZONE_NAME: opcional. O nome da zona secundária da instância de destino. Use-o para especificar uma zona secundária diferente para a instância regional do Cloud SQL que você quer clonar.

Método HTTP e URL:

POST https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME",
    "preferredZone": "ZONE_NAME",
    "preferredSecondaryZone": "SECONDARY_ZONE_NAME"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login, ou usando o Cloud Shell, que faz login automaticamente na CLI gcloud. . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone"

PowerShell (Windows)

Observação: o comando a seguir pressupõe que você fez login na CLI gcloud com sua conta de usuário executando gcloud init ou gcloud auth login . É possível verificar a conta ativa atual executando gcloud auth list.

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/instances/DESTINATION_INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CLONE",
  "name": "OPERATION_ID",
  "targetId": "DESTINATION_INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Se você estiver usando os parâmetros preferredZone e preferredSecondaryZone, as seguintes condições serão aplicadas:

As zonas principal e secundária precisam ser válidas.
As duas zonas precisam pertencer à mesma região da instância de origem.
As zonas principal e secundária precisam ser diferentes.
Para instâncias zonais, não é possível usar o parâmetro preferredSecondaryZone. Se você fizer isso, o processo de clonagem da instância vai falhar.
Se você não especificar valores para os parâmetros preferredZone ou preferredSecondaryZone, a instância clonada terá as mesmas zonas principais e secundárias que a instância de origem.

Para usar o método da API instances.clone, você precisa ter a permissão cloudsql.instances.clone. Para mais informações sobre as permissões necessárias para usar os métodos da API, consulte Permissões do Cloud SQL.

REST v1beta4

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

PROJECT_ID: o ID ou número do projeto do Google Cloud que contém as instâncias de origem e destino.
SOURCE_INSTANCE_NAME: o nome da instância do Cloud SQL a ser clonada
DESTINATION_INSTANCE_NAME: o nome da instância clonada
ZONE_NAME: opcional. O nome da zona principal da instância de destino. Use essa opção se quiser que a instância de destino esteja em uma zona primária diferente da instância do Cloud SQL que você está clonando. Para uma instância regional, esta zona substitui a zona principal, mas a zona secundária permanece igual à instância.
SECONDARY_ZONE_NAME: opcional. O nome da zona secundária da instância de destino. Use-o para especificar uma zona secundária diferente para a instância regional do Cloud SQL que você quer clonar.

Método HTTP e URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "destinationInstanceName": "DESTINATION_INSTANCE_NAME",
    "preferredZone": "ZONE_NAME",
    "preferredSecondaryZone": "SECONDARY_ZONE_NAME"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/SOURCE_INSTANCE_NAME/clone" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/DESTINATION_INSTANCE_NAME",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CLONE",
  "name": "OPERATION_ID",
  "targetId": "DESTINATION_INSTANCE_NAME",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/operations/OPERATION_ID",
  "targetProject": "PROJECT_ID"
}

Se você estiver usando os parâmetros preferredZone e preferredSecondaryZone, as seguintes condições serão aplicadas:

As zonas principal e secundária precisam ser válidas.
As duas zonas precisam pertencer à mesma região da instância de origem.
As zonas principal e secundária precisam ser diferentes.
Para instâncias zonais, não é possível usar o parâmetro preferredSecondaryZone. Se você fizer isso, o processo de clonagem da instância vai falhar.
Se você não especificar valores para os parâmetros preferredZone ou preferredSecondaryZone, a instância clonada terá as mesmas zonas principais e secundárias que a instância de origem.

Clonar uma instância que usa um endereço IP interno

Se a instância do Cloud SQL usar um endereço IP interno, será possível especificar um intervalo de IP alocado para o novo endereço IP do clone. Por exemplo, google-managed-services-default.

gcloud

Clone a instância especificando opcionalmente o intervalo de IP alocado que você quer usar:

gcloud sql instances clone SOURCE_INSTANCE_NAME TARGET_INSTANCE_NAME \
--allocated-ip-range-name ALLOCATED_IP_RANGE_NAME

A conta de serviço ou o usuário que está executando o comando gcloud sql instances clone precisa ter a permissão cloudsql.instances.clone. Para mais informações sobre as permissões necessárias para executar os comandos da CLI gcloud, consulte Permissões do Cloud SQL.

REST v1

Clone a instância especificando opcionalmente o intervalo de IP alocado que você quer usar:

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

project-id: o ID do projeto;
source-instance-id: o ID da instância de origem
target-instance-id: o ID da instância de destino
allocated-ip-range-name: o nome de um intervalo de IP alocado

Método HTTP e URL:

POST https://sqladmin.googleapis.com/v1/projects/project-id/instances/source-instance-id/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "destinationInstanceName": "target-instance-id",
    "allocatedIpRange": "allocated-ip-range-name"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/v1/projects/project-id/instances/source-instance-id/clone"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/v1/projects/project-id/instances/source-instance-id/clone" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/v1/projects/project-id/instances/target-instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CLONE",
  "name": "operation-id",
  "targetId": "target-instance-id",
  "selfLink": "https://sqladmin.googleapis.com/v1/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

O usuário ou a conta de serviço que está usando o método instances.clone da API precisa ter a permissão cloudsql.instances.clone. Para mais informações sobre as permissões necessárias para usar os métodos da API, consulte Permissões do Cloud SQL.

REST v1beta4

Clone a instância especificando opcionalmente o intervalo de IP alocado que você quer usar:

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

project-id: o ID do projeto;
source-instance-id: o ID da instância de origem
target-instance-id: o ID da instância de destino
allocated-ip-range-name: o nome de um intervalo de IP alocado

Método HTTP e URL:

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/source-instance-id/clone

Corpo JSON da solicitação:

{
  "cloneContext":
  {
    "destinationInstanceName": "target-instance-id",
    "allocatedIpRange": "allocated-ip-range-name"
  }
}

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/source-instance-id/clone"

PowerShell (Windows)

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando a seguir:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/source-instance-id/clone" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

Resposta

{
  "kind": "sql#operation",
  "targetLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/instances/target-instance-id",
  "status": "PENDING",
  "user": "user@example.com",
  "insertTime": "2020-01-21T22:43:37.981Z",
  "operationType": "CLONE",
  "name": "operation-id",
  "targetId": "target-instance-id",
  "selfLink": "https://sqladmin.googleapis.com/sql/v1beta4/projects/project-id/operations/operation-id",
  "targetProject": "project-id"
}

Se você não especificar um intervalo de IP alocado, este comportamento será aplicado:

Se a instância de origem foi criada com um intervalo específico, a instância clonada será criada no mesmo intervalo.
Se a instância de origem não foi criada com um intervalo específico, a instância clonada será criada em um intervalo aleatório.

Resolver problemas

Problema Solução de problemas

Problema	Solução de problemas
Ocorreu uma falha na clonagem com um erro `constraints/sql.restrictAuthorizedNetworks`.	A operação de clonagem é bloqueada pela configuração `Authorized Networks`. `Authorized Networks` são configurados para endereços IP públicos na seção "Conectividade" do console do Google Cloud, e a clonagem não é permitida devido a considerações de segurança. Remova todas as entradas `Authorized Networks` da instância do Cloud SQL, se possível. Caso contrário, crie uma réplica sem nenhuma entrada `Authorized Networks`.
Mensagem de erro: `Failed to create subnetwork. Couldn't find free blocks in allocated IP ranges. Please allocate new ranges for this service provider. Help Token: [help-token-id].`	Você está tentando usar o console do Google Cloud para clonar uma instância com um endereço IP particular, mas não especificou o intervalo de IP alocado que pretende usar e a instância de origem não foi criada com o intervalo especificado. Como resultado, a instância clonada é criada em um intervalo aleatório. Use `gcloud` para clonar a instância e fornecer um valor para o parâmetro `--allocated-ip-range-name`. Para mais informações, consulte Como clonar uma instância com um IP particular.

Ocorreu uma falha na clonagem com um erro constraints/sql.restrictAuthorizedNetworks.

A operação de clonagem é bloqueada pela configuração Authorized Networks. Authorized Networks são configurados para endereços IP públicos na seção "Conectividade" do console do Google Cloud, e a clonagem não é permitida devido a considerações de segurança.

Remova todas as entradas Authorized Networks da instância do Cloud SQL, se possível. Caso contrário, crie uma réplica sem nenhuma entrada Authorized Networks.

Mensagem de erro:

Failed to create subnetwork. Couldn't find free
      blocks in allocated IP ranges. Please allocate new ranges for this service
      provider. Help Token: [help-token-id].

Você está tentando usar o console do Google Cloud para clonar uma instância com um endereço IP particular, mas não especificou o intervalo de IP alocado que pretende usar e a instância de origem não foi criada com o intervalo especificado. Como resultado, a instância clonada é criada em um intervalo aleatório.

Use gcloud para clonar a instância e fornecer um valor para o parâmetro
--allocated-ip-range-name. Para mais informações, consulte Como clonar uma instância com um IP particular.