Creating a Cloud Bigtable Instance

A Cloud Bigtable instance is a container for up to two Cloud Bigtable clusters. Instances that use replication have two clusters, and other instances have only one cluster.

This page explains how to create an instance with or without replication. Before you read this page, you should be familiar with the overview of Cloud Bigtable. You should also read the overview of instances, clusters, and nodes.

Before you begin

Before you begin, you'll need to prepare your environment and do some initial planning:

  1. Enable the Cloud Bigtable APIs:

    1. Select or create a GCP project.

      Go to the Manage resources page

    2. Make sure that billing is enabled for your project.

      Learn how to enable billing

    3. Enable the Cloud Bigtable and Cloud Bigtable Admin APIs.

      Enable the APIs

  2. If you want to use the command-line tools for Cloud Bigtable, install the Cloud SDK and the cbt command-line tool if you haven't already.

  3. If you plan to enable replication, take a few minutes to read the replication overview.

    You should identify your use case for replication; choose a region for your instance that offers Cloud Bigtable in at least two zones; and decide how you'll use application profiles to route incoming requests.

Creating an instance

To create a Cloud Bigtable instance:

Console

  1. Open the Create Instance page in the GCP Console.

    Open the Create Instance page

    Screenshot of the "Create instance" page

  2. Enter a name for the instance.

    The GCP Console displays this name to identify your instance.

  3. Enter an instance ID.

    The instance ID is a permanent identifier for the instance.

  4. Select the type of instance to create.

    For development and testing, use a development instance, which has limited performance and no SLA. You can upgrade to a production instance later. Learn more.

    For other purposes, use a production instance. This choice is permanent. Learn more.

  5. Enter a cluster ID for the first cluster.

    The cluster ID is a permanent identifier for the cluster.

  6. Choose the region and zone where the first cluster will run.

    If you plan to use replication, make sure Cloud Bigtable is available in at least one other zone in your preferred region. View the zone list.

  7. Choose the number of Cloud Bigtable nodes for the first cluster. If you aren't sure how many nodes you need, use the default. You can add more nodes later. Learn more.

  8. To enable replication now, click Add cluster, then update the settings for the second cluster. You can also enable replication later by adding a cluster.

    An instance's clusters must be in unique zones that are within the same region. If the Add cluster button is disabled, change the zone for your first cluster.

  9. Choose whether to use an SSD or HDD disk for your clusters. In most cases, SSD is best. This choice is permanent. Learn more.

    The GCP Console shows how the disk type and number of nodes affect your throughput and cost.

  10. Click Create to create the instance.

  11. If you've started using replication in an instance, your next step is to review the replication settings in the default app profile to see if they make sense for your replication use case. You might need to update the default app profile or create custom app profiles.

gcloud

  1. Start by creating an instance with a single cluster. Use the beta bigtable instances create command to create an instance:

    gcloud beta bigtable instances create INSTANCE_ID \
        --cluster=CLUSTER_ID \
        --cluster-zone=CLUSTER_ZONE \
        --display-name=DISPLAY_NAME \
        [--cluster-num-nodes=CLUSTER_NUM_NODES] \
        [--cluster-storage-type=CLUSTER_STORAGE_TYPE] \
        [--instance-type=INSTANCE_TYPE]
    

    Provide the following values:

    • INSTANCE_ID: The permanent identifier for the instance.
    • CLUSTER_ID: The permanent identifier for the cluster.
    • CLUSTER_ZONE: The zone where the cluster runs.

      If you plan to use replication, make sure Cloud Bigtable is available in at least one other zone in your preferred region. View the zone list.

    • DISPLAY_NAME: A human-readable name that identifies the instance in the GCP Console.

    The command accepts the following optional flags:

    • --cluster-num-nodes=CLUSTER_NUM_NODES: The number of nodes in the cluster. Clusters in a production instance must have 3 or more nodes. The default value is 3. If you aren't sure how many nodes you need, use the default. You can add more nodes later. Learn more.

      Do not use this flag for development instances.

    • --cluster-storage-type=CLUSTER_STORAGE_TYPE: The type of storage to use for the cluster. Each cluster in an instance must use the same storage type. Accepts the values SSD and HDD. The default value is SSD.

      In most cases, the default value is best. This choice is permanent. Learn more.

    • --instance-type=INSTANCE_TYPE: The type of instance to create. Accepts one of the following values:

      • PRODUCTION (default): A high-availability, full-powered instance. This choice is permanent. Learn more.
      • DEVELOPMENT: A low-cost instance for development and testing, with limited performance and no SLA. You can upgrade to a production instance later. Learn more.
  2. To enable replication for a production instance, use the beta bigtable clusters create command to add a cluster:

    gcloud beta bigtable clusters create CLUSTER_ID \
        --instance=INSTANCE_ID \
        --zone=ZONE \
        [--num-nodes=NUM_NODES] \
        [--storage-type=STORAGE_TYPE]
    

    Provide the following values:

    • CLUSTER_ID: The permanent identifier for the cluster.
    • INSTANCE_ID: The permanent identifier for the instance you just created.
    • ZONE: The zone where the cluster runs.

      An instance's clusters must be in unique zones that are within the same region. For example, if the first cluster is in us-east1-b, then us-east1-c is a valid zone for the second cluster.

    The command accepts the following optional flags:

    • --num-nodes=NUM_NODES: The number of nodes in the cluster. Clusters in a production instance must have 3 or more nodes.

      In many cases, each cluster in an instance should have the same number of nodes, but there are exceptions. Learn about nodes and replication.

    • --storage-type=STORAGE_TYPE: The type of storage to use for the cluster. Each cluster in an instance must use the same storage type. Accepts the values SSD and HDD. The default value is SSD.

  3. If you've started using replication in an instance, your next step is to review the replication settings in the default app profile to see if they make sense for your replication use case. You might need to update the default app profile or create custom app profiles.

cbt

  1. Start by creating an instance with a single cluster. Use the createinstance command to create an instance:

    cbt createinstance INSTANCE_ID DISPLAY_NAME CLUSTER_ID CLUSTER_ZONE \
        CLUSTER_NUM_NODES CLUSTER_STORAGE_TYPE
    

    Provide the following values:

    • INSTANCE_ID: The permanent identifier for the instance.
    • DISPLAY_NAME: A human-readable name that identifies the instance in the GCP Console.
    • CLUSTER_ID: The permanent identifier for the cluster.
    • CLUSTER_ZONE: The zone where the cluster runs.

      If you plan to use replication, make sure Cloud Bigtable is available in at least one other zone in your preferred region. View the zone list.

    • CLUSTER_NUM_NODES: The number of nodes in the cluster. Clusters in a production instance must have 3 or more nodes. If you aren't sure how many nodes you need, use the default. You can add more nodes later. Learn more.

    • CLUSTER_STORAGE_TYPE: The type of storage to use for the cluster. Each cluster in an instance must use the same storage type. Accepts the values SSD and HDD. In most cases, SSD is best. This choice is permanent. Learn more.
  2. To enable replication, use the createcluster command to add a cluster:

    cbt createcluster -instance INSTANCE_ID CLUSTER_ID ZONE NUM_NODES STORAGE_TYPE
    

    Provide the following values:

    • INSTANCE_ID: The permanent identifier for the instance you just created.
    • CLUSTER_ID: The permanent identifier for the cluster.
    • ZONE: The zone where the cluster runs.

      An instance's clusters must be in unique zones that are within the same region. For example, if the first cluster is in us-east1-b, then us-east1-c is a valid zone for the second cluster.

    • NUM_NODES: The number of nodes in the cluster. Clusters in a production instance must have 3 or more nodes.

      In many cases, each cluster in an instance should have the same number of nodes, but there are exceptions. Learn about nodes and replication.

    • STORAGE_TYPE: The type of storage to use for the cluster. Each cluster in an instance must use the same storage type. Accepts the values SSD and HDD.

  3. If you've started using replication in an instance, your next step is to review the replication settings in the default app profile to see if they make sense for your replication use case. You might need to update the default app profile or create custom app profiles.

What's next

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Bigtable Documentation