Package com.google.cloud.bigtable.admin.v2

Class BigtableInstanceAdminClient

  • All Implemented Interfaces:
    AutoCloseable
    public final class BigtableInstanceAdminClient
extends Object
implements AutoCloseable
    Client for creating, configuring and deleting Cloud Bigtable instances, app profiles, and clusters.

    See the individual methods for example code. 

    
 // One instance per application.
 BigtableInstanceAdminClient client =  BigtableInstanceAdminClient.create("my-project");
 CreateInstanceRequest request = CreateInstanceRequest.of("my-instance")
   .addCluster("my-cluster", "us-east1-c", 3, StorageType.SSD);

 Instance instance = client.createInstance(request);

 // Cleanup during application shutdown.
 client.close();

    Creating a new client is a very expensive operation and should only be done once and shared in an application. However, close() needs to be called on the client object to clean up resources such as threads during application shutdown.

    This class can be customized by passing in a custom instance of BigtableInstanceAdminSettings to create(). For example:

    To customize credentials: 

    
 BigtableInstanceAdminSettings settings = BigtableInstanceAdminSettings.newBuilder()
   .setProjectId("my-project")
   .setCredentialsProvider(FixedCredentialsProvider.create(myCredentials))
   .build();

 BigtableInstanceAdminClient client = BigtableInstanceAdminClient.create(settings);
    To customize the endpoint: 
    
 BigtableInstanceAdminSettings.Builder settingsBuilder = BigtableInstanceAdminSettings.newBuilder()
   .setProjectId("my-project");

 settingsBuilder.stubSettings()
   .setEndpoint(myEndpoint);

 BigtableInstanceAdminClient client = BigtableInstanceAdminClient.create(settingsBuilder.build());

    • Method Detail

      • create

        public static BigtableInstanceAdminClient create​(@Nonnull
                                                 String projectId,
                                                 @Nonnull
                                                 com.google.cloud.bigtable.admin.v2.stub.BigtableInstanceAdminStub stub)
        Constructs an instance of BigtableInstanceAdminClient with the given project ID and stub.

      • getProjectId

        public String getProjectId()
        Gets the project ID this client is associated with.

      • close

        public void close()
        Closes the client and frees all resources associated with it (like thread pools).
        Specified by:
        close in interface AutoCloseable

      • createInstance

        public Instance createInstance​(CreateInstanceRequest request)
        Creates a new instance and returns its representation.

        Sample code: 

        
 Instance instance = client.createInstance(
   CreateInstanceRequest.of("my-instance")
     .addCluster("my-cluster", "us-east1-c", 3, StorageType.SSD)
 );
        See Also:
        for details.

      • createInstanceAsync

        public com.google.api.core.ApiFuture<Instance> createInstanceAsync​(CreateInstanceRequest request)
        Asynchronously creates a new instance and returns its representation wrapped in a future.

        Sample code: 

        
 ApiFuture<Instance> instanceFuture = client.createInstanceAsync(
   CreateInstanceRequest.of("my-instance")
     .addCluster("my-cluster", "us-east1-c", 3, StorageType.SSD)
 );

 Instance instance = instanceFuture.get();
        See Also:
        for details.

      • updateInstance

        public Instance updateInstance​(UpdateInstanceRequest request)
        Updates a new instance and returns its representation.

        Sample code: 

        
 Instance instance = client.updateInstance(
   UpdateInstanceRequest.of("my-instance")
     .setProductionType()
 );
        See Also:
        for details.

      • updateInstanceAsync

        public com.google.api.core.ApiFuture<Instance> updateInstanceAsync​(UpdateInstanceRequest request)
        Asynchronously updates a new instance and returns its representation wrapped in a future.

        Sample code: 

        
 ApiFuture<Instance> instanceFuture = client.updateInstanceAsync(
   UpdateInstanceRequest.of("my-instance")
     .setProductionType()
 );

 Instance instance = instanceFuture.get();
        See Also:
        for details.

      • getInstance

        public Instance getInstance​(String id)
        Get the instance representation by ID.

        Sample code: 

        
 Instance instance = client.getInstance("my-instance");

      • getInstanceAsync

        public com.google.api.core.ApiFuture<Instance> getInstanceAsync​(String instanceId)
        Asynchronously gets the instance representation by ID wrapped in a future.

        Sample code: 

        
 ApiFuture<Instance> instanceFuture = client.getInstanceAsync("my-instance");
 Instance instance = instanceFuture.get();

      • listInstances

        public List<Instance> listInstances()
        Lists all of the instances in the current project.

        This method will throw a PartialListInstancesException when any zone is unavailable. If a partial list is OK, the exception can be caught and inspected.

        Sample code: 

        
 try {
   List<Instance> instances = client.listInstances();
 } catch (PartialListInstancesException e) {
   System.out.println("The following zones are unavailable: " + e.getUnavailableZones());
   System.out.println("But the following instances are reachable: " + e.getInstances());
 }

      • listInstancesAsync

        public com.google.api.core.ApiFuture<List<Instance>> listInstancesAsync()
        Asynchronously lists all of the instances in the current project.

        This method will throw a PartialListInstancesException when any zone is unavailable. If a partial list is OK, the exception can be caught and inspected.

        Sample code: 

        
 ApiFuture<Instance> instancesFuture = client.listInstancesAsync();

 ApiFutures.addCallback(instancesFuture, new ApiFutureCallback<List<Instance>>() {
   public void onFailure(Throwable t) {
     if (t instanceof PartialListInstancesException) {
       PartialListInstancesException partialError = (PartialListInstancesException)t;
       System.out.println("The following zones are unavailable: " + partialError.getUnavailableZones());
       System.out.println("But the following instances are reachable: " + partialError.getInstances());
     } else {
       t.printStackTrace();
     }
   }

   public void onSuccess(List<Instance> result) {
     System.out.println("Found a complete set of instances: " + result);
   }
 }, MoreExecutors.directExecutor());

      • deleteInstance

        public void deleteInstance​(String instanceId)
        Deletes the specified instance.

        Sample code: 

        
 client.deleteInstance("my-instance");

      • deleteInstanceAsync

        public com.google.api.core.ApiFuture<Void> deleteInstanceAsync​(String instanceId)
        Asynchronously deletes the specified instance.

        Sample code: 

        
 ApiFuture<Void> deleteFuture = client.deleteInstanceAsync("my-instance");
 deleteFuture.get();

      • exists

        public boolean exists​(String instanceId)
        Checks if the instance specified by the instance ID exists.

        Sample code: 

        
 if(client.exists("my-instance")) {
   System.out.println("Instance exists");
 }

      • existsAsync

        public com.google.api.core.ApiFuture<Boolean> existsAsync​(String instanceId)
        Asynchronously checks if the instance specified by the instance ID exists.

        Sample code: 

        
 ApiFuture<Boolean> found = client.existsAsync("my-instance");

 ApiFutures.addCallback(
  found,
  new ApiFutureCallback<Boolean>() {
    public void onSuccess(Boolean found) {
      if (found) {
        System.out.println("Instance exists");
      } else {
        System.out.println("Instance not found");
      }
    }

    public void onFailure(Throwable t) {
      t.printStackTrace();
    }
  },
  MoreExecutors.directExecutor()
 );

      • createCluster

        public Cluster createCluster​(CreateClusterRequest request)
        Creates a new cluster in the specified instance.

        Sample code: 

        
 Cluster cluster = client.createCluster(
   CreateClusterRequest.of("my-instance", "my-new-cluster")
     .setZone("us-east1-c")
     .setServeNodes(3)
     .setStorageType(StorageType.SSD)
 );

      • createClusterAsync

        public com.google.api.core.ApiFuture<Cluster> createClusterAsync​(CreateClusterRequest request)
        Asynchronously creates a new cluster in the specified instance.

        Sample code: 

        
 ApiFuture<Cluster> clusterFuture = client.createClusterAsync(
   CreateClusterRequest.of("my-instance", "my-new-cluster")
     .setZone("us-east1-c")
     .setServeNodes(3)
     .setStorageType(StorageType.SSD)
 );

 Cluster cluster = clusterFuture.get();

      • getCluster

        public Cluster getCluster​(String instanceId,
                          String clusterId)
        Gets the cluster representation by ID.

        Sample code: 

        
 Cluster cluster = client.getCluster("my-instance", "my-cluster");

      • getClusterAsync

        public com.google.api.core.ApiFuture<Cluster> getClusterAsync​(String instanceId,
                                                              String clusterId)
        Asynchronously gets the cluster representation by ID.

        Sample code: 

        
 ApiFuture<Cluster> clusterFuture = client.getClusterAsync("my-instance", "my-cluster");
 Cluster cluster = clusterFuture.get();

      • listClusters

        public List<Cluster> listClusters​(String instanceId)
        Lists all clusters in the specified instance.

        This method will throw a PartialListClustersException when any zone is unavailable. If a partial list is OK, the exception can be caught and inspected.

        Sample code: 

        
 try {
   List<Cluster> clusters = client.listClusters("my-instance");
 } catch (PartialListClustersException e) {
   System.out.println("The following zones are unavailable: " + e.getUnavailableZones());
   System.out.println("But the following clusters are reachable: " + e.getClusters())
 }

      • listClustersAsync

        public com.google.api.core.ApiFuture<List<Cluster>> listClustersAsync​(String instanceId)
        Asynchronously lists all clusters in the specified instance.

        This method will throw a PartialListClustersException when any zone is unavailable. If a partial list is OK, the exception can be caught and inspected.

        Sample code: 

        
 ApiFuture<Cluster> clustersFuture = client.listClustersAsync("my-instance");

 ApiFutures.addCallback(clustersFuture, new ApiFutureCallback<List<Cluster>>() {
   public void onFailure(Throwable t) {
     if (t instanceof PartialListClustersException) {
       PartialListClustersException partialError = (PartialListClustersException)t;
       System.out.println("The following zones are unavailable: " + partialError.getUnavailableZones());
       System.out.println("But the following clusters are reachable: " + partialError.getClusters());
     } else {
       t.printStackTrace();
     }
   }

   public void onSuccess(List<Cluster> result) {
     System.out.println("Found a complete set of instances: " + result);
   }
 }, MoreExecutors.directExecutor());

      • resizeCluster

        public Cluster resizeCluster​(String instanceId,
                             String clusterId,
                             int numServeNodes)
        Modifies the cluster's node count for manual scaling. If autoscaling is already enabled, manual scaling will be silently ignored. If you wish to disable autoscaling and enable manual scaling, please use disableClusterAutoscaling(String, String, int) instead. Please note that only clusters that belong to a production instance can be resized.

        Sample code: 

        
 Cluster cluster = client.resizeCluster("my-instance", "my-cluster", 30);

      • resizeClusterAsync

        public com.google.api.core.ApiFuture<Cluster> resizeClusterAsync​(String instanceId,
                                                                 String clusterId,
                                                                 int numServeNodes)
        Asynchronously modifies the cluster's node count for manual scaling. If autoscaling is already enabled, manual scaling will be silently ignored. If you wish to disable autoscaling and enable manual scaling, please use disableClusterAutoscaling(String, String, int) instead. Please note that only clusters that belong to a production instance can be resized. 
        
 ApiFuture<Cluster> clusterFuture = client.resizeCluster("my-instance", "my-cluster", 30);
 Cluster cluster = clusterFuture.get();

      • updateClusterAutoscalingConfig

        public Cluster updateClusterAutoscalingConfig​(@Nonnull
                                              ClusterAutoscalingConfig clusterAutoscalingConfig)
        Modifies the cluster's autoscaling config. This will enable autoscaling and disable manual scaling if the cluster is manually scaled. Please note that only clusters that belong to a production instance can enable autoscaling.

        Sample code: 

        
 ClusterAutoscalingConfig clusterAutoscalingConfig =
      ClusterAutoscalingConfig.of("my-instance", "my-cluster")
          .setMinNodes(1)
          .setMaxNodes(4)
          .setCpuUtilizationTargetPercent(40);
 Cluster cluster = client.updateClusterAutoscalingConfig(clusterAutoscalingConfig);

      • updateClusterAutoscalingConfigAsync

        public com.google.api.core.ApiFuture<Cluster> updateClusterAutoscalingConfigAsync​(@Nonnull
                                                                                  ClusterAutoscalingConfig clusterAutoscalingConfig)
        Asynchronously modifies the cluster's autoscaling config. This will enable autoscaling and disable manual scaling if the cluster is manually scaled. Please note that only clusters that belong to a production instance can enable autoscaling.

        Sample code: 

        
 ClusterAutoscalingConfig clusterAutoscalingConfig =
      ClusterAutoscalingConfig.of(targetInstanceId, targetClusterId)
          .setMinNodes(1)
          .setMaxNodes(4)
          .setCpuUtilizationTargetPercent(40);

  ApiFuture<Cluster> clusterApiFuture = client.updateClusterAutoscalingConfigAsync(clusterAutoscalingConfig);
  Cluster cluster = clusterApiFuture.get();

      • disableClusterAutoscaling

        public Cluster disableClusterAutoscaling​(String instanceId,
                                         String clusterId,
                                         int staticSize)
        Disables autoscaling and enables manual scaling by setting a static node count for the cluster. Please note that only clusters that belong to a production instance can be resized.

        Sample code: 

        
 Cluster cluster = client.disableClusterAutoscaling("my-instance", "my-cluster", 3);

      • disableClusterAutoscalingAsync

        public com.google.api.core.ApiFuture<Cluster> disableClusterAutoscalingAsync​(String instanceId,
                                                                             String clusterId,
                                                                             int staticSize)
        Asynchronously disables autoscaling and enables manual scaling by setting a static node count for the cluster. Please note that only clusters that belong to a production instance can be resized.

        Sample code: 

        
 ApiFuture<Cluster> clusterApiFuture = client.disableClusterAutoscalingAsync("my-instance", "my-cluster", 3);
 Cluster cluster = clusterApiFuture.get();

      • deleteCluster

        public void deleteCluster​(String instanceId,
                          String clusterId)
        Deletes the specified cluster. Please note that an instance must have at least 1 cluster. To remove the last cluster, please use deleteInstance(String).

        Sample code: 

        
 client.deleteCluster("my-instance", "my-cluster");

      • deleteClusterAsync

        public com.google.api.core.ApiFuture<Void> deleteClusterAsync​(String instanceId,
                                                              String clusterId)
        Asynchronously deletes the specified cluster. Please note that an instance must have at least 1 cluster. To remove the last cluster, please use deleteInstanceAsync(String).

        Sample code: 

        
 ApiFuture<Void> future = client.deleteClusterAsync("my-instance", "my-cluster");
 future.get();

      • createAppProfile

        public AppProfile createAppProfile​(CreateAppProfileRequest request)
        Creates a new app profile.

        Sample code: 

        
 AppProfile appProfile = client.createAppProfile(
   CreateAppProfileRequest.of("my-instance", "my-new-app-profile")
     .setRoutingPolicy(SingleClusterRoutingPolicy.of("my-cluster"))
 );
        See Also:
        CreateAppProfileRequest

      • createAppProfileAsync

        public com.google.api.core.ApiFuture<AppProfile> createAppProfileAsync​(CreateAppProfileRequest request)
        Asynchronously creates a new app profile.

        Sample code: 

        
 ApiFuture<AppProfile> appProfileFuture = client.createAppProfileAsync(
   CreateAppProfileRequest.of("my-instance", "my-new-app-profile")
     .setRoutingPolicy(SingleClusterRoutingPolicy.of("my-cluster"))
 );

 AppProfile appProfile = appProfileFuture.get();
        See Also:
        CreateAppProfileRequest

      • getAppProfile

        public AppProfile getAppProfile​(String instanceId,
                                String appProfileId)
        Gets the app profile by ID.

        Sample code: 

        
 AppProfile appProfile = client.getAppProfile("my-instance", "my-app-profile");
        See Also:
        AppProfile

      • getAppProfileAsync

        public com.google.api.core.ApiFuture<AppProfile> getAppProfileAsync​(String instanceId,
                                                                    String appProfileId)
        Asynchronously gets the app profile by ID.

        Sample code: 

        
 ApiFuture<AppProfile> appProfileFuture = client.getAppProfileAsync("my-instance", "my-app-profile");

 AppProfile appProfile = appProfileFuture.get();
        See Also:
        AppProfile

      • listAppProfiles

        public List<AppProfile> listAppProfiles​(String instanceId)
        Lists all app profiles of the specified instance.

        Sample code: 

        
 List<AppProfile> appProfiles = client.listAppProfiles("my-instance");
        See Also:
        AppProfile

      • listAppProfilesAsync

        public com.google.api.core.ApiFuture<List<AppProfile>> listAppProfilesAsync​(String instanceId)
        Asynchronously lists all app profiles of the specified instance.

        Sample code: 

        
 ApiFuture<List<AppProfile>> appProfilesFuture = client.listAppProfilesAsync("my-instance");

 List<AppProfile> appProfiles = appProfileFuture.get();
        See Also:
        AppProfile

      • updateAppProfile

        public AppProfile updateAppProfile​(UpdateAppProfileRequest request)
        Updates an existing app profile.

        Sample code: 

        
 AppProfile existingAppProfile = client.getAppProfile("my-instance", "my-app-profile");

 AppProfile updatedAppProfile = client.updateAppProfile(
   UpdateAppProfileRequest.of(existingAppProfile)
     .setRoutingPolicy(SingleClusterRoutingPolicy.of("my-cluster"))
 );
        See Also:
        UpdateAppProfileRequest

      • updateAppProfileAsync

        public com.google.api.core.ApiFuture<AppProfile> updateAppProfileAsync​(UpdateAppProfileRequest request)
        Asynchronously updates an existing app profile.

        Sample code: 

        
 ApiFuture<AppProfile> existingAppProfileFuture = client.getAppProfileAsync("my-instance", "my-app-profile");

 ApiFuture<AppProfile> updatedAppProfileFuture = ApiFutures.transformAsync(
   existingAppProfileFuture,
   new ApiAsyncFunction<AppProfile, AppProfile>() {
     public ApiFuture<AppProfile> apply(AppProfile existingAppProfile) {
       return client.updateAppProfileAsync(
         UpdateAppProfileRequest.of(existingAppProfile)
           .setRoutingPolicy(SingleClusterRoutingPolicy.of("my-other-cluster"))
       );
     }
   },
   MoreExecutors.directExecutor()
 );

 ApiFuture<AppProfile> appProfile = updatedAppProfileFuture.get();
        See Also:
        UpdateAppProfileRequest

      • deleteAppProfile

        public void deleteAppProfile​(String instanceId,
                             String appProfileId)
        Deletes the specified app profile.

        Sample code: 

        
 client.deleteAppProfile("my-instance", "my-app-profile");

      • deleteAppProfileAsync

        public com.google.api.core.ApiFuture<Void> deleteAppProfileAsync​(String instanceId,
                                                                 String appProfileId)
        Asynchronously deletes the specified app profile.

        Sample code: 

        
 ApiFuture<Void> deleteFuture = client.deleteAppProfileAsync("my-instance", "my-app-profile");

 deleteFuture.get();

      • deleteAppProfile

        public void deleteAppProfile​(String instanceId,
                             String appProfileId,
                             boolean forceDelete)
        Deletes the specified app profile with an option to force deletion.

        Sample code: 

        
 client.deleteAppProfile("my-instance", "my-app-profile", true);

      • deleteAppProfileAsync

        public com.google.api.core.ApiFuture<Void> deleteAppProfileAsync​(String instanceId,
                                                                 String appProfileId,
                                                                 boolean forceDelete)
        Asynchronously deletes the specified app profile with an option to force deletion.

        Sample code: 

        
 ApiFuture<Void> deleteFuture = client.deleteAppProfileAsync("my-instance", "my-app-profile", true);

 deleteFuture.get();

      • getIamPolicy

        public com.google.cloud.Policy getIamPolicy​(String instanceId)
        Gets the IAM access control policy for the specified instance.

        Sample code: 

        
 Policy policy = client.getIamPolicy("my-instance");
 for(Map.Entry<Role, Set<Identity>> entry : policy.getBindings().entrySet()) {
   System.out.printf("Role: %s Identities: %s\n", entry.getKey(), entry.getValue());
 }
        See Also:
        Instance-level IAM management

      • getIamPolicyAsync

        public com.google.api.core.ApiFuture<com.google.cloud.Policy> getIamPolicyAsync​(String instanceId)
        Asynchronously gets the IAM access control policy for the specified instance.

        Sample code: 

        
 ApiFuture<Policy> policyFuture = client.getIamPolicyAsync("my-instance");

 ApiFutures.addCallback(policyFuture,
   new ApiFutureCallback<Policy>() {
     public void onSuccess(Policy policy) {
       for (Entry<Role, Set<Identity>> entry : policy.getBindings().entrySet()) {
         System.out.printf("Role: %s Identities: %s\n", entry.getKey(), entry.getValue());
       }
     }

     public void onFailure(Throwable t) {
       t.printStackTrace();
     }
   },
   MoreExecutors.directExecutor());
        See Also:
        Instance-level IAM management

      • setIamPolicy

        public com.google.cloud.Policy setIamPolicy​(String instanceId,
                                            com.google.cloud.Policy policy)
        Replaces the IAM policy associated with the specified instance.

        Sample code: 

        
 Policy newPolicy = client.setIamPolicy("my-instance",
   Policy.newBuilder()
     .addIdentity(Role.of("bigtable.user"), Identity.user("someone@example.com"))
     .addIdentity(Role.of("bigtable.admin"), Identity.group("admins@example.com"))
     .build());
        See Also:
        Instance-level IAM management

      • setIamPolicyAsync

        public com.google.api.core.ApiFuture<com.google.cloud.Policy> setIamPolicyAsync​(String instanceId,
                                                                                com.google.cloud.Policy policy)
        Asynchronously replaces the IAM policy associated with the specified instance.

        Sample code: 

        
 ApiFuture<Policy> newPolicyFuture = client.setIamPolicyAsync("my-instance",
   Policy.newBuilder()
     .addIdentity(Role.of("bigtable.user"), Identity.user("someone@example.com"))
     .addIdentity(Role.of("bigtable.admin"), Identity.group("admins@example.com"))
     .build());

 ApiFutures.addCallback(policyFuture,
   new ApiFutureCallback<Policy>() {
     public void onSuccess(Policy policy) {
       for (Entry<Role, Set<Identity>> entry : policy.getBindings().entrySet()) {
         System.out.printf("Role: %s Identities: %s\n", entry.getKey(), entry.getValue());
       }
     }

     public void onFailure(Throwable t) {
       t.printStackTrace();
     }
   },
   MoreExecutors.directExecutor());
        See Also:
        Instance-level IAM management

      • testIamPermission

        public List<String> testIamPermission​(String instanceId,
                                      String... permissions)
        Tests whether the caller has the given permissions for the specified instance. Returns a subset of the specified permissions that the caller has.

        Sample code: 

        
 List<String> grantedPermissions = client.testIamPermission("my-instance",
   "bigtable.tables.readRows", "bigtable.tables.mutateRows");
        System.out.println("Has read access: " + grantedPermissions.contains("bigtable.tables.readRows")); System.out.println("Has write access: " + grantedPermissions.contains("bigtable.tables.mutateRows"));
        See Also:
        Cloud Bigtable permissions

      • testIamPermissionAsync

        public com.google.api.core.ApiFuture<List<String>> testIamPermissionAsync​(String instanceId,
                                                                          String... permissions)
        Asynchronously tests whether the caller has the given permissions for the specified instance. Returns a subset of the specified permissions that the caller has.

        Sample code: 

        
 ApiFuture<List<String>> grantedPermissionsFuture = client.testIamPermissionAsync("my-instance",
   "bigtable.tables.readRows", "bigtable.tables.mutateRows");

 ApiFutures.addCallback(grantedPermissionsFuture,
   new ApiFutureCallback<List<String>>() {
     public void onSuccess(List<String> grantedPermissions) {
       System.out.println("Has read access: " + grantedPermissions.contains("bigtable.tables.readRows"));
       System.out.println("Has write access: " + grantedPermissions.contains("bigtable.tables.mutateRows"));
     }

     public void onFailure(Throwable t) {
       t.printStackTrace();
     }
   },
   MoreExecutors.directExecutor());
        See Also:
        Cloud Bigtable permissions