Crear y administrar instancias

En esta página, se describe cómo crear, enumerar, editar y borrar instancias de Cloud Spanner.

Crea una instancia

Puedes crear una instancia con la CLI de Google Cloud o con Google Cloud Console.

Console

  1. Ve a la página Crear una instancia en Cloud Console.

    Crea una instancia

  2. Ingresa los siguientes valores:

    • Un nombre de instancia para mostrar en Cloud Console El nombre de la instancia debe ser único en tu proyecto de Google Cloud.
    • Un ID de instancia (Instance ID) para identificar de forma permanente tu instancia. El ID de la instancia también debe ser único en tu proyecto de Google Cloud. No puedes cambiar el ID de la instancia más tarde.
    • Una configuración, que define la ubicación geográfica de la instancia y afecta la forma en que se replican los datos. Obtén más información sobre la configuración de instancias.
    • La cantidad de capacidad de procesamiento de la instancia. La capacidad de procesamiento determina la cantidad de recursos de entrega y almacenamiento que están disponibles para las bases de datos de la instancia. Para especificar la capacidad de procesamiento, elige las unidades de medida (unidades de procesamiento o nodos) y, luego, ingresa una cantidad. Cuando uses unidades de procesamiento, ingresa cantidades hasta 1,000 en múltiplos de 100 (100, 200, 300, etc.) y, luego, ingresa cantidades mayores en múltiplos de 1,000 (1,000, 2,000, 3,000 y así sucesivamente). Cada nodo equivale a 1,000 unidades de procesamiento. Obtén más información sobre las unidades de procesamiento y los nodos.

  3. Haga clic en Crear para crear la instancia.

gcloud

Usa el comando gcloud spanner instances create. Cuando uses este comando, especifica la capacidad de procesamiento como un número de nodos o unidades de procesamiento.

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

o

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

Ingresa los siguientes valores:

  • [INSTANCE-ID]: Un identificador permanente que es único dentro de tu proyecto de Google Cloud. No puedes cambiar el ID de la instancia más tarde.
  • [INSTANCE-CONFIG]: la configuración de la instancia, que define la ubicación geográfica de la instancia y afecta la forma en que se replican los datos. Obtén más información sobre la configuración de instancias.
  • [INSTANCE-NAME]: El nombre que se mostrará para la instancia en Cloud Console. El nombre de la instancia debe ser único en tu proyecto de Google Cloud.
  • [NODE-COUNT]: La capacidad de procesamiento de la instancia, expresada como una cantidad de nodos. Cada nodo equivale a 1,000 unidades de procesamiento.
  • [PROCESSING-UNIT-COUNT]: La capacidad de procesamiento de la instancia, expresada como una cantidad de unidades de procesamiento. Ingresa cantidades hasta 1,000 en múltiplos de 100 (100, 200, 300 y así sucesivamente) y, luego, ingresa cantidades mayores en múltiplos de 1,000 (1,000, 2,000, 3,000 y así sucesivamente).

Por ejemplo:

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

Deberías ver un mensaje similar al siguiente ejemplo:

Creating instance...done.

C++

Para obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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 obtener información sobre cómo instalar y usar la biblioteca cliente de Cloud Spanner, consulta Bibliotecas cliente de 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

Genera una lista de instancias

Console

Ve a la página Instancias de Spanner en Cloud Console.

Ir a la página Instancias

Cloud Console muestra una lista de tus instancias de Cloud Spanner, junto con cada ID de instancia, nombre visible, configuración y capacidad de procesamiento expresada en unidades de procesamiento y en nodos.

gcloud

Usa el comando gcloud spanner instances list:

gcloud spanner instances list

La CLI de gcloud muestra una lista de tus instancias de Cloud Spanner, junto con cada ID de instancia, nombre visible, configuración y capacidad de procesamiento.

Edita una instancia

En las siguientes secciones, se explica cómo cambiar el nombre visible y la capacidad de procesamiento de una instancia. No puedes cambiar el ID ni la configuración de la instancia.

Cambia el nombre visible

Console

  1. Ve a la página Instancias de Spanner en Cloud Console.

    Ir a la página Instancias

  2. Haz clic en el nombre de la instancia a la que deseas cambiarle el nombre.

  3. Haz clic en Editar instancia.

  4. Ingresa un nuevo nombre de instancia. Este nombre debe ser único dentro del proyecto de Google Cloud.

  5. Haz clic en Guardar.

gcloud

Usa el comando gcloud spanner instances update:

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

Ingresa los siguientes valores:

  • [INSTANCE-ID]: Identificador permanente de la instancia.
  • [INSTANCE-NAME]: El nombre que se mostrará para la instancia en Cloud Console. El nombre de la instancia debe ser único en tu proyecto de Google Cloud.

Cambia la capacidad de procesamiento

Debes aprovisionar suficiente capacidad de procesamiento para mantener el uso de CPU y el uso de almacenamiento por debajo de los máximos recomendados. Para obtener más información, consulta las cuotas y límites de Cloud Spanner.

Existen algunos casos en los que no puedes reducir la capacidad de procesamiento de una instancia existente:

  • Quitar la capacidad de procesamiento requeriría que tu instancia almacene más de 4 TB de datos por cada 1,000 unidades de procesamiento (1 nodo).
  • Debido a tus patrones de uso históricos, Cloud Spanner creó una gran cantidad de divisiones para tus datos y, en algunos casos, Cloud Spanner no podría administrar las divisiones después de quitar la capacidad de procesamiento.

En el último caso, puedes intentar reducir la capacidad de procesamiento en cantidades progresivamente más pequeñas hasta encontrar la capacidad mínima que necesita Cloud Spanner para administrar todas las divisiones de la instancia. Si la instancia ya no necesita tantas divisiones debido a un cambio en los patrones de uso, Cloud Spanner puede combinar algunas divisiones y permitirte intentar reducir la capacidad de procesamiento de la instancia después de una o dos semanas.

Cuando quites la capacidad de procesamiento, supervisa el uso de CPU y solicita latencias en Cloud Monitoring a fin de asegurarte de que el uso de CPU se mantenga por debajo del 65% para las instancias regionales y del 45% para cada región en instancias multirregionales. Es posible que experimentes un aumento temporal en la latencia de las solicitudes mientras se quita la capacidad de procesamiento.

Si quieres aumentar la capacidad de procesamiento de una instancia, tu proyecto de Google Cloud debe tener cuota suficiente para agregar la capacidad de procesamiento.

Console

  1. Ve a la página Instancias de Spanner en Cloud Console.

    Ir a la página Instancias

  2. Haz clic en el nombre de la instancia que deseas cambiar.

  3. Haz clic en Editar instancia.

  4. Para cambiar la capacidad de procesamiento, elige las unidades de medida (unidades de procesamiento o nodos) y, luego, ingresa una cantidad. Cuando uses unidades de procesamiento, ingresa cantidades hasta 1,000 en múltiplos de 100 (100, 200, 300, etc.) y, luego, ingresa cantidades más grandes en múltiplos de 1,000 (1,000, 2,000, 3,000 y así sucesivamente). Cada nodo equivale a 1,000 unidades de procesamiento.

  5. Haz clic en Guardar.

    Si ves un cuadro de diálogo que indica que tienes una cuota insuficiente para agregar capacidad de procesamiento en esta ubicación, sigue las instrucciones a fin de solicitar una cuota superior.

gcloud

Usa el comando gcloud spanner instances update. Cuando uses este comando, especifica la capacidad de procesamiento como un número de nodos o unidades de procesamiento.

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

o

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

Ingresa los siguientes valores:

  • [INSTANCE-ID]: Identificador permanente de la instancia.
  • [NODE-COUNT]: La capacidad de procesamiento de la instancia, expresada como una cantidad de nodos. Cada nodo equivale a 1,000 unidades de procesamiento.
  • [PROCESSING-UNIT-COUNT]: La capacidad de procesamiento de la instancia, expresada como una cantidad de unidades de procesamiento. Ingresa cantidades hasta 1,000 en múltiplos de 100 (100, 200, 300 y así sucesivamente) y, luego, ingresa cantidades mayores en múltiplos de 1,000 (1,000, 2,000, 3,000 y así sucesivamente).

Etiquetar una instancia

Etiquetas para organizar tus recursos.

Console

  1. Ve a la página Instancias de Spanner en Cloud Console.

    Ir a la página Instancias

  2. Selecciona la casilla de verificación de la instancia. El panel de información aparece en el lado derecho de la página.

  3. Haz clic en la pestaña Etiquetas en el panel de información. Luego, puedes agregar, borrar o actualizar etiquetas para la instancia de Cloud Spanner.

Borra una instancia

Console

  1. Ve a la página Instancias de Spanner en Cloud Console.

    Ir a la página Instancias

  2. Haz clic en el nombre de la instancia que deseas borrar.

  3. Haz clic en Borrar instancia.

  4. Sigue las instrucciones para confirmar que deseas borrar la instancia.

  5. Haz clic en Borrar.

gcloud

Usa el comando gcloud spanner instances delete y reemplaza [INSTANCE-ID] por el ID de la instancia:

gcloud spanner instances delete [INSTANCE-ID]

Detén o reinicia una instancia

Cloud Spanner es un servicio de base de datos completamente administrado que supervisa sus propias tareas y recursos subyacentes, incluida la supervisión y el reinicio de los procesos cuando es necesario sin tiempo de inactividad. Como no es necesario detener o reiniciar una instancia determinada de forma manual, Cloud Spanner no ofrece una manera de hacerlo.

¿Qué sigue?