Create an instance

A Bigtable instance is a container for Bigtableclusters. An instance that has more than one cluster usesreplication. You can create clusters in up to8 regions, with as many clusters in eachregion as there are zones.

This page explains how to create an instance. Before you read this page, you should be familiar with theoverview of Bigtable. You shouldalso read theoverview 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.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
    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. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

  5. Install the Google Cloud CLI.

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. Toinitialize the gcloud CLI, run the following command:

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

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
    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

  9. Verify that billing is enabled for your Google Cloud project.

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

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    Enable the APIs

  11. Install the Google Cloud CLI.

    Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  12. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  13. Toinitialize the gcloud CLI, run the following command:

    gcloudinit
  14. Run the following command to install thecbt CLI:
    gcloud components install cbt

Plan your configuration:

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

  2. Optional: If you want to usecustomer-managed encryption keys (CMEK) instead of the default Google-managed encryption, have yourCMEK key ID readybefore you create your new instance. You are not able toadd CMEK protection to an instance after it has been created, and you cannotmodify or replace the CMEK key after the instance is created. For moreinformation, seeUse customer-managed encryption keys (CMEK).

Create an instance

To create a Bigtable instance:

Console

  1. In the Google Cloud console, go to theCreate instance page.

    Go to Create instance

  2. Enter a name for the instance.

    The Google 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. ClickContinue.

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

  6. ClickContinue.

  7. Enter a cluster ID for the first cluster.

    The cluster ID is a permanent identifier for the cluster.

  8. Choose theregion and zone where the first clusterwill run.

  9. Optional: To configure the cluster to always scale in increments oftwo nodes, selectEnable 2x node scaling. 2x node scaling is notavailable in all zones. For more information, seeNode scalingfactor.

  10. Choose a node scaling mode for the cluster. In most cases, you shouldchoose autoscaling. For scaling guidance, seeAutoscaling.

    1. ForManual node allocation, enter the number ofBigtable 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. ForAutoscaling, enter values for the following:
      • Minimum number of nodes
      • Maximum number of nodes
      • CPU utilization target
      • Storage utilization target
  11. Optional: To protect your instance with CMEK instead of the defaultGoogle-managed encryption, complete the following:

    1. ClickShow encryption options.
    2. SelectCloud KMS key.
    3. In theKey management type field, select one of the followingoptions:
      • If you want to automate creation of Cloud KMS keys, selectCloud KMS with Autokey, and then clickRequest a key. Amessage indicates when your key has been successfully created andis ready for use.
      • If you want to add a key manually, selectCloud KMS. Select orenter the resource name for theCMEK key that you wantto use for the cluster. You cannot add this later. If you areprompted to grant permission to the CMEK key's service account,clickGrant. Your user account must be granted theCloud KMS Admin role to complete this task. ClickSave.
  12. Optional: To enable replication now, complete the following additionalsteps:

    1. ClickShow advanced options.
    2. ClickAdd cluster, enter the settings for the cluster, andthen clickAdd. Repeat this step to create additional clusters inthe instance. You can also enable replication later byadding acluster.

    Eachzone in a region can contain onlyone cluster. If theAdd cluster button isdisabled, change the zone for your first cluster.

    To create an instance that has more than six clusters, first create aninstance that has six clusters, then add more clusters to the instance.

  13. ClickCreate to create the instance.

  14. Review the replication settings in the default app profile to see if they make sense for yourreplication use case. You might need toupdate the default appprofile orcreate customapp profiles.

gcloud

  1. Use thebigtable instances create command to createan instance:

    gcloudbigtableinstancescreateINSTANCE_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],\[node-scaling-factor=NODE_SCALING_FACTOR]

    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: Thezone 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 multipleclusters,repeat the--cluster-config flag for each cluster.

    Formanual node allocation, settingnodes in the--cluster-configflag is optional. If no value is set, Bigtable allocatesnodes to the cluster automatically based on your data footprint andoptimizes for 50% storage utilization. This automatic allocation ofnodes has a pricing impact. If you want to control the number of nodesin a cluster, replaceNODES with the number of nodes thatyou want in the cluster.Learn more about nodes.

    In most cases, chooseautoscaling instead of manual node allocation.For_autoscaling, provideautoscaling- options in the--cluster-config flag (autoscaling-storage-target is optional) anddon't usenodes. SeeAutoscaling forguidance on choosing the values for your autoscaling settings. Replacethe 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 forthe cluster. This value must be from 10 to 80.
    • AUTOSCALING_STORAGE_TARGET: (Optional) The storage utilizationtarget in GiB that Bigtable maintains by adding orremoving nodes.
    • KMS_KEY: The CMEK key for the cluster.

      TheKMS_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 inthe same region as its CMEK key. You canadd 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 touse 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 ifdifferent from the current project.

    • node-scaling-factor=NODE_SCALING_FACTOR: A flag thatenables2x node scaling.You can enable this feature with both manual scaling and autoscaling.Acceptable values arenode-scaling-factor-2x ornode-scaling-factor-1x.

    To view a list of Bigtable zones that aren't availablefor 2x node scaling, seeNode scaling factorlimitations.

  2. Review the replication settings in the default app profile to see if they make sense for yourreplication use case. You might need toupdate the default appprofile orcreate customapp profiles.

cbt

Note: You can't create CMEK-protected resources or configureautoscaling using thecbt CLI. You also can't enable 2x nodescaling with thecbt CLI.
  1. Start by creating an instance with a single cluster. Use thecreateinstance command to create aninstance:

    cbt createinstanceINSTANCE_ID \DISPLAY_NAME \CLUSTER_ID \CLUSTER_ZONE \CLUSTER_NUM_NODES \CLUSTER_STORAGE_TYPE

    Provide the following:

  2. To enable replication, use thecreatecluster command to add a cluster:

    cbt -instance=INSTANCE_ID \createclusterCLUSTER_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: Thezone where the cluster runs.

      Eachzone in a region can contain onlyone cluster. For example, if an instance has a cluster inus-east1-b, you can add a clusterin a different zone in the same region, such asus-east1-c, or a zone in a separateregion, such aseurope-west2-a.

    • NUM_NODES: This field is optional. If no value is set, Bigtable automaticallyallocates nodes based on your data footprint and optimizes for 50% storageutilization. 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 areexceptions.Learn about nodesand replication.

    • STORAGE_TYPE: The type of storage to use for the cluster. Each cluster in an instance must use the same storagetype. Accepts the valuesSSD andHDD.

  3. (Optional)Review the replication settings in the default app profile to see if they make sense for yourreplication use case. You might need toupdate the default appprofile orcreate customapp profiles.

C++

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

namespacecbta=::google::cloud::bigtable_admin;using::google::cloud::future;using::google::cloud::Location;using::google::cloud::Project;using::google::cloud::StatusOr;[](cbta::BigtableInstanceAdminClientinstance_admin,std::stringconst&project_id,std::stringconst&instance_id,std::stringconst&zone){autoconstproject=Project(project_id);std::stringproject_name=project.FullName();std::stringcluster_id=instance_id+"-c1";google::bigtable::admin::v2::Instancein;in.set_type(google::bigtable::admin::v2::Instance::PRODUCTION);in.set_display_name("Put description here");google::bigtable::admin::v2::Clustercluster;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;autoinstance=instance_future.get();if(!instance)throwstd::move(instance).status();std::cout <<"DONE, details=" <<instance->DebugString() <<"\n";}

C#

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

// 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.stringinstanceId=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/locationsstringzone1="us-east1-b";// The instance to create.InstancemyInstance=newInstance{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.ClustermyCluster1=newCluster{// 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=newLocationName(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).CreateInstanceRequestrequest=newCreateInstanceRequest{ParentAsProjectName=newProjectName(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 completeOperation<Instance,CreateInstanceMetadata>completedResponse=createInstanceResponse.PollUntilCompleted();}catch(Exceptionex){Console.WriteLine($"Exception while creating {displayName} instance");Console.WriteLine(ex.Message);}

Java

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

// Creates a Production Instance with the ID "ssd-instance",// cluster id "ssd-cluster", 3 nodes and location "us-central1-f".CreateInstanceRequestcreateInstanceRequest=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{Instanceinstance=adminClient.createInstance(createInstanceRequest);System.out.printf("PRODUCTION type instance %s created successfully%n",instance.getId());}catch(Exceptione){System.err.println("Failed to create instance: "+e.getMessage());throwe;}

Node.js

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

// Creates a Production Instance with the ID "ssd-instance"// with cluster id "ssd-cluster", 3 nodes and location us-central1-fconst{BigtableInstanceAdminClient}=require('@google-cloud/bigtable').v2;constinstanceAdminClient=newBigtableInstanceAdminClient();constprojectId=awaitinstanceAdminClient.getProjectId();constinstanceOptions={parent:`projects/${projectId}`,instanceId:instanceID,instance:{displayName:instanceID,labels:{'prod-label':'prod-label'},type:'PRODUCTION',},clusters:{[clusterID]:{location:`projects/${projectId}/locations/us-central1-f`,serveNodes:3,defaultStorageType:'SSD',},},};// Create production instance with given optionsconst[prodInstance,operation]=awaitinstanceAdminClient.createInstance(instanceOptions);awaitoperation.promise();console.log(`Created Instance:${prodInstance.name}`);

PHP

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

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

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

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

Ruby

To learn how to install and use the client library for Bigtable, seeBigtable client libraries.

To authenticate to Bigtable, set up Application Default Credentials. For more information, seeSet up authentication for a local development environment.

# 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.addcluster_id,cluster_location,nodes:3,storage_type::SSDendjob.wait_until_done!instance=job.instanceputs"Created Instance:#{instance.instance_id}"

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-15 UTC.