Criar uma instância

Uma instância do Bigtable é um contêiner de clusters do Bigtable. Uma instância que tem mais de um cluster usa replicação. É possível criar clusters em até oito regiões, com o mesmo número de clusters em cada região.

Nesta página, você verá como criar uma instância. Antes de ler esta página, familiarize-se com a visão geral do Bigtable. Leia também a visão geral de instâncias, clusters e nós.

Antes de começar

Preparar o ambiente:

  1. Sign in to your Google Account.

    If you don't already have one, sign up for a new account.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Make sure that billing is enabled for your Google Cloud project.

  4. Enable the Cloud Bigtable API, Cloud Bigtable Admin API APIs.

    Enable the APIs

  5. Install the Google Cloud CLI.

  6. To initialize the gcloud CLI, run the following command: 

    gcloud init

  7. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  8. Make sure that billing is enabled for your Google Cloud project.

  9. Enable the Cloud Bigtable API, Cloud Bigtable Admin API APIs.

    Enable the APIs

  10. Install the Google Cloud CLI.

  11. To initialize the gcloud CLI, run the following command: 

    gcloud init
  12. Execute o seguinte comando para instalar a CLI cbt: 
    gcloud components install cbt

Planejar a configuração:

  1. Opicional: se você planeja ativar a replicação, faça o seguinte:

  2. Opcional: se você quiser usar chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês) em vez da criptografia padrão gerenciada pelo Google, conclua as tarefas em Como criar uma instância habilitada para CMEK e tenha o ID de chave CMEK em mãos antes de criar a nova instância. Não é possível adicionar a proteção CMEK a uma instância depois que ela foi criada. Também não é possível modificar ou substituir a chave CMEK após a criação da instância.

Criar uma instância

Para criar uma instância do Bigtable:

Console

  1. No Console do Google Cloud, acesse a página Criar instância.

    Acessar "Criar instância"

  2. Digite um nome para a instância.

    O Console do Google Cloud exibe esse nome para identificar a instância.

  3. Digite o ID de uma instância.

    O código da instância é um identificador permanente da instância.

  4. Clique em Continuar.

  5. Escolha se é necessário usar um disco SSD ou HDD nos clusters. Na maioria dos casos, o SSD é o melhor. Essa opção é permanente. Saiba mais.

  6. Clique em Continuar.

  7. Digite o código do primeiro cluster.

    O código é um identificador permanente do cluster.

  8. Escolha a região e a zona em que o primeiro cluster será executado.

  9. Escolha um modo de escalonamento de nó para o cluster. Na maioria dos casos, escolha o escalonamento automático. Para orientações sobre escalonamento, consulte Escalonamento automático.

    1. Em Alocação manual de nós, insira o número de nós do Bigtable para o primeiro cluster. Caso não tenha certeza de quantos nós são necessários, use o padrão. Será possível adicionar mais nodes depois.
    2. Em Escalonamento automático, insira os valores a seguir:
      • Número mínimo de nós
      • Número máximo de nós
      • Meta de utilização da CPU
      • Meta de uso do armazenamento

  10. (Opcional) Para proteger a instância com CMEK em vez da criptografia padrão gerenciada pelo Google, conclua o seguinte:

    1. Clique em Mostrar opções de criptografia.
    2. Selecione o botão de opção ao lado de Chave de criptografia gerenciada pelo cliente (CMEK, na sigla em inglês).
    3. Selecione ou insira o nome do recurso para a chave de CMEK que você quer usar para o cluster. Não é possível adicionar essa informação posteriormente.
    4. Se for solicitado que você conceda permissão à conta de serviço da chave CMEK, clique em Conceder. Sua conta de usuário precisa receber o papel de Administrador do Cloud KMS para concluir essa tarefa.
    5. Clique em Save.

  11. (Opcional) Para ativar a replicação agora, conclua as etapas a seguir:

    1. Clique em Exibir opções avançadas.
    2. Clique em Adicionar cluster, insira as configurações do cluster e clique em Adicionar. Repita essa etapa para criar outros clusters na instância. Também é possível ativar a replicação posteriormente adicionando um cluster.

    Cada zona em uma região pode conter apenas um cluster. Caso o botão Adicionar cluster esteja desativado, altere a zona do primeiro cluster.

    Para criar uma instância com mais de seis clusters, primeiro crie uma instância com seis clusters. Depois, adicione mais clusters.

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

  13. Revise as configurações de replicação no perfil de aplicativo padrão para ver se elas se aplicam ao caso de uso de replicação. Talvez seja necessário atualizar o perfil de aplicativo padrão ou criar perfis de aplicativo personalizados.

gcloud

  1. Use o comando bigtable instances create para criar uma instância:

    gcloud bigtable instances create INSTANCE_ID \
    --display-name=DISPLAY_NAME \
    [--cluster-storage-type=CLUSTER_STORAGE_TYPE] \
    [--cluster-config=id=CLUSTER_ID,zone=CLUSTER_ZONE, \
    nodes=NODES] \
    [--cluster-config=id=CLUSTER_ID,zone=CLUSTER_ZONE, \
    autoscaling-min-nodes=AUTOSCALING_MIN_NODES, \
    autoscaling-max-nodes=AUTOSCALING_MAX_NODES, \
    autoscaling-cpu-target=AUTOSCALING_CPU_TARGET, \
    autoscaling-storage-target=AUTOSCALING_STORAGE_TARGET, \
    kms-key=KMS_KEY]

    Substitua:

    • INSTANCE_ID: identificador permanente da instância
    • DISPLAY_NAME: um nome legível que identifica a instância no console do Google Cloud.
    • CLUSTER_ID: identificador permanente do cluster.
    • CLUSTER_ZONE: a zona em que o cluster é executado.

    É necessário configurar pelo menos um cluster para a instância usando a sinalização --cluster-config. Para criar uma instância que tenha vários clusters, repita a sinalização --cluster-config para cada um deles.

    Para alocação manual de nós, é opcional configurar nodes na sinalização --cluster-config. Se nenhum valor for definido, o Bigtable vai alocar nós para o cluster automaticamente com base no volume de dados e otimizar para 50% da utilização do armazenamento. Essa alocação automática de nós afeta o preço. Se você quiser controlar o número de nós em um cluster, substitua NODES pelo número de nós que você quer no cluster. Saiba mais sobre nós.

    Na maioria dos casos, escolha o escalonamento automático em vez da alocação manual de nós. Para _autoscaling, forneça as opções autoscaling- na flag --cluster-config (autoscaling-storage-target é opcional) e não use nodes. Veja escalonamento automático para orientações sobre como escolher os valores das suas configurações de escalonamento automático. Substitua o seguinte cluster-config para as chaves de opção:

    • AUTOSCALING_MIN_NODES: o número mínimo de nós do cluster.
    • AUTOSCALING_MAX_NODES: o número máximo de nós para o cluster.
    • AUTOSCALING_CPU_TARGET: a meta de uso da CPU para o cluster. Esse valor precisa ser de 10 a 80.
    • AUTOSCALING_STORAGE_TARGET: (opcional) o destino de utilização do armazenamento em GiB que o Bigtable mantém adicionando ou removendo nós.

    • KMS_KEY: a chave CMEK para o cluster.

      O valor KMS_KEY precisa ser definido no seguinte formato:

      projects/PROJECT/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY

      Substitua:

      • PROJECT: identificador permanente do projeto
      • LOCATION: o local do cluster
      • KEYRING: o nome do keyring que contém a chave
      • KEY: o nome da chave;

      Veja um exemplo abaixo.

      projects/examplestore.com:dev/locations/us-east1/keyRings/devt-cmek-2/cryptoKeys/key2

      Se a instância estiver protegida por CMEK, cada cluster precisará estar na mesma região que a chave CMEK. Só é possível adicionar clusters do CMEK a instâncias que já estejam protegidas por CMEK. Saiba mais.

    O comando aceita as sinalizações opcionais a seguir:

    • --cluster-storage-type=CLUSTER_STORAGE_TYPE: o tipo de armazenamento a ser usado na instância. O valor padrão é SSD. Na maioria dos casos, o valor padrão é o melhor. Essa opção é permanente. Saiba mais.

    • --project=PROJECT: projeto em que o cluster será criado se for diferente do projeto atual.

  2. Revise as configurações de replicação no perfil de aplicativo padrão para ver se elas se aplicam ao caso de uso de replicação. Talvez seja necessário atualizar o perfil de aplicativo padrão ou criar perfis de aplicativo personalizados.

cbt

  1. Comece criando uma instância com um único cluster. Use o comando createinstance para criar uma instância:

    cbt createinstance INSTANCE_ID \
    DISPLAY_NAME \
    CLUSTER_ID \
    CLUSTER_ZONE \
    CLUSTER_NUM_NODES \
    CLUSTER_STORAGE_TYPE

    Preencha o seguinte:

    • INSTANCE_ID: identificador permanente da instância
    • DISPLAY_NAME: um nome legível que identifica a instância no console do Google Cloud.
    • CLUSTER_ID: identificador permanente do cluster.
    • CLUSTER_ZONE: a zona em que o cluster é executado.
    • CLUSTER_NUM_NODES: este campo é opcional. Se nenhum valor for definido, o Bigtable vai alocar automaticamente os nós com base no seu volume de dados e otimizar para 50% da utilização do armazenamento. Se você quiser controlar o número de nós em um cluster, atualize o valor CLUSTER_NUM_NODES. Verifique se o número de nós está definido como um valor diferente de zero. Saiba mais sobre nós.
    • CLUSTER_STORAGE_TYPE: o tipo de armazenamento a ser usado no cluster. Cada cluster em uma instância precisa usar o mesmo tipo de armazenamento. Aceita os valores SSD e HDD. Na maioria dos casos, o SSD é o melhor. Essa opção é permanente. Saiba mais.

  2. Para ativar a replicação, use o comando createcluster para adicionar um cluster:

    
cbt -instance=INSTANCE_ID \
createcluster CLUSTER_ID \
ZONE \
NUM_NODES \
STORAGE_TYPE

    Preencha o seguinte:

    • INSTANCE_ID: identificador permanente da instância recém-criada.
    • CLUSTER_ID: identificador permanente do cluster.

    • ZONE: a zona em que o cluster é executado.

      Cada zona em uma região pode conter apenas um cluster. Por exemplo, se uma instância tiver um cluster em us-east1-b, será possível adicionar um cluster em uma zona diferente na mesma região, como us-east1-c, ou em uma zona em uma região separada, como europe-west2-a.

    • NUM_NODES: este campo é opcional. Se nenhum valor for definido, o Bigtable vai alocar automaticamente os nós com base no seu volume de dados e otimizar para 50% da utilização do armazenamento. Se você quiser controlar o número de nós em um cluster, atualize o valor NUM_NODES. Verifique se o número de nós está definido como um valor diferente de zero.

      Em muitos casos, cada cluster em uma instância precisa ter o mesmo número de nós, mas há exceções. Saiba mais sobre nós e replicação.

    • STORAGE_TYPE: o tipo de armazenamento a ser usado no cluster. Cada cluster em uma instância precisa usar o mesmo tipo de armazenamento. Aceita os valores SSD e HDD.

  3. (Opcional) Revise as configurações de replicação no perfil de aplicativo padrão para saber se elas se aplicam ao caso de uso de replicação. Talvez seja necessário atualizar o perfil de aplicativo padrão ou criar perfis de aplicativo personalizados.

C++

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

namespace cbta = ::google::cloud::bigtable_admin;
using ::google::cloud::future;
using ::google::cloud::Location;
using ::google::cloud::Project;
using ::google::cloud::StatusOr;
[](cbta::BigtableInstanceAdminClient instance_admin,
   std::string const& project_id, std::string const& instance_id,
   std::string const& zone) {
  auto const project = Project(project_id);
  std::string project_name = project.FullName();
  std::string cluster_id = instance_id + "-c1";

  google::bigtable::admin::v2::Instance in;
  in.set_type(google::bigtable::admin::v2::Instance::PRODUCTION);
  in.set_display_name("Put description here");

  google::bigtable::admin::v2::Cluster cluster;
  cluster.set_location(Location(project, zone).FullName());
  cluster.set_serve_nodes(3);
  cluster.set_default_storage_type(google::bigtable::admin::v2::HDD);

  std::map<std::string, google::bigtable::admin::v2::Cluster> cluster_map = {
      {cluster_id, std::move(cluster)}};

  future<StatusOr<google::bigtable::admin::v2::Instance>> instance_future =
      instance_admin.CreateInstance(project_name, instance_id, std::move(in),
                                    std::move(cluster_map));
  // Show how to perform additional work while the long running operation
  // completes. The application could use future.then() instead.
  std::cout << "Waiting for instance creation to complete " << std::flush;
  instance_future.wait_for(std::chrono::seconds(1));
  std::cout << '.' << std::flush;
  auto instance = instance_future.get();
  if (!instance) throw std::move(instance).status();
  std::cout << "DONE, details=" << instance->DebugString() << "\n";
}

C#

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

// Creates a production instance with "<intanceId>-prod" instance ID,
// with cluster ID "ssd-cluster1", 3 nodes and location us-east1-b.
displayName += " Prod"; // Display name is for display purposes only. It doesn't have to equal instanceId and can be amended after instance is created.
string instanceId = Regex.Replace(displayName, @"[^A-Za-z0-9_\.~]+", "-").ToLower();

// Please refer to the link below for the full list of available locations:
// https://cloud.google.com/bigtable/docs/locations
string zone1 = "us-east1-b";

// The instance to create.
Instance myInstance = new Instance
{
    DisplayName = displayName,
    // You can choose DEVELOPMENT or PRODUCTION type here.
    // If not set, will default to PRODUCTION type.
    // Instance type can be upgraded from DEVELOPMENT to PRODUCTION but cannot be dowgraded after the instance is created.
    Type = Instance.Types.Type.Production,
    Labels = { { "prod-label", "prod-label" } }
};

// The first cluster to be created within the instance.
Cluster myCluster1 = new Cluster
{
    // You can choose SSD or HDD storage type here: StorageType.Ssd or StorageType.Hdd.
    // Cluster storage type can not be changed after the instance is created.
    // If not set will default to SSD type.
    DefaultStorageType = StorageType.Ssd,
    LocationAsLocationName = new LocationName(projectId, zone1),
    // Serve Nodes count can only be set if PRODUCTION type instance is being created.
    // Minimum count of 3 serve nodes must be specified.
    // Serve Nodes count can be increased and decreased after an instance is created.
    ServeNodes = 3
};

// Initialize request argument(s).
CreateInstanceRequest request = new CreateInstanceRequest
{
    ParentAsProjectName = new ProjectName(projectId),
    Instance = myInstance,
    InstanceId = instanceId,
    // Must specify at lease one cluster.
    // Only PRODUCTION type instance can be created with more than one cluster.
    // Currently all clusters must have the same storage type.
    // Clusters must be set to different locations.
    Clusters = { { "ssd-cluster1", myCluster1 } }
};

try
{
    // Make a request.
    Operation<Instance, CreateInstanceMetadata> createInstanceResponse =
        bigtableInstanceAdminClient.CreateInstance(request);
    Console.WriteLine("Waiting for operation to complete...");

    // Poll until the returned long-running operation is complete
    Operation<Instance, CreateInstanceMetadata> completedResponse =
        createInstanceResponse.PollUntilCompleted();
}
catch (Exception ex)
{
    Console.WriteLine($"Exception while creating {displayName} instance");
    Console.WriteLine(ex.Message);
}

Java

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

// Creates a Production Instance with the ID "ssd-instance",
// cluster id "ssd-cluster", 3 nodes and location "us-central1-f".
CreateInstanceRequest createInstanceRequest =
    CreateInstanceRequest.of(instanceId)
        .addCluster(clusterId, "us-central1-f", 3, StorageType.SSD)
        .setType(Instance.Type.PRODUCTION)
        .addLabel("department", "accounting");
// Creates a production instance with the given request.
try {
  Instance instance = adminClient.createInstance(createInstanceRequest);
  System.out.printf("PRODUCTION type instance %s created successfully%n", instance.getId());
} catch (Exception e) {
  System.err.println("Failed to create instance: " + e.getMessage());
  throw e;
}

Node.js

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

// Creates a Production Instance with the ID "ssd-instance"
// with cluster id "ssd-cluster", 3 nodes and location us-central1-f

const instanceOptions = {
  clusters: [
    {
      id: clusterID,
      nodes: 3,
      location: 'us-central1-f',
      storage: 'ssd',
    },
  ],
  type: 'PRODUCTION', // Optional as default type is PRODUCTION
  labels: {'prod-label': 'prod-label'},
};

// Create production instance with given options
const [prodInstance, operation] = await instance.create(instanceOptions);
await operation.promise();
console.log(`Created Instance: ${prodInstance.id}`);

PHP

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

use Exception;
use Google\ApiCore\ApiException;
use Google\Cloud\Bigtable\Admin\V2\Client\BigtableInstanceAdminClient;
use Google\Cloud\Bigtable\Admin\V2\Cluster;
use Google\Cloud\Bigtable\Admin\V2\CreateInstanceRequest;
use Google\Cloud\Bigtable\Admin\V2\GetInstanceRequest;
use Google\Cloud\Bigtable\Admin\V2\Instance;
use Google\Cloud\Bigtable\Admin\V2\Instance\Type as InstanceType;
use Google\Cloud\Bigtable\Admin\V2\StorageType;

/**
 * Create a production Bigtable instance
 *
 * @param string $projectId The Google Cloud project ID
 * @param string $instanceId The ID of the Bigtable instance to be generated
 * @param string $clusterId The ID of the cluster to be generated
 * @param string $locationId The Bigtable region ID where you want your instance to reside
 */
function create_production_instance(
    string $projectId,
    string $instanceId,
    string $clusterId,
    string $locationId = 'us-east1-b'
): void {
    $instanceAdminClient = new BigtableInstanceAdminClient();

    $projectName = $instanceAdminClient->projectName($projectId);
    $instanceName = $instanceAdminClient->instanceName($projectId, $instanceId);

    $serveNodes = 3;
    $storageType = StorageType::SSD;
    $production = InstanceType::PRODUCTION;
    $labels = ['prod-label' => 'prod-label'];

    $instance = new Instance();
    $instance->setDisplayName($instanceId);

    $instance->setLabels($labels);
    $instance->setType($production);

    $cluster = new Cluster();
    $cluster->setDefaultStorageType($storageType);
    $locationName = $instanceAdminClient->locationName($projectId, $locationId);
    $cluster->setLocation($locationName);
    $cluster->setServeNodes($serveNodes);
    $clusters = [
        $clusterId => $cluster
    ];
    try {
        $getInstanceRequest = (new GetInstanceRequest())
            ->setName($instanceName);
        $instanceAdminClient->getInstance($getInstanceRequest);
        printf('Instance %s already exists.' . PHP_EOL, $instanceId);
        throw new Exception(sprintf('Instance %s already exists.' . PHP_EOL, $instanceId));
    } catch (ApiException $e) {
        if ($e->getStatus() === 'NOT_FOUND') {
            printf('Creating an Instance: %s' . PHP_EOL, $instanceId);
            $createInstanceRequest = (new CreateInstanceRequest())
                ->setParent($projectName)
                ->setInstanceId($instanceId)
                ->setInstance($instance)
                ->setClusters($clusters);
            $operationResponse = $instanceAdminClient->createInstance($createInstanceRequest);
            $operationResponse->pollUntilComplete();
            if (!$operationResponse->operationSucceeded()) {
                print('Error: ' . $operationResponse->getError()->getMessage());
            } else {
                printf('Instance %s created.', $instanceId);
            }
        } else {
            throw $e;
        }
    }
}

Python

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

cluster = instance.cluster(
    cluster_id,
    location_id=location_id,
    serve_nodes=serve_nodes,
    default_storage_type=storage_type,
)
if not instance.exists():
    print("\nCreating an instance")
    # Create instance with given options
    operation = instance.create(clusters=[cluster])
    # Ensure the operation completes.
    operation.result(timeout=480)
    print("\nCreated instance: {}".format(instance_id))

Ruby

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

Para autenticar no Bigtable, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local. 

# instance_id      = "my-instance"
# cluster_id       = "my-cluster"
# cluster_location = "us-east1-b"
puts "Creating a PRODUCTION Instance"
job = bigtable.create_instance(
  instance_id,
  display_name: "Sample production instance",
  labels:       { "env": "production" },
  type:         :PRODUCTION # Optional as default type is :PRODUCTION
) do |clusters|
  clusters.add cluster_id, cluster_location, nodes: 3, storage_type: :SSD
end

job.wait_until_done!
instance = job.instance
puts "Created Instance: #{instance.instance_id}"

A seguir