Criar e gerenciar instâncias

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

Criar uma instância

É possível criar uma instância com a ferramenta de linha de comando gcloud ou com o Console do Google Cloud.

Console

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

    Criar uma instância

  2. Insira os seguintes valores:

    • Um nome da instância a ser exibido no Console do 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 dos nós da instância e afeta como os dados são replicados. Saiba mais sobre configurações de instâncias.
    • O número de nós para a instância. Esse número determina a quantidade de recursos de exibição e armazenamento disponíveis para bancos de dados na instância.
  3. Clique em Criar para criar a instância.

Na captura de tela a seguir, veja a página de criação da instância:

Captura de tela da página de criação da instância

gcloud

Use o comando gcloud spanner instances create:

gcloud spanner instances create [INSTANCE-ID] --config=[INSTANCE-CONFIG] \
    --description="[INSTANCE-NAME]" --nodes=[NODE-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 a localização geográfica dos nós da instância e afeta a replicação dos dados. Saiba mais sobre configurações de instâncias.
  • [INSTANCE-NAME]: o nome a ser exibido para a instância no Console do Cloud. O nome da instância precisa ser exclusivo no projeto do Google Cloud.
  • [NODE-COUNT]: o número de nós da instância. Esse número determina a quantidade de recursos de exibição e armazenamento disponíveis para bancos de dados na instância.

Por 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 saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as bibliotecas de cliente do Cloud Spanner.

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

  std::string instance_config =
      "projects/" + project_id + "/instanceConfigs/" + config;
  auto instance =
      client
          .CreateInstance(
              spanner::CreateInstanceRequestBuilder(in, instance_config)
                  .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";
}

Go

Para saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as 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(ctx context.Context, w io.Writer, projectID, instanceID string) error {
	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 saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as 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 saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as 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-central1',
    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 saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as 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 saber como instalar e usar a biblioteca de cliente do Cloud Spanner, consulte as 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,
    )

    operation = instance.create()

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

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

Ruby

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

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

require "google/cloud/spanner"

spanner  = Google::Cloud::Spanner.new project: project_id
instance = spanner.instance instance_id

job = spanner.create_instance instance_id,
                              name:   instance_id,
                              config: "regional-us-central1",
                              nodes:  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 Cloud.

Acessar a página "Instâncias"

No Console do Cloud, você encontra uma lista de instâncias do Cloud Spanner, incluindo código, nome de exibição, configuração e número de nós correspondentes.

gcloud

Use o comando gcloud spanner instances list:

gcloud spanner instances list

A ferramenta gcloud imprime uma lista de instâncias do Cloud Spanner, incluindo código, nome de exibição, configuração e número de nós correspondentes.

Como editar uma instância

Nas seções a seguir, explicamos como alterar o nome de exibição e o número de nós 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 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 Salvar.

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 Cloud. O nome da instância precisa ser exclusivo no projeto do Google Cloud.

Como alterar o número de nós

É preciso provisionar nós suficientes para manter o uso da CPU e a utilização de armazenamento abaixo do máximo recomendado. Para mais informações sobre os recursos fornecidos por um nó, consulte cotas e limites do Cloud Spanner.

Em alguns casos, não é possível remover nós de uma instância existente:

  • A remoção dos nós exigiria que a instância armazenasse mais de 2 TB de dados por 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 o Cloud Spanner não consegue gerenciar as divisões depois da remoção dos nós.

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. Talvez haja um aumento temporário nas latências de solicitação durante a remoção de nós.

Para aumentar o número de nós em uma instância, seu projeto do Google Cloud precisa ter cota suficiente para adicionar os nós.

Console

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

    Acessar a página "Instâncias"

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

  3. Clique em Editar instância.

  4. Digite o número de nós desejado.

  5. Clique em Salvar.

    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:

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

Forneça os valores a seguir:

  • [INSTANCE-ID]: o identificador permanente da instância.
  • [NODE-COUNT]: o número de nós da instância.

Como excluir uma instância

Console

  1. Acesse a página Instâncias do Spanner no Console do 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]

A seguir