Criar e gerenciar instâncias

Nesta página, descrevemos como criar, listar, editar e excluir instâncias do Cloud Spanner.

Como criar uma instância

É possível criar uma instância com a CLI do Google Cloud ou com o Console do Google Cloud.

Console

  1. Acesse a página Criar uma instância no Console do Google Cloud.

    Criar uma instância

  2. Digite os seguintes valores:

    • Um nome de instância a ser exibido no Console do Google Cloud. O nome da instância precisa ser exclusivo no projeto do Google Cloud.
    • Um código de instância para identificá-la permanentemente. O código da instância também precisa ser exclusivo no projeto do Google Cloud. Não será possível alterá-lo depois.
    • Uma configuração, que define a localização geográfica da instância e afeta a maneira como os dados são replicados. Saiba mais sobre configurações de instâncias.
    • A quantidade de capacidade de computação da instância. A capacidade de computação determina a quantidade de recursos de serviço e de armazenamento disponíveis para os bancos de dados na instância. Para especificar a capacidade de computação, escolha as unidades de medida (unidades de processamento ou nós) e insira uma quantidade. Ao usar unidades de processamento, insira quantidades até 1000 em múltiplos de 100 (100, 200, 300 e assim por diante) e insira quantidades maiores em múltiplos de 1000 (1000, 2000, 3000 e assim por diante). Cada nó é igual a 1.000 unidades de processamento. Saiba mais sobre o processamento de unidades e nós.

  3. Clique em Criar para criar a instância.

gcloud

Use o comando gcloud spanner instances create: Ao usar esse comando, especifique a capacidade de computação como um número ou nós ou unidades de processamento.

gcloud spanner instances create [INSTANCE-ID] --config=[INSTANCE-CONFIG] \
    --description="[INSTANCE-NAME]" --nodes=[NODE-COUNT]

ou

gcloud spanner instances create [INSTANCE-ID] --config=[INSTANCE-CONFIG] \
    --description="[INSTANCE-NAME]" --processing-units=[PROCESSING-UNIT-COUNT]

Forneça os valores a seguir:

  • [INSTANCE-ID]: um identificador permanente exclusivo em seu projeto do Google Cloud. Não será possível alterá-lo depois.
  • [INSTANCE-CONFIG]: a configuração da instância, que define o local geográfico dela e afeta a maneira como os dados são replicados. Saiba mais sobre configurações de instâncias.
  • [INSTANCE-NAME]: o nome a ser exibido para a instância no Console do Google Cloud. O nome da instância precisa ser exclusivo no projeto do Google Cloud.
  • [NODE-COUNT]: a capacidade de computação da instância, expressa como um número de nós. Cada nó é igual a 1.000 unidades de processamento.
  • [PROCESSING-UNIT-COUNT]: a capacidade de computação da instância, expressa como um número de unidades de processamento. Insira quantidades até 1.000 em múltiplos de 100 (100, 200, 300 etc.) e digite quantidades maiores em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante).

Exemplo:

gcloud spanner instances create test-instance --config=regional-us-central1 \
    --description="Test Instance" --nodes=1

Será exibida uma mensagem parecida com o exemplo a seguir:

Creating instance...done.

C++

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

void CreateInstance(google::cloud::spanner_admin::InstanceAdminClient client,
                    std::string const& project_id,
                    std::string const& instance_id,
                    std::string const& display_name,
                    std::string const& config_id) {
  namespace spanner = ::google::cloud::spanner;
  spanner::Instance in(project_id, instance_id);

  auto project = google::cloud::Project(project_id);
  std::string config_name =
      project.FullName() + "/instanceConfigs/" + config_id;
  auto instance =
      client
          .CreateInstance(spanner::CreateInstanceRequestBuilder(in, config_name)
                              .SetDisplayName(display_name)
                              .SetNodeCount(1)
                              .SetLabels({{"cloud_spanner_samples", "true"}})
                              .Build())
          .get();
  if (!instance) throw std::runtime_error(instance.status().message());
  std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
}

C#

Para saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 


using Google.Api.Gax.ResourceNames;
using Google.Cloud.Spanner.Admin.Instance.V1;
using Google.Cloud.Spanner.Common.V1;
using Google.LongRunning;
using System;

public class CreateInstanceSample
{
    public Instance CreateInstance(string projectId, string instanceId)
    {
        // Create the InstanceAdminClient instance.
        InstanceAdminClient instanceAdminClient = InstanceAdminClient.Create();

        // Initialize request parameters.
        Instance instance = new Instance
        {
            InstanceName = InstanceName.FromProjectInstance(projectId, instanceId),
            ConfigAsInstanceConfigName = InstanceConfigName.FromProjectInstanceConfig(projectId, "regional-us-central1"),
            DisplayName = "This is a display name.",
            NodeCount = 1,
            Labels =
            {
                { "cloud_spanner_samples", "true" },
            }
        };
        ProjectName projectName = ProjectName.FromProject(projectId);

        // Make the CreateInstance request.
        Operation<Instance, CreateInstanceMetadata> response = instanceAdminClient.CreateInstance(projectName, instanceId, instance);

        Console.WriteLine("Waiting for the operation to finish.");

        // Poll until the returned long-running operation is complete.
        Operation<Instance, CreateInstanceMetadata> completedResponse = response.PollUntilCompleted();

        if (completedResponse.IsFaulted)
        {
            Console.WriteLine($"Error while creating instance: {completedResponse.Exception}");
            throw completedResponse.Exception;
        }

        Console.WriteLine($"Instance created successfully.");

        return completedResponse.Result;
    }
}

Go

Para saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

import (
	"context"
	"fmt"
	"io"

	instance "cloud.google.com/go/spanner/admin/instance/apiv1"
	instancepb "google.golang.org/genproto/googleapis/spanner/admin/instance/v1"
)

func createInstance(w io.Writer, projectID, instanceID string) error {
	// projectID := "my-project-id"
	// instanceID := "my-instance"
	ctx := context.Background()
	instanceAdmin, err := instance.NewInstanceAdminClient(ctx)
	if err != nil {
		return err
	}
	defer instanceAdmin.Close()

	op, err := instanceAdmin.CreateInstance(ctx, &instancepb.CreateInstanceRequest{
		Parent:     fmt.Sprintf("projects/%s", projectID),
		InstanceId: instanceID,
		Instance: &instancepb.Instance{
			Config:      fmt.Sprintf("projects/%s/instanceConfigs/%s", projectID, "regional-us-central1"),
			DisplayName: instanceID,
			NodeCount:   1,
			Labels:      map[string]string{"cloud_spanner_samples": "true"},
		},
	})
	if err != nil {
		return fmt.Errorf("could not create instance %s: %v", fmt.Sprintf("projects/%s/instances/%s", projectID, instanceID), err)
	}
	// Wait for the instance creation to finish.
	i, err := op.Wait(ctx)
	if err != nil {
		return fmt.Errorf("waiting for instance creation to finish failed: %v", err)
	}
	// The instance may not be ready to serve yet.
	if i.State != instancepb.Instance_READY {
		fmt.Fprintf(w, "instance state is not READY yet. Got state %v\n", i.State)
	}
	fmt.Fprintf(w, "Created instance [%s]\n", instanceID)
	return nil
}

Java

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.spanner.Instance;
import com.google.cloud.spanner.InstanceAdminClient;
import com.google.cloud.spanner.InstanceConfigId;
import com.google.cloud.spanner.InstanceId;
import com.google.cloud.spanner.InstanceInfo;
import com.google.cloud.spanner.Spanner;
import com.google.cloud.spanner.SpannerOptions;
import com.google.spanner.admin.instance.v1.CreateInstanceMetadata;
import java.util.concurrent.ExecutionException;

class CreateInstanceExample {

  static void createInstance() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "my-project";
    String instanceId = "my-instance";
    createInstance(projectId, instanceId);
  }

  static void createInstance(String projectId, String instanceId) {
    Spanner spanner = SpannerOptions.newBuilder().setProjectId(projectId).build().getService();
    InstanceAdminClient instanceAdminClient = spanner.getInstanceAdminClient();

    // Set Instance configuration.
    String configId = "regional-us-central1";
    int nodeCount = 2;
    String displayName = "Descriptive name";

    // Create an InstanceInfo object that will be used to create the instance.
    InstanceInfo instanceInfo =
        InstanceInfo.newBuilder(InstanceId.of(projectId, instanceId))
            .setInstanceConfigId(InstanceConfigId.of(projectId, configId))
            .setNodeCount(nodeCount)
            .setDisplayName(displayName)
            .build();
    OperationFuture<Instance, CreateInstanceMetadata> operation =
        instanceAdminClient.createInstance(instanceInfo);
    try {
      // Wait for the createInstance operation to finish.
      Instance instance = operation.get();
      System.out.printf("Instance %s was successfully created%n", instance.getId());
    } catch (ExecutionException e) {
      System.out.printf(
          "Error: Creating instance %s failed with error message %s%n",
          instanceInfo.getId(), e.getMessage());
    } catch (InterruptedException e) {
      System.out.println("Error: Waiting for createInstance operation to finish was interrupted");
    } finally {
      spanner.close();
    }
  }
}

Node.js

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

const instance = spanner.instance(instanceId);

// Creates a new instance
try {
  console.log(`Creating instance ${instance.formattedName_}.`);
  const [, operation] = await instance.create({
    config: 'regional-us-west1',
    nodes: 1,
    displayName: 'This is a display name.',
    labels: {
      ['cloud_spanner_samples']: 'true',
      created: Math.round(Date.now() / 1000).toString(), // current time
    },
  });

  console.log(`Waiting for operation on ${instance.id} to complete...`);
  await operation.promise();

  console.log(`Created instance ${instanceId}.`);
} catch (err) {
  console.error('ERROR:', err);
}

PHP

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

use Google\Cloud\Spanner\SpannerClient;

/**
 * Creates an instance.
 * Example:
 * ```
 * create_instance($instanceId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 */
function create_instance($instanceId)
{
    $spanner = new SpannerClient();
    $instanceConfig = $spanner->instanceConfiguration(
        'regional-us-central1'
    );
    $operation = $spanner->createInstance(
        $instanceConfig,
        $instanceId,
        [
            'displayName' => 'This is a display name.',
            'nodeCount' => 1,
            'labels' => [
                'cloud_spanner_samples' => true,
            ]
        ]
    );

    print('Waiting for operation to complete...' . PHP_EOL);
    $operation->pollUntilComplete();

    printf('Created instance %s' . PHP_EOL, $instanceId);
}

Python

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

def create_instance(instance_id):
    """Creates an instance."""
    spanner_client = spanner.Client()

    config_name = "{}/instanceConfigs/regional-us-central1".format(
        spanner_client.project_name
    )

    instance = spanner_client.instance(
        instance_id,
        configuration_name=config_name,
        display_name="This is a display name.",
        node_count=1,
        labels={
            "cloud_spanner_samples": "true",
            "sample_name": "snippets-create_instance-explicit",
            "created": str(int(time.time())),
        },
    )

    operation = instance.create()

    print("Waiting for operation to complete...")
    operation.result(OPERATION_TIMEOUT_SECONDS)

    print("Created instance {}".format(instance_id))

Ruby

Para aprender a instalar e usar a biblioteca de cliente para o Cloud Spanner, consulte Bibliotecas de cliente do Cloud Spanner. 

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"

require "google/cloud/spanner"
require "google/cloud/spanner/admin/instance"

instance_admin_client = Google::Cloud::Spanner::Admin::Instance.instance_admin

project_path = instance_admin_client.project_path project: project_id
instance_path = instance_admin_client.instance_path project: project_id, instance: instance_id
instance_config_path = instance_admin_client.instance_config_path project: project_id, instance_config: "regional-us-central1"

job = instance_admin_client.create_instance parent: project_path,
                                            instance_id: instance_id,
                                            instance: { name: instance_path,
                                                        config: instance_config_path,
                                                        display_name: instance_id,
                                                        node_count: 2,
                                                        labels: { cloud_spanner_samples: "true" } }

puts "Waiting for create instance operation to complete"

job.wait_until_done!

if job.error?
  puts job.error
else
  puts "Created instance #{instance_id}"
end

Como listar instâncias

Console

Acesse a página Instâncias do Spanner no Console do Google Cloud.

Acessar a página "Instâncias"

O Console do Google Cloud mostra uma lista de instâncias do Cloud Spanner com o ID, o nome de exibição, a configuração e a capacidade de computação de cada instância, expressas em unidades de processamento e nós.

gcloud

Use o comando gcloud spanner instances list:

gcloud spanner instances list

A CLI gcloud exibe uma lista de instâncias do Cloud Spanner, além do ID, nome de exibição, configuração e capacidade de computação de cada instância.

Como editar uma instância

As seções a seguir explicam como alterar o nome de exibição e a capacidade de computação de uma instância. Não é possível alterar o código ou a configuração da instância.

Como alterar o nome de exibição

Console

  1. Acesse a página Instâncias do Spanner no Console do Google Cloud.

    Acessar a página "Instâncias"

  2. Para renomear, clique no nome da instância.

  3. Clique em Editar instância.

  4. Insira um novo nome de instância. Esse nome precisa ser exclusivo no projeto do Google Cloud.

  5. Clique em Save.

gcloud

Use o comando gcloud spanner instances update:

gcloud spanner instances update [INSTANCE-ID] --description=[INSTANCE-NAME]

Forneça os valores a seguir:

  • [INSTANCE-ID]: o identificador permanente da instância.
  • [INSTANCE-NAME]: o nome a ser exibido para a instância no Console do Google Cloud. O nome da instância precisa ser exclusivo no projeto do Google Cloud.

Como alterar a capacidade de computação

Provisione capacidade de computação suficiente para manter a utilização da CPU e a utilização de armazenamento abaixo dos valores máximos recomendados. Para mais informações, consulte as cotas e limites do Cloud Spanner.

Há alguns casos em que não é possível reduzir a capacidade de computação de uma instância atual:

  • A remoção da capacidade de computação exige que a instância armazene mais de 4 TB de dados a cada 1.000 unidades de processamento (1 nó).
  • Com base nos padrões históricos de uso, o Cloud Spanner criou um grande número de divisões nos dados da instância, e, em alguns raros casos, o Cloud Spanner não consegue gerenciar as divisões depois da remoção dos nós.

No último caso, é possível tentar reduzir a capacidade de computação progressivamente em valores menores até encontrar a capacidade mínima que o Cloud Spanner precisa para gerenciar todas as divisões da instância. Se a instância não exigir mais tantas divisões devido a uma alteração nos padrões de uso, o Cloud Spanner poderá mesclar algumas divisões e permitir que você tente reduzir ainda mais a capacidade de computação da instância depois de uma ou duas semanas. de dados.

Ao remover nós, monitore a utilização da CPU e as latências de solicitação em Monitoramento do Cloud para garantir que a utilização da CPU permaneça abaixo de 65% para instâncias regionais e 45% para cada região em instâncias multirregionais. Pode haver um aumento temporário nas latências de solicitação ao remover a capacidade de computação.

Se você quiser aumentar a capacidade de uma instância, seu projeto do Google Cloud precisa ter cota suficiente para adicionar a capacidade de computação.

Console

  1. Acesse a página Instâncias do Spanner no Console do Google Cloud.

    Acessar a página "Instâncias"

  2. Clique no nome da instância a ser modificada.

  3. Clique em Editar instância.

  4. Para alterar a capacidade de computação, escolha as unidades de medida (unidades de processamento ou nós) e insira uma quantidade. Ao usar unidades de processamento, insira quantidades até 1.000 em múltiplos de 100 (100, 200, 300 e assim por diante) e insira quantidades maiores em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante). . Cada nó é igual a 1.000 unidades de processamento.

  5. Clique em Save.

    Se for exibida uma caixa de diálogo informando que sua cota é insuficiente para adicionar nós neste local, siga as instruções para solicitar uma cota maior.

gcloud

Use o comando gcloud spanner instances update. Ao usar esse comando, especifique a capacidade de computação como um número ou nós ou unidades de processamento.

gcloud spanner instances update [INSTANCE-ID] --nodes=[NODE-COUNT]

ou

gcloud spanner instances update [INSTANCE-ID] --processing-units=[PROCESSING-UNIT-COUNT]

Forneça os valores a seguir:

  • [INSTANCE-ID]: o identificador permanente da instância.
  • [NODE-COUNT]: a capacidade de computação da instância, expressa como um número de nós. Cada nó é igual a 1.000 unidades de processamento.
  • [PROCESSING-UNIT-COUNT]: a capacidade de computação da instância, expressa como um número de unidades de processamento. Insira quantidades até 1.000 em múltiplos de 100 (100, 200, 300 etc.) e digite quantidades maiores em múltiplos de 1.000 (1.000, 2.000, 3.000 e assim por diante).

Como rotular uma instância

Os rótulos ajudam a organizar os recursos.

Console

  1. Acesse a página Instâncias do Spanner no Console do Google Cloud.

    Acessar a página "Instâncias"

  2. Marque a caixa de seleção da instância. O Painel de informações aparece no lado direito da página.

  3. Clique na guia Permissões no painel de informações. É possível adicionar, excluir ou atualizar rótulos para a instância do Cloud Spanner.

Excluir uma instância

Console

  1. Acesse a página Instâncias do Spanner no Console do Google Cloud.

    Acessar a página "Instâncias"

  2. Clique no nome da instância a ser excluída.

  3. Clique em Excluir instância.

  4. Siga as instruções para confirmar a exclusão da instância.

  5. Clique em Excluir.

gcloud

Use o comando gcloud spanner instances delete, substituindo [INSTANCE-ID] pelo código da instância:

gcloud spanner instances delete [INSTANCE-ID]

Como interromper ou reiniciar uma instância

O Cloud Spanner é um serviço de banco de dados totalmente gerenciado que supervisiona as próprias tarefas e recursos subjacentes, incluindo monitoramento e reinicialização de processos quando necessário, sem inatividade. Como não é necessário interromper ou reiniciar manualmente uma determinada instância, o Cloud Spanner não oferece uma maneira de fazer isso.

A seguir