Create an instance

A Cloud Bigtable instance is a container for up to 4 Bigtable clusters. Instances that use replication have two or more clusters, and instances without replication 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 Bigtable. You should also read the overview of instances, clusters, and nodes.

Before you begin

Prepare your environment:

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.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

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

   Enable the APIs

5. Install and initialize the Cloud SDK.
   Note: If you installed Cloud SDK previously, make sure you have the latest available version by running gcloud components update.

6. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

7. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

8. Enable the Cloud Bigtable, Cloud Bigtable Admin APIs.

   Enable the APIs

9. Install and initialize the Cloud SDK.
   Note: If you installed Cloud SDK previously, make sure you have the latest available version by running gcloud components update.

Plan your configuration:

1. If you plan to enable replication, do the following:

   • Take a few minutes to read the replication overview.
   • Identify your use case for replication.
   • Determine the region or regions that your instance should be in, based on your use case and the location of your application and traffic.
   • Decide how you'll use application profiles to route incoming requests.

2. If you plan to use customer-managed encryption keys (CMEK) instead of the default Google-managed encryption, complete the tasks under Creating a CMEK-enabled instance and have your CMEK key ID ready before you create your new instance. You are not able to add CMEK protection to an instance after it has been created, and you cannot modify or replace the CMEK key after the instance is created.

Create an instance

To create a Bigtable instance:

Console

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

   Open the Create Instance page

2. Enter a name for the instance.

   The Cloud Console displays this name to identify your instance.

3. Enter an instance ID.

   The instance ID is a permanent identifier for the instance.

4. Click Continue.

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

6. Click Continue.

7. Enter a cluster ID for the first cluster.

   The cluster ID is a permanent identifier for the cluster.

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

9. Choose a node scaling mode for the cluster. For scaling guidance, see Autoscaling.

   1. For Manual node allocation, enter the number of 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.
   2. For Autoscaling, enter values for the following:
      • Minimum number of nodes
      • Maximum number of nodes
      • CPU utilization target

10. (Optional) To protect your instance with CMEK instead of the default Google-managed encryption, complete the following:

    1. Click Show encryption options.
    2. Select the checkbox next to Use a customer-managed encryption key (CMEK).
    3. Select or enter the resource name for the CMEK key that you want to use for the cluster. You cannot add this later.
    4. If you are prompted to grant permission to the CMEK key's service account, click Grant. Your user account must be granted the Cloud KMS Admin role to complete this task.
    5. Click Save.

11. (Optional) To enable replication now, complete the following additional steps:

    1. Click Show advanced options.
    2. Click Add cluster, enter the settings for the cluster, and then click Add. Repeat this step to create up to 4 clusters in the instance. You can also enable replication later by adding a cluster.

    An instance's clusters must each be in unique zones. You can create an additional cluster in any zone where Bigtable is available. If the Add cluster button is disabled, change the zone for your first cluster.

12. Click Create to create the instance.

13. 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. Use the bigtable instances create command to create an instance:

   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=CLUSTER_NUM_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] \
       [kms-key=KMS_KEY]
   

   Replace the following:

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

   If the instance is CMEK-protected, each cluster must be in the same region as its CMEK key. Learn more.

   You must configure at least one cluster for the instance, using the --cluster-config flag. To create an instance that has multiple clusters, repeat the --cluster-config flag for each cluster.

   For manual node allocation, use the cluster-num-nodes option in the --cluster-config flag. Replace CLUSTER_NUM_NODES with the number of nodes in the cluster. Each cluster in an instance must have one or more nodes. The default value is 1. If you aren't sure how many nodes you need, use the default. You can add more nodes later. Learn more.

   For autoscaling, provide all three autoscaling- options in the --cluster-config flag and do not use cluster-num-nodes. See Autoscaling for guidance on choosing the values for your autoscaling settings. Replace the following options in the cluster-config flag:

   • AUTOSCALING_MIN_NODES: The minimum number of nodes for the cluster.
   • AUTOSCALING_MAX_NODES: The maximum number of nodes for the cluster.
   • AUTOSCALING_CPU_TARGET: The target CPU utilization for the cluster. This value must be from 10 to 80.

   The command accepts the following optional flags:

   • --cluster-storage-type=CLUSTER_STORAGE_TYPE: The type of storage to use for the instance. The default value is SSD. In most cases, the default value is best. This choice is permanent. Learn more.

   • --kms-key=KMS_KEY: The CMEK key for the cluster. You can add CMEK clusters only to instances that are already CMEK-protected. Learn more.

   • --project=PROJECT: The project in which to create the cluster if different from the current project.

2. 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

Note: You are not able to create CMEK-protected resources or configure autoscaling using the 'cbt` command-line tool.

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:

   • INSTANCE_ID: The permanent identifier for the instance.
   • DISPLAY_NAME: A human-readable name that identifies the instance in the Cloud Console.
   • CLUSTER_ID: The permanent identifier for the cluster.
   • CLUSTER_ZONE: The zone where the cluster runs.
   • CLUSTER_NUM_NODES: The number of nodes in the cluster. Each cluster in an instance must have 1 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 -instance=INSTANCE_ID createcluster CLUSTER_ID ZONE NUM_NODES STORAGE_TYPE
   
   

   Provide the following:

   • 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 each be in unique zones. You can create an additional cluster in any zone where Bigtable is available. For example, if the first cluster is in us-east1-b, you can choose a different zone in the same region, such as us-east1-c, or a zone in a separate region, such as europe-west2-a.

   • NUM_NODES: The number of nodes in the cluster. Each cluster in an instance must have 1 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. (Optional) 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

• Find out how Bigtable uses instances, clusters, and nodes.
• Learn about Bigtable replication.
• Review and update the default app profile for replication, and create custom app profiles as needed.
• Find out how to modify an existing instance.