Class InstanceAdmin (2.17.0)

In addition, the [main page](xref:index) contains examples using [`StatusOr`](xref:classgoogle_1_1cloud_1_1StatusOr)`<T>` to handle errors.



###### Retry, Backoff, and Idempotency Policies

The library automatically retries requests that fail with transient errors, and uses [truncated exponential backoff](https://cloud.google.com/storage/docs/exponential-backoff) to backoff between retries. The default policies are to continue retrying for up to 10 minutes. On each transient failure the backoff period is doubled, starting with an initial backoff of 100 milliseconds. The backoff period growth is truncated at 60 seconds. The default idempotency policy is to only retry idempotent operations. Note that most operations that change state are **not** idempotent.
The application can override these policies when constructing objects of this class. The documentation for the constructors show examples of this in action.



###### See Also

[https://cloud.google.com/bigtable/](https://cloud.google.com/bigtable/) for an overview of Cloud Bigtable.

###### See Also

[https://cloud.google.com/bigtable/docs/overview](https://cloud.google.com/bigtable/docs/overview) for an overview of the Cloud Bigtable data model.

###### See Also

[https://cloud.google.com/bigtable/docs/instances-clusters-nodes](https://cloud.google.com/bigtable/docs/instances-clusters-nodes) for an introduction of the main APIs into Cloud Bigtable.

###### See Also

[https://cloud.google.com/bigtable/docs/reference/service-apis-overview](https://cloud.google.com/bigtable/docs/reference/service-apis-overview) for an overview of the underlying Cloud Bigtable API.

###### See Also

[`google::cloud::StatusOr`](xref:classgoogle_1_1cloud_1_1StatusOr) for a description of the error reporting class used by this library.

###### See Also

[`LimitedTimeRetryPolicy`](xref:classgoogle_1_1cloud_1_1bigtable_1_1LimitedTimeRetryPolicy) and [`LimitedErrorCountRetryPolicy`](xref:classgoogle_1_1cloud_1_1bigtable_1_1LimitedErrorCountRetryPolicy) for alternative retry policies.

###### See Also

[`ExponentialBackoffPolicy`](xref:classgoogle_1_1cloud_1_1bigtable_1_1ExponentialBackoffPolicy) to configure different parameters for the exponential backoff policy.

###### See Also

[`SafeIdempotentMutationPolicy`](xref:classgoogle_1_1cloud_1_1bigtable_1_1SafeIdempotentMutationPolicy) and [`AlwaysRetryMutationPolicy`](xref:classgoogle_1_1cloud_1_1bigtable_1_1AlwaysRetryMutationPolicy) for alternative idempotency policies. 

  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::future;
  using ::google::cloud::Location;
  using ::google::cloud::Project;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& zone) {
    auto const project = Project(project_id);
    std::string project_name = project.FullName();
    std::string cluster_id = instance_id + "-c1";

    google::bigtable::admin::v2::Instance in;
    in.set_type(google::bigtable::admin::v2::Instance::PRODUCTION);
    in.set_display_name("Put description here");

    google::bigtable::admin::v2::Cluster cluster;
    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;
    auto instance = instance_future.get();
    if (!instance) throw std::move(instance).status();
    std::cout << "DONE, details=" << instance->DebugString() << "\n";
  }

  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::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& cluster_id, std::string const& zone) {
    auto const project = Project(project_id);
    std::string instance_name = cbt::InstanceName(project_id, instance_id);

    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);

    future<StatusOr<google::bigtable::admin::v2::Cluster>> cluster_future =
        instance_admin.CreateCluster(instance_name, cluster_id, std::move(c));

    // Applications can wait asynchronously, in this example we just block.
    auto cluster = cluster_future.get();
    if (!cluster) throw std::move(cluster).status();
    std::cout << "Successfully created cluster " << cluster->name() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::future;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::bigtable::admin::v2::Instance> instance =
        instance_admin.GetInstance(instance_name);
    if (!instance) throw std::move(instance).status();
    // Modify the instance and prepare the mask with the modified field
    instance->set_display_name("Modified Display Name");
    google::protobuf::FieldMask mask;
    mask.add_paths("display_name");

    future<StatusOr<google::bigtable::admin::v2::Instance>> instance_future =
        instance_admin.PartialUpdateInstance(std::move(*instance),
                                             std::move(mask));
    instance_future
        .then([](future<StatusOr<google::bigtable::admin::v2::Instance>> f) {
          auto updated_instance = f.get();
          if (!updated_instance) {
            throw std::move(updated_instance).status();
          }
          std::cout << "UpdateInstance details : "
                    << updated_instance->DebugString() << "\n";
        })
        .get();  // block until done to simplify example
  }

  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::Project;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id) {
    std::string project_name = Project(project_id).FullName();
    StatusOr<google::bigtable::admin::v2::ListInstancesResponse> instances =
        instance_admin.ListInstances(project_name);
    if (!instances) throw std::move(instances).status();
    for (auto const& instance : instances->instances()) {
      std::cout << instance.name() << "\n";
    }
    if (!instances->failed_locations().empty()) {
      std::cout << "The Cloud Bigtable service reports that the following "
                   "locations are temporarily unavailable and no information "
                   "about instances in these locations can be obtained:\n";
      for (auto const& failed_location : instances->failed_locations()) {
        std::cout << failed_location << "\n";
      }
    }
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::bigtable::admin::v2::Instance> instance =
        instance_admin.GetInstance(instance_name);
    if (!instance) throw std::move(instance).status();
    std::cout << "GetInstance details : " << instance->DebugString() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::Status;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    Status status = instance_admin.DeleteInstance(instance_name);
    if (!status.ok()) throw std::runtime_error(status.message());
    std::cout << "Successfully deleted the instance " << instance_id << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::bigtable::admin::v2::ListClustersResponse> clusters =
        instance_admin.ListClusters(instance_name);
    if (!clusters) throw std::move(clusters).status();
    std::cout << "Cluster Name List\n";
    for (auto const& cluster : clusters->clusters()) {
      std::cout << "Cluster Name:" << cluster.name() << "\n";
    }
    if (!clusters->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 : clusters->failed_locations()) {
        std::cout << failed_location << "\n";
      }
    }
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::bigtable::admin::v2::ListClustersResponse> clusters =
        instance_admin.ListClusters(instance_name);
    if (!clusters) throw std::move(clusters).status();
    std::cout << "Cluster Name List\n";
    for (auto const& cluster : clusters->clusters()) {
      std::cout << "Cluster Name:" << cluster.name() << "\n";
    }
    if (!clusters->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 : clusters->failed_locations()) {
        std::cout << failed_location << "\n";
      }
    }
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& cluster_id) {
    std::string cluster_name =
        cbt::ClusterName(project_id, instance_id, cluster_id);
    // GetCluster first and then modify it.
    StatusOr<google::bigtable::admin::v2::Cluster> cluster =
        instance_admin.GetCluster(cluster_name);
    if (!cluster) throw std::move(cluster).status();

    // The state cannot be sent on updates, so clear it first.
    cluster->clear_state();
    // Set the desired cluster configuration.
    cluster->set_serve_nodes(4);

    auto modified_cluster =
        instance_admin.UpdateCluster(std::move(*cluster)).get();
    if (!modified_cluster) {
      throw std::move(modified_cluster).status();
    }
    std::cout << "cluster details : " << cluster->DebugString() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::Status;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& cluster_id) {
    std::string cluster_name =
        cbt::ClusterName(project_id, instance_id, cluster_id);
    Status status = instance_admin.DeleteCluster(cluster_name);
    if (!status.ok()) throw std::runtime_error(status.message());
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& cluster_id) {
    std::string cluster_name =
        cbt::ClusterName(project_id, instance_id, cluster_id);
    StatusOr<google::bigtable::admin::v2::Cluster> cluster =
        instance_admin.GetCluster(cluster_name);
    if (!cluster) throw std::move(cluster).status();
    std::cout << "GetCluster details : " << cluster->DebugString() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);

    google::bigtable::admin::v2::AppProfile ap;
    ap.mutable_multi_cluster_routing_use_any()->Clear();

    StatusOr<google::bigtable::admin::v2::AppProfile> profile =
        instance_admin.CreateAppProfile(instance_name, profile_id,
                                        std::move(ap));
    if (!profile) throw std::move(profile).status();
    std::cout << "New profile created with name=" << profile->name() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id, std::string const& cluster_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);

    google::bigtable::admin::v2::AppProfile ap;
    ap.mutable_single_cluster_routing()->set_cluster_id(cluster_id);

    StatusOr<google::bigtable::admin::v2::AppProfile> profile =
        instance_admin.CreateAppProfile(instance_name, profile_id,
                                        std::move(ap));
    if (!profile) throw std::move(profile).status();
    std::cout << "New profile created with name=" << profile->name() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id) {
    std::string profile_name =
        cbt::AppProfileName(project_id, instance_id, profile_id);
    StatusOr<google::bigtable::admin::v2::AppProfile> profile =
        instance_admin.GetAppProfile(profile_name);
    if (!profile) throw std::move(profile).status();
    std::cout << "Application Profile details=" << profile->DebugString()
              << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::future;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id, std::string const& description) {
    std::string profile_name =
        cbt::AppProfileName(project_id, instance_id, profile_id);

    google::bigtable::admin::v2::AppProfile profile;
    profile.set_name(profile_name);
    profile.set_description(description);

    google::protobuf::FieldMask mask;
    mask.add_paths("description");

    future<StatusOr<google::bigtable::admin::v2::AppProfile>> profile_future =
        instance_admin.UpdateAppProfile(std::move(profile), std::move(mask));
    auto modified_profile = profile_future.get();
    if (!modified_profile) throw std::move(modified_profile).status();
    std::cout << "Updated AppProfile: " << modified_profile->DebugString()
              << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::future;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id) {
    std::string profile_name =
        cbt::AppProfileName(project_id, instance_id, profile_id);

    google::bigtable::admin::v2::UpdateAppProfileRequest req;
    req.mutable_app_profile()->set_name(profile_name);
    req.mutable_app_profile()->mutable_multi_cluster_routing_use_any()->Clear();
    req.mutable_update_mask()->add_paths("multi_cluster_routing_use_any");
    req.set_ignore_warnings(true);

    future<StatusOr<google::bigtable::admin::v2::AppProfile>> profile_future =
        instance_admin.UpdateAppProfile(std::move(req));
    auto modified_profile = profile_future.get();
    if (!modified_profile) throw std::move(modified_profile).status();
    std::cout << "Updated AppProfile: " << modified_profile->DebugString()
              << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::future;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id, std::string const& cluster_id) {
    std::string profile_name =
        cbt::AppProfileName(project_id, instance_id, profile_id);

    google::bigtable::admin::v2::UpdateAppProfileRequest req;
    req.mutable_app_profile()->set_name(profile_name);
    req.mutable_app_profile()->mutable_single_cluster_routing()->set_cluster_id(
        cluster_id);
    req.mutable_update_mask()->add_paths("single_cluster_routing");
    req.set_ignore_warnings(true);

    future<StatusOr<google::bigtable::admin::v2::AppProfile>> profile_future =
        instance_admin.UpdateAppProfile(std::move(req));
    auto modified_profile = profile_future.get();
    if (!modified_profile) throw std::move(modified_profile).status();
    std::cout << "Updated AppProfile: " << modified_profile->DebugString()
              << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StreamRange;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StreamRange<google::bigtable::admin::v2::AppProfile> profiles =
        instance_admin.ListAppProfiles(instance_name);
    std::cout << "The " << instance_id << " instance has "
              << std::distance(profiles.begin(), profiles.end())
              << " application profiles\n";
    for (auto& profile : profiles) {
      if (!profile) throw std::move(profile).status();
      std::cout << profile->DebugString() << "\n";
    }
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::Status;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& profile_id, bool ignore_warnings) {
    std::string profile_name =
        cbt::AppProfileName(project_id, instance_id, profile_id);

    google::bigtable::admin::v2::DeleteAppProfileRequest req;
    req.set_name(profile_name);
    req.set_ignore_warnings(ignore_warnings);

    Status status = instance_admin.DeleteAppProfile(std::move(req));
    if (!status.ok()) throw std::runtime_error(status.message());
    std::cout << "Application Profile deleted\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::iam::v1::Policy> policy =
        instance_admin.GetIamPolicy(instance_name);
    if (!policy) throw std::move(policy).status();
    std::cout << "The IAM Policy for " << instance_id << " is\n"
              << policy->DebugString() << "\n";
  }

  namespace cbt = ::google::cloud::bigtable;
  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& project_id, std::string const& instance_id,
     std::string const& role, std::string const& member) {
    std::string instance_name = cbt::InstanceName(project_id, instance_id);
    StatusOr<google::iam::v1::Policy> current =
        instance_admin.GetIamPolicy(instance_name);
    if (!current) throw std::move(current).status();
    // This example adds the member to all existing bindings for that role. If
    // there are no such bindings, it adds a new one. This might not be what the
    // user wants, e.g. in case of conditional bindings.
    size_t num_added = 0;
    for (auto& binding : *current->mutable_bindings()) {
      if (binding.role() == role) {
        binding.add_members(member);
        ++num_added;
      }
    }
    if (num_added == 0) {
      *current->add_bindings() = cbt::IamBinding(role, {member});
    }
    StatusOr<google::iam::v1::Policy> policy =
        instance_admin.SetIamPolicy(instance_name, *current);
    if (!policy) throw std::move(policy).status();
    std::cout << "The IAM Policy for " << instance_id << " is\n"
              << policy->DebugString() << "\n";
  }

  namespace cbta = ::google::cloud::bigtable_admin;
  using ::google::cloud::StatusOr;
  [](cbta::BigtableInstanceAdminClient instance_admin,
     std::string const& resource_name,
     std::vector<std::string> const& permissions) {
    auto result = instance_admin.TestIamPermissions(resource_name, permissions);
    if (!result) throw std::move(result).status();
    std::cout << "The current user has the following permissions [";
    std::cout << absl::StrJoin(result->permissions(), ", ");
    std::cout << "]\n";
  }