Getting Started with Bigtable Instance Administrative Operations

This example is a very simple "Instance Admin" application, which illustrates how to:

  • Create a production instance.
  • List the existing instances.
  • Get the metadata for an instance.
  • List all the clusters in an instance.
  • Delete an instance.

Run the example

This example uses the Cloud Bigtable C++ Client Library to communicate with Cloud Bigtable.

To run the example program, follow the instructions for the example on GitHub.

Include the Necessary Headers

The example uses the following headers:

#include "google/cloud/bigtable/admin/bigtable_instance_admin_client.h"

Define aliases

To make the example less verbose we define some aliases:

 namespace cbt = ::google::cloud::bigtable; namespace cbta = ::google::cloud::bigtable_admin; using ::google::cloud::future; using ::google::cloud::Location; using ::google::cloud::Project; using ::google::cloud::Status; using ::google::cloud::StatusOr;

Connect to the Cloud Bigtable Instance Admin Endpoint.

Create an object of type bigtable_admin::BigtableInstanceAdminClient to obtain information about Instances, Clusters, Application Profiles, and to change the IAM permissions in a Cloud Bigtable instance:

 auto instance_admin = cbta::BigtableInstanceAdminClient( cbta::MakeBigtableInstanceAdminConnection());
See Also

https://cloud.google.com/bigtable/docs/instances-clusters-nodes for more information about Cloud Bigtable instances, clusters, and nodes.

See Also

https://cloud.google.com/bigtable/docs/app-profiles for more information about Cloud Bigtable application profiles.

See Also

https://cloud.google.com/bigtable/docs/access-control for more information about access controls via IAM permissions on Cloud Bigtable.

Check if an Instance already exists

 std::cout << "\nCheck Instance exists:\n"; auto const project = Project(project_id); std::string const project_name = project.FullName(); StatusOr<google::bigtable::admin::v2::ListInstancesResponse> instances = instance_admin.ListInstances(project_name); if (!instances) throw std::move(instances).status(); if (!instances->failed_locations().empty()) { std::cerr << "The service tells us it has no information about these locations:"; for (auto const& failed_location : instances->failed_locations()) { std::cerr << " " << failed_location; } std::cerr << ". Continuing anyway\n"; } std::string const instance_name = cbt::InstanceName(project_id, instance_id); auto is_instance = [&instance_name](google::bigtable::admin::v2::Instance const& i) { return i.name() == instance_name; }; auto const& ins = instances->instances(); auto instance_exists = std::find_if(ins.begin(), ins.end(), is_instance) != ins.end(); std::cout << "The instance " << instance_id << (instance_exists ? " already exists" : " does not exist") << "\n";
See Also

BigtableInstanceAdminClient::GetInstance() for another operation to query if an instance exists.

Create a Production Instance

Use BigtableInstanceAdminClient::CreateInstance() to create a new instance:

 std::cout << "\nCreating a PRODUCTION Instance: "; // production instance needs at least 3 nodes google::bigtable::admin::v2::Cluster c; c.set_location(Location(project, zone).FullName()); c.set_serve_nodes(3); c.set_default_storage_type(google::bigtable::admin::v2::HDD); google::bigtable::admin::v2::Instance in; in.set_display_name("Sample Instance"); in.set_type(google::bigtable::admin::v2::Instance::PRODUCTION); future<void> creation_done = instance_admin .CreateInstance(project_name, instance_id, std::move(in), {{cluster_id, std::move(c)}}) .then( [instance_id]( future<StatusOr<google::bigtable::admin::v2::Instance>> f) { auto instance = f.get(); if (!instance) { std::cerr << "Could not create instance " << instance_id << "\n"; throw std::move(instance).status(); } std::cout << "Successfully created instance: " << instance->DebugString() << "\n"; }); // Note how this blocks until the instance is created. In production code // you may want to perform this task asynchronously. creation_done.get(); std::cout << "DONE\n";

List Instances in a Project

Use BigtableInstanceAdminClient::ListInstances() to list all the instances in the project:

 std::cout << "\nListing Instances:\n"; instances = instance_admin.ListInstances(project_name); if (!instances) throw std::move(instances).status(); if (!instances->failed_locations().empty()) { std::cerr << "The service tells us it has no information about these locations:"; for (auto const& failed_location : instances->failed_locations()) { std::cerr << " " << failed_location; } std::cerr << ". Continuing anyway\n"; } for (auto const& instance : instances->instances()) { std::cout << " " << instance.name() << "\n"; } std::cout << "DONE\n";
See Also

The gRPC API documentation for ListInstances has more details on when failed_locations might be populated.

Get an Instance Metadata

Use BigtableInstanceAdminClient::GetInstance() to retrieve the metadata of an instance:

 std::cout << "\nGet Instance:\n"; auto instance = instance_admin.GetInstance(instance_name); if (!instance) throw std::move(instance).status(); std::cout << "Instance details :\n" << instance->DebugString() << "\n";

List clusters in an Instance

Use BigtableInstanceAdminClient::ListClusters() to list all the clusters in an instance (or all the clusters in a project):

 std::cout << "\nListing Clusters:\n"; StatusOr<google::bigtable::admin::v2::ListClustersResponse> cluster_list = instance_admin.ListClusters(instance_name); if (!cluster_list) throw std::move(cluster_list).status(); if (!cluster_list->failed_locations().empty()) { std::cout << "The Cloud Bigtable service reports that the following " "locations are temporarily unavailable and no information " "about clusters in these locations can be obtained:\n"; for (auto const& failed_location : cluster_list->failed_locations()) { std::cout << failed_location << "\n"; } } std::cout << "Cluster Name List:\n"; for (auto const& cluster : cluster_list->clusters()) { std::cout << "Cluster Name: " << cluster.name() << "\n"; } std::cout << "DONE\n";
See Also

The bigtable_admin::BigtableInstanceAdminClient class also has functions to create, update, delete, and retrieve the metadata of a Cluster.

See Also

The gRPC API documentation for ListClusters has more details on when failed_locations might be populated.

Delete an instance

Finally, use BigtableInstanceAdminClient::DeleteInstance() to delete an instance:

 std::cout << "Deleting instance " << instance_id << "\n"; Status delete_status = instance_admin.DeleteInstance(instance_name); if (!delete_status.ok()) throw std::runtime_error(delete_status.message()); std::cout << "DONE\n";

Put it all together

Here is the full example

 #include "google/cloud/bigtable/admin/bigtable_instance_admin_client.h" #include "google/cloud/bigtable/examples/bigtable_examples_common.h" #include "google/cloud/bigtable/resource_names.h" #include "google/cloud/bigtable/testing/cleanup_stale_resources.h" #include "google/cloud/bigtable/testing/random_names.h" #include "google/cloud/internal/getenv.h" #include "google/cloud/internal/random.h" #include "google/cloud/location.h" #include "google/cloud/log.h" #include "google/cloud/project.h" #include <algorithm> #include <iostream> namespace { using ::google::cloud::bigtable::examples::Usage; void BigtableHelloInstance(std::vector<std::string> const& argv) { if (argv.size() != 4) { throw Usage{ "hello-instance <project-id> <instance-id> <cluster-id> <zone>"}; } std::string const& project_id = argv[0]; std::string const& instance_id = argv[1]; std::string const& cluster_id = argv[2]; std::string const& zone = argv[3]; namespace cbt = ::google::cloud::bigtable; namespace cbta = ::google::cloud::bigtable_admin; using ::google::cloud::future; using ::google::cloud::Location; using ::google::cloud::Project; using ::google::cloud::Status; using ::google::cloud::StatusOr; // Connect to the Cloud Bigtable admin endpoint. auto instance_admin = cbta::BigtableInstanceAdminClient( cbta::MakeBigtableInstanceAdminConnection()); std::cout << "\nCheck Instance exists:\n"; auto const project = Project(project_id); std::string const project_name = project.FullName(); StatusOr<google::bigtable::admin::v2::ListInstancesResponse> instances = instance_admin.ListInstances(project_name); if (!instances) throw std::move(instances).status(); if (!instances->failed_locations().empty()) { std::cerr << "The service tells us it has no information about these locations:"; for (auto const& failed_location : instances->failed_locations()) { std::cerr << " " << failed_location; } std::cerr << ". Continuing anyway\n"; } std::string const instance_name = cbt::InstanceName(project_id, instance_id); auto is_instance = [&instance_name](google::bigtable::admin::v2::Instance const& i) { return i.name() == instance_name; }; auto const& ins = instances->instances(); auto instance_exists = std::find_if(ins.begin(), ins.end(), is_instance) != ins.end(); std::cout << "The instance " << instance_id << (instance_exists ? " already exists" : " does not exist") << "\n"; // Create instance if it does not exist if (!instance_exists) { std::cout << "\nCreating a PRODUCTION Instance: "; // production instance needs at least 3 nodes google::bigtable::admin::v2::Cluster c; c.set_location(Location(project, zone).FullName()); c.set_serve_nodes(3); c.set_default_storage_type(google::bigtable::admin::v2::HDD); google::bigtable::admin::v2::Instance in; in.set_display_name("Sample Instance"); in.set_type(google::bigtable::admin::v2::Instance::PRODUCTION); future<void> creation_done = instance_admin .CreateInstance(project_name, instance_id, std::move(in), {{cluster_id, std::move(c)}}) .then( [instance_id]( future<StatusOr<google::bigtable::admin::v2::Instance>> f) { auto instance = f.get(); if (!instance) { std::cerr << "Could not create instance " << instance_id << "\n"; throw std::move(instance).status(); } std::cout << "Successfully created instance: " << instance->DebugString() << "\n"; }); // Note how this blocks until the instance is created. In production code // you may want to perform this task asynchronously. creation_done.get(); std::cout << "DONE\n"; } std::cout << "\nListing Instances:\n"; instances = instance_admin.ListInstances(project_name); if (!instances) throw std::move(instances).status(); if (!instances->failed_locations().empty()) { std::cerr << "The service tells us it has no information about these locations:"; for (auto const& failed_location : instances->failed_locations()) { std::cerr << " " << failed_location; } std::cerr << ". Continuing anyway\n"; } for (auto const& instance : instances->instances()) { std::cout << " " << instance.name() << "\n"; } std::cout << "DONE\n"; std::cout << "\nGet Instance:\n"; auto instance = instance_admin.GetInstance(instance_name); if (!instance) throw std::move(instance).status(); std::cout << "Instance details :\n" << instance->DebugString() << "\n"; std::cout << "\nListing Clusters:\n"; StatusOr<google::bigtable::admin::v2::ListClustersResponse> cluster_list = instance_admin.ListClusters(instance_name); if (!cluster_list) throw std::move(cluster_list).status(); if (!cluster_list->failed_locations().empty()) { std::cout << "The Cloud Bigtable service reports that the following " "locations are temporarily unavailable and no information " "about clusters in these locations can be obtained:\n"; for (auto const& failed_location : cluster_list->failed_locations()) { std::cout << failed_location << "\n"; } } std::cout << "Cluster Name List:\n"; for (auto const& cluster : cluster_list->clusters()) { std::cout << "Cluster Name: " << cluster.name() << "\n"; } std::cout << "DONE\n"; std::cout << "Deleting instance " << instance_id << "\n"; Status delete_status = instance_admin.DeleteInstance(instance_name); if (!delete_status.ok()) throw std::runtime_error(delete_status.message()); std::cout << "DONE\n"; } void RunAll(std::vector<std::string> const& argv) { namespace examples = ::google::cloud::bigtable::examples; namespace cbta = ::google::cloud::bigtable_admin; if (!argv.empty()) throw Usage{"auto"}; if (!examples::RunAdminIntegrationTests()) return; examples::CheckEnvironmentVariablesAreSet({ "GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_CPP_BIGTABLE_TEST_ZONE_A", }); auto const project_id = google::cloud::internal::GetEnv("GOOGLE_CLOUD_PROJECT").value(); auto const zone_a = google::cloud::internal::GetEnv("GOOGLE_CLOUD_CPP_BIGTABLE_TEST_ZONE_A") .value(); auto generator = google::cloud::internal::DefaultPRNG(std::random_device{}()); google::cloud::bigtable::testing::CleanupStaleInstances( cbta::MakeBigtableInstanceAdminConnection(), project_id); auto const instance_id = google::cloud::bigtable::testing::RandomInstanceId(generator); auto const cluster_id = instance_id + "-c1"; std::cout << "\nRunning the BigtableHelloInstance() example" << std::endl; BigtableHelloInstance({project_id, instance_id, cluster_id, zone_a}); } } // namespace int main(int argc, char* argv[]) try { google::cloud::bigtable::examples::Example example({ {"auto", RunAll}, {"hello-instance", BigtableHelloInstance}, }); return example.Run(argc, argv); } catch (std::exception const& ex) { std::cerr << ex.what() << "\n"; ::google::cloud::LogSink::Instance().Flush(); return 1; }