Create an instance
A Bigtable instance is a container for Bigtable clusters. An instance that has more than one cluster uses replication. You can create clusters in up to 8 regions, with as many clusters in each region as there are zones.
This page explains how to create an instance. 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:
-
Sign in to your Google Account.
If you don't already have one, sign up for a new account.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Bigtable API, Cloud Bigtable Admin API APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
Enable the Cloud Bigtable API, Cloud Bigtable Admin API APIs.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
- Run the following command to install the
cbt
CLI :gcloud components install cbt
Plan your configuration:
Optional: 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.
Optional: If you want 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
In the Google Cloud console, go to the Create instance page.
Enter a name for the instance.
The Google Cloud console displays this name to identify your instance.
Enter an instance ID.
The instance ID is a permanent identifier for the instance.
Click Continue.
Choose whether to use an SSD or HDD disk for your clusters. In most cases, SSD is best. This choice is permanent. Learn more.
Click Continue.
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.
Choose a node scaling mode for the cluster. In most cases, you should choose autoscaling. For scaling guidance, see Autoscaling.
- 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.
- For Autoscaling, enter values for the following:
- Minimum number of nodes
- Maximum number of nodes
- CPU utilization target
- Storage utilization target
(Optional) To protect your instance with CMEK instead of the default Google-managed encryption, complete the following:
- Click Show encryption options.
- Select the radio button next to Customer-managed encryption key (CMEK).
- Select or enter the resource name for the CMEK key that you want to use for the cluster. You cannot add this later.
- 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.
- Click Save.
(Optional) To enable replication now, complete the following additional steps:
- Click Show advanced options.
- Click Add cluster, enter the settings for the cluster, and then click Add. Repeat this step to create additional clusters in the instance. You can also enable replication later by adding a cluster.
Each zone in a region can contain only one cluster. If the Add cluster button is disabled, change the zone for your first cluster.
To create an instance that has more than six clusters, first create an instance that has six clusters, then add more clusters to the instance.
Click Create to create the instance.
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
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=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]
Replace the following:
INSTANCE_ID
: The permanent identifier for the instance.DISPLAY_NAME
: A human-readable name that identifies the instance in the Google Cloud console.CLUSTER_ID
: The permanent identifier for the cluster.CLUSTER_ZONE
: The zone where the cluster runs.
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, setting
nodes
in the--cluster-config
flag is optional. If no value is set, Bigtable allocates nodes to the cluster automatically based on your data footprint and optimizes for 50% storage utilization. This automatic allocation of nodes has a pricing impact. If you want to control the number of nodes in a cluster, replaceNODES
with the number of nodes that you want in the cluster. Learn more about nodes.In most cases, choose autoscaling instead of manual node allocation. For_autoscaling, provide
autoscaling-
options in the--cluster-config
flag (autoscaling-storage-target
is optional) and don't usenodes
. See Autoscaling for guidance on choosing the values for your autoscaling settings. Replace the following for thecluster-config
option keys: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 percentage for the cluster. This value must be from 10 to 80.AUTOSCALING_STORAGE_TARGET
: (Optional) The storage utilization target in GiB that Bigtable maintains by adding or removing nodes.KMS_KEY: The CMEK key for the cluster.
The KMS_KEY value must be set in the following format:
projects/PROJECT/locations/LOCATION/keyRings/KEYRING/cryptoKeys/KEY
Replace the following:
- PROJECT: the permanent identifier for the project
- LOCATION: the location of your cluster
- KEYRING: the name of the key ring that contains the key
- KEY: the name of the key
The following is an example:
projects/examplestore.com:dev/locations/us-east1/keyRings/devt-cmek-2/cryptoKeys/key2
If the instance is CMEK-protected, each cluster must be in the same region as its CMEK key. You can add CMEK clusters only to instances that are already CMEK-protected. Learn more.
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 isSSD
. In most cases, the default value is best. This choice is permanent. Learn more.--project=PROJECT
: The project in which to create the cluster if different from the current project.
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:
INSTANCE_ID
: The permanent identifier for the instance.DISPLAY_NAME
: A human-readable name that identifies the instance in the Google Cloud console.CLUSTER_ID
: The permanent identifier for the cluster.CLUSTER_ZONE
: The zone where the cluster runs.CLUSTER_NUM_NODES
: This field is optional. If no value is set, Bigtable automatically allocates nodes based on your data footprint and optimizes for 50% storage utilization. If you want to control the number of nodes in a cluster, update theCLUSTER_NUM_NODES
value. Ensure that number of nodes is set to a non-zero value. Learn more about nodes.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 valuesSSD
andHDD
. 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:
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.Each zone in a region can contain only one cluster. For example, if an instance has a cluster in
us-east1-b
, you can add a cluster in a different zone in the same region, such asus-east1-c
, or a zone in a separate region, such aseurope-west2-a
.NUM_NODES
: This field is optional. If no value is set, Bigtable automatically allocates nodes based on your data footprint and optimizes for 50% storage utilization. If you want to control the number of nodes in a cluster, update theNUM_NODES
value. Ensure that number of nodes is set to a non-zero value.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 valuesSSD
andHDD
.
(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.
C++
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C#
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
To learn how to install and use the client library for Bigtable, see Bigtable client libraries.
To authenticate to Bigtable, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
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.