Creating a Cloud Bigtable Instance

A Cloud Bigtable instance is a container for up to 4 Cloud 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 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:

Select or create a GCP project.

Go to the project selector page

Important: A project name must be between 4 and 30 characters. When you type the name, the form suggests a project ID, which you can edit. The project ID must be between 6 and 30 characters, with a lowercase letter as the first character. The last character cannot be a hyphen. Project identifiers might be retained beyond the life of your project, so do not use sensitive information for the project name or ID.
Make sure billing is enabled for your Google Cloud project. Learn how to confirm that billing is enabled for your project.
Enable the Cloud Bigtable and Cloud Bigtable Admin APIs.

Enable the APIs
Click Go to credentials.
On the Credentials page, answer the required questions:
1. In response to "Which API are you using?", choose Cloud Bigtable API.
2. Answer the question about App Engine or Compute Engine. For this quickstart, you are not using them.
3. Click What credentials do I need?
4. If you are prompted to create a service account, provide the following information:
  1. Choose a name for your service account.
  2. For Role, choose Cloud Bigtable > Bigtable Administrator.
  3. For Key type, select JSON.
  4. Click Continue.
  5. Save the newly created service account JSON file to your local HOME directory or your preferred location.
5. If you are not prompted to create a new service account, click Done.
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.
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.

Creating an instance

To create a Cloud Bigtable instance:

Console

Open the Create Instance page in the Cloud Console.

Open the Create Instance page
Enter a name for the instance.

The Cloud Console displays this name to identify your instance.
Enter an instance ID.

The instance ID is a permanent identifier for the instance.
Enter a cluster ID for the first cluster.

The cluster ID is a permanent identifier for the cluster.
Choose the region and zone where the first cluster will run.

If you plan to use replication within a single region, make sure Cloud Bigtable is available in at least one other zone in that region. View the zone list.
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.
To enable replication now, click Add replicated cluster, then update the settings for the second cluster. 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 Cloud Bigtable is available. If the Add cluster button is disabled, change the zone for your first cluster.
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 Cloud Console shows how the disk type and number of nodes affect your throughput and cost.
Click Create to create the instance.
Next, 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

Start by creating an instance with a single cluster. Use the bigtable instances create command to create an instance:
```
gcloud 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] \
```
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 within a single region, make sure Cloud Bigtable is available in at least one other zone in that region. View the zone list.
- DISPLAY_NAME: A human-readable name that identifies the instance in the Cloud Console.
The command accepts the following optional flags:
- --cluster-num-nodes=CLUSTER_NUM_NODES: The number of nodes in the cluster. Each cluster in an instance must have 1 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.
- --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.
To enable replication for a production instance, use the bigtable clusters create command to add a cluster:
```
gcloud 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 each be in unique zones. You can create an additional cluster in any zone where Cloud 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.
The command accepts the following optional flags:
- --num-nodes=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=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.
Repeat the previous step to create up to 4 clusters in the instance.
Next, 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

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 Cloud Console.
- CLUSTER_ID: The permanent identifier for the cluster.
- CLUSTER_ZONE: The zone where the cluster runs.
  
  If you plan to use replication within a single region, make sure Cloud Bigtable is available in at least one other zone in that region. View the zone list.
- 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.
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 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 each be in unique zones. You can create an additional cluster in any zone where Cloud 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.
Next, 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 Cloud Bigtable uses instances, clusters, and nodes.
Learn about Cloud 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.