Google Cloud Bigtable C++ Client  1.42.0
A C++ Client Library for Google Cloud Bigtable
instance_admin.h
Go to the documentation of this file.
1 // Copyright 2018 Google Inc.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // https://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #ifndef GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_INSTANCE_ADMIN_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_INSTANCE_ADMIN_H
17 
18 #include "google/cloud/bigtable/admin/bigtable_instance_admin_connection.h"
19 #include "google/cloud/bigtable/admin/bigtable_instance_admin_options.h"
20 #include "google/cloud/bigtable/app_profile_config.h"
21 #include "google/cloud/bigtable/cluster_config.h"
22 #include "google/cloud/bigtable/cluster_list_responses.h"
23 #include "google/cloud/bigtable/completion_queue.h"
24 #include "google/cloud/bigtable/iam_policy.h"
25 #include "google/cloud/bigtable/instance_admin_client.h"
26 #include "google/cloud/bigtable/instance_config.h"
27 #include "google/cloud/bigtable/instance_list_responses.h"
28 #include "google/cloud/bigtable/instance_update_config.h"
29 #include "google/cloud/bigtable/internal/convert_policies.h"
30 #include "google/cloud/bigtable/polling_policy.h"
31 #include "google/cloud/bigtable/resource_names.h"
32 #include "google/cloud/bigtable/version.h"
33 #include "google/cloud/future.h"
34 #include "google/cloud/project.h"
35 #include "google/cloud/status_or.h"
36 #include <future>
37 #include <memory>
38 #include <string>
39 #include <vector>
40 
41 namespace google {
42 namespace cloud {
43 namespace bigtable_internal {
45 class InstanceAdminTester;
47 } // namespace bigtable_internal
48 namespace bigtable {
50 
51 /**
52  * Implements the APIs to administer Cloud Bigtable instances.
53  *
54  * @par Thread-safety
55  * Instances of this class created via copy-construction or copy-assignment
56  * share the underlying pool of connections. Access to these copies via multiple
57  * threads is guaranteed to work. Two threads operating concurrently on the same
58  * instance of this class is not guaranteed to work.
59  *
60  * @par Cost
61  * Creating a new object of type `InstanceAdmin` is comparable to creating a few
62  * objects of type `std::string` or a few objects of type
63  * `std::shared_ptr<int>`. The class represents a shallow handle to a remote
64  * object.
65  *
66  * @par Error Handling
67  * This class uses `StatusOr<T>` to report errors. When an operation fails to
68  * perform its work the returned `StatusOr<T>` contains the error details. If
69  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
70  * contains the expected result. Operations that do not return a value simply
71  * return a `google::cloud::Status` indicating success or the details of the
72  * error Please consult the [`StatusOr<T>`
73  * documentation](#google::cloud::StatusOr) for more details.
74  *
75  * @code
76  * namespace cbt = google::cloud::bigtable;
77  * namespace btadmin = google::bigtable::admin::v2;
78  * cbt::InstanceAdmin admin = ...;
79  * google::cloud::StatusOr<btadmin::Instance> instance = admin.GetInstance(...);
80  *
81  * if (!instance) {
82  * std::cerr << "Error fetching instance\n";
83  * return;
84  * }
85  *
86  * // Use `instance` as a smart pointer here, e.g.:
87  * std::cout << "The full instance name is " << instance->name() << "\n";
88  * @endcode
89  *
90  * In addition, the @ref index "main page" contains examples using `StatusOr<T>`
91  * to handle errors.
92  *
93  * @par Retry, Backoff, and Idempotency Policies
94  * The library automatically retries requests that fail with transient errors,
95  * and uses [truncated exponential backoff][backoff-link] to backoff between
96  * retries. The default policies are to continue retrying for up to 10 minutes.
97  * On each transient failure the backoff period is doubled, starting with an
98  * initial backoff of 100 milliseconds. The backoff period growth is truncated
99  * at 60 seconds. The default idempotency policy is to only retry idempotent
100  * operations. Note that most operations that change state are **not**
101  * idempotent.
102  *
103  * The application can override these policies when constructing objects of this
104  * class. The documentation for the constructors show examples of this in
105  * action.
106  *
107  * [backoff-link]: https://cloud.google.com/storage/docs/exponential-backoff
108  *
109  * @see https://cloud.google.com/bigtable/ for an overview of Cloud Bigtable.
110  *
111  * @see https://cloud.google.com/bigtable/docs/overview for an overview of the
112  * Cloud Bigtable data model.
113  *
114  * @see https://cloud.google.com/bigtable/docs/instances-clusters-nodes for an
115  * introduction of the main APIs into Cloud Bigtable.
116  *
117  * @see https://cloud.google.com/bigtable/docs/reference/service-apis-overview
118  * for an overview of the underlying Cloud Bigtable API.
119  *
120  * @see #google::cloud::StatusOr for a description of the error reporting class
121  * used by this library.
122  *
123  * @see `LimitedTimeRetryPolicy` and `LimitedErrorCountRetryPolicy` for
124  * alternative retry policies.
125  *
126  * @see `ExponentialBackoffPolicy` to configure different parameters for the
127  * exponential backoff policy.
128  *
129  * @see `SafeIdempotentMutationPolicy` and `AlwaysRetryMutationPolicy` for
130  * alternative idempotency policies.
131  */
133  public:
134  explicit InstanceAdmin(
136  connection,
137  std::string project)
138  : connection_(std::move(connection)),
139  project_id_(std::move(project)),
140  project_name_(Project(project_id_).FullName()),
141  retry_prototype_(
142  DefaultRPCRetryPolicy(internal::kBigtableInstanceAdminLimits)),
143  backoff_prototype_(
144  DefaultRPCBackoffPolicy(internal::kBigtableInstanceAdminLimits)),
145  polling_prototype_(
146  DefaultPollingPolicy(internal::kBigtableInstanceAdminLimits)),
147  policies_(bigtable_internal::MakeInstanceAdminOptions(
148  retry_prototype_, backoff_prototype_, polling_prototype_)) {}
149 
150  /**
151  * @param client the interface to create grpc stubs, report errors, etc.
152  */
153  // NOLINTNEXTLINE(performance-unnecessary-value-param)
154  explicit InstanceAdmin(std::shared_ptr<InstanceAdminClient> client)
155  : InstanceAdmin(client->connection_, client->project()) {}
156 
157  /**
158  * Create a new InstanceAdmin using explicit policies to handle RPC errors.
159  *
160  * @param client the interface to create grpc stubs, report errors, etc.
161  * @param policies the set of policy overrides for this object.
162  * @tparam Policies the types of the policies to override, the types must
163  * derive from one of the following types:
164  * - `RPCBackoffPolicy` how to backoff from a failed RPC. Currently only
165  * `ExponentialBackoffPolicy` is implemented. You can also create your
166  * own policies that backoff using a different algorithm.
167  * - `RPCRetryPolicy` for how long to retry failed RPCs. Use
168  * `LimitedErrorCountRetryPolicy` to limit the number of failures
169  * allowed. Use `LimitedTimeRetryPolicy` to bound the time for any
170  * request. You can also create your own policies that combine time and
171  * error counts.
172  * - `PollingPolicy` for how long will the class wait for
173  * `google.longrunning.Operation` to complete. This class combines both
174  * the backoff policy for checking long running operations and the
175  * retry policy.
176  *
177  * @see GenericPollingPolicy, ExponentialBackoffPolicy,
178  * LimitedErrorCountRetryPolicy, LimitedTimeRetryPolicy.
179  */
180  template <typename... Policies>
181  // NOLINTNEXTLINE(performance-unnecessary-value-param)
182  explicit InstanceAdmin(std::shared_ptr<InstanceAdminClient> client,
183  Policies&&... policies)
184  : connection_(client->connection_),
185  project_id_(client->project()),
186  project_name_(Project(project_id_).FullName()),
187  retry_prototype_(
188  DefaultRPCRetryPolicy(internal::kBigtableInstanceAdminLimits)),
189  backoff_prototype_(
190  DefaultRPCBackoffPolicy(internal::kBigtableInstanceAdminLimits)),
191  polling_prototype_(
192  DefaultPollingPolicy(internal::kBigtableInstanceAdminLimits)) {
193  ChangePolicies(std::forward<Policies>(policies)...);
194  policies_ = bigtable_internal::MakeInstanceAdminOptions(
195  retry_prototype_, backoff_prototype_, polling_prototype_);
196  }
197 
198  /// The full name (`projects/<project_id>`) of the project.
199  std::string const& project_name() const { return project_name_; }
200  /// The project id, i.e., `project_name()` without the `projects/` prefix.
201  std::string const& project_id() const { return project_id_; }
202 
203  /**
204  * Returns an InstanceAdmin that reuses the connection and configuration of
205  * this InstanceAdmin, but with a different resource name.
206  */
207  InstanceAdmin WithNewTarget(std::string project_id) const {
208  auto admin = *this;
209  admin.project_id_ = std::move(project_id);
210  admin.project_name_ = Project(admin.project_id_).FullName();
211  return admin;
212  }
213 
214  /// Return the fully qualified name of the given instance_id.
215  std::string InstanceName(std::string const& instance_id) const {
216  return google::cloud::bigtable::InstanceName(project_id_, instance_id);
217  }
218 
219  /// Return the fully qualified name of the given cluster_id in give
220  /// instance_id.
221  std::string ClusterName(std::string const& instance_id,
222  std::string const& cluster_id) const {
223  return google::cloud::bigtable::ClusterName(project_id_, instance_id,
224  cluster_id);
225  }
226 
227  std::string AppProfileName(std::string const& instance_id,
228  std::string const& profile_id) const {
229  return google::cloud::bigtable::AppProfileName(project_id_, instance_id,
230  profile_id);
231  }
232 
233  /**
234  * Create a new instance of Cloud Bigtable.
235  *
236  * @warning Note that this is operation can take seconds or minutes to
237  * complete. The application may prefer to perform other work while waiting
238  * for this operation.
239  *
240  * @param instance_config a description of the new instance to be created.
241  * instance_id and a display_name parameters must be set in instance_config,
242  * - instance_id : must be between 6 and 33 characters.
243  * - display_name : must be between 4 and 30 characters.
244  * @return a future that becomes satisfied when (a) the operation has
245  * completed successfully, in which case it returns a proto with the
246  * Instance details, (b) the operation has failed, in which case the future
247  * contains an `google::cloud::Status` with the details of the failure, or
248  * (c) the state of the operation is unknown after the time allocated by the
249  * retry policies has expired, in which case the future contains the last
250  * error status.
251  *
252  * @par Idempotency
253  * This operation is always treated as non-idempotent.
254  *
255  * @par Thread-safety
256  * Two threads concurrently calling this member function on the same instance
257  * of this class are **not** guaranteed to work. Consider copying the object
258  * and using different copies in each thread.
259  *
260  * @par Example
261  * @snippet bigtable_instance_admin_snippets.cc create instance
262  */
263  future<StatusOr<google::bigtable::admin::v2::Instance>> CreateInstance(
264  InstanceConfig instance_config);
265 
266  /**
267  * Create a new Cluster of Cloud Bigtable.
268  *
269  * @param cluster_config a description of the new cluster to be created.
270  * @param instance_id the id of the instance in the project
271  * @param cluster_id the id of the cluster in the project that needs to be
272  * created. It must be between 6 and 30 characters.
273  *
274  * @par Idempotency
275  * This operation is always treated as non-idempotent.
276  *
277  * @par Thread-safety
278  * Two threads concurrently calling this member function on the same instance
279  * of this class are **not** guaranteed to work. Consider copying the object
280  * and using different copies in each thread.
281  *
282  * @par Example
283  * @snippet bigtable_instance_admin_snippets.cc create cluster
284  */
285  future<StatusOr<google::bigtable::admin::v2::Cluster>> CreateCluster(
286  ClusterConfig cluster_config, std::string const& instance_id,
287  std::string const& cluster_id);
288 
289  /**
290  * Update an existing instance of Cloud Bigtable.
291  *
292  * @warning Note that this is operation can take seconds or minutes to
293  * complete. The application may prefer to perform other work while waiting
294  * for this operation.
295  *
296  * @param instance_update_config config with modified instance.
297  * @return a future that becomes satisfied when (a) the operation has
298  * completed successfully, in which case it returns a proto with the
299  * Instance details, (b) the operation has failed, in which case the future
300  * contains an exception (typically `bigtable::GrpcError`) with the details
301  * of the failure, or (c) the state of the operation is unknown after the
302  * time allocated by the retry policies has expired, in which case the
303  * future contains an exception of type `bigtable::PollTimeout`.
304  *
305  * @par Idempotency
306  * This operation is always treated as non-idempotent.
307  *
308  * @par Thread-safety
309  * Two threads concurrently calling this member function on the same instance
310  * of this class are **not** guaranteed to work. Consider copying the object
311  * and using different copies in each thread.
312  *
313  * @par Example
314  * @snippet bigtable_instance_admin_snippets.cc update instance
315  */
316  future<StatusOr<google::bigtable::admin::v2::Instance>> UpdateInstance(
317  InstanceUpdateConfig instance_update_config);
318 
319  /**
320  * Obtain the list of instances in the project.
321  *
322  * @note In some circumstances Cloud Bigtable may be unable to obtain the full
323  * list of instances, typically because some transient failure has made
324  * specific zones unavailable. In this cases the service returns a separate
325  * list of `failed_locations` that represent the unavailable zones.
326  * Applications may want to retry the operation after the transient
327  * conditions have cleared.
328  *
329  * @par Idempotency
330  * This operation is read-only and therefore it is always idempotent.
331  *
332  * @par Thread-safety
333  * Two threads concurrently calling this member function on the same instance
334  * of this class are **not** guaranteed to work. Consider copying the object
335  * and using different copies in each thread.
336  *
337  * @par Example
338  * @snippet bigtable_instance_admin_snippets.cc list instances
339  */
341 
342  /**
343  * Return the details of @p instance_id.
344  *
345  * @par Idempotency
346  * This operation is read-only and therefore it is always idempotent.
347  *
348  * @par Thread-safety
349  * Two threads concurrently calling this member function on the same instance
350  * of this class are **not** guaranteed to work. Consider copying the object
351  * and using different copies in each thread.
352  *
353  * @par Example
354  * @snippet bigtable_instance_admin_snippets.cc get instance
355  */
356  StatusOr<google::bigtable::admin::v2::Instance> GetInstance(
357  std::string const& instance_id);
358 
359  /**
360  * Deletes the instances in the project.
361  *
362  * @param instance_id the id of the instance in the project that needs to be
363  * deleted
364  *
365  * @par Idempotency
366  * This operation is always treated as non-idempotent.
367  *
368  * @par Thread-safety
369  * Two threads concurrently calling this member function on the same instance
370  * of this class are **not** guaranteed to work. Consider copying the object
371  * and using different copies in each thread.
372  *
373  * @par Example
374  * @snippet bigtable_instance_admin_snippets.cc delete instance
375  */
376  Status DeleteInstance(std::string const& instance_id);
377 
378  /**
379  * Obtain the list of clusters in an instance.
380  *
381  * @note In some circumstances Cloud Bigtable may be unable to obtain the full
382  * list of clusters, typically because some transient failure has made
383  * specific zones unavailable. In this cases the service returns a separate
384  * list of `failed_locations` that represent the unavailable zones.
385  * Applications may want to retry the operation after the transient
386  * conditions have cleared.
387  *
388  * @par Idempotency
389  * This operation is read-only and therefore it is always idempotent.
390  *
391  * @par Thread-safety
392  * Two threads concurrently calling this member function on the same instance
393  * of this class are **not** guaranteed to work. Consider copying the object
394  * and using different copies in each thread.
395  *
396  * @par Example
397  * @snippet bigtable_instance_admin_snippets.cc list clusters
398  */
400 
401  /**
402  * Obtain the list of clusters in an instance.
403  *
404  * @note In some circumstances Cloud Bigtable may be unable to obtain the full
405  * list of clusters, typically because some transient failure has made
406  * specific zones unavailable. In this cases the service returns a separate
407  * list of `failed_locations` that represent the unavailable zones.
408  * Applications may want to retry the operation after the transient
409  * conditions have cleared.
410  *
411  * @par Idempotency
412  * This operation is read-only and therefore it is always idempotent.
413  *
414  * @par Thread-safety
415  * Two threads concurrently calling this member function on the same instance
416  * of this class are **not** guaranteed to work. Consider copying the object
417  * and using different copies in each thread.
418  *
419  * @par Example
420  * @snippet bigtable_instance_admin_snippets.cc list clusters
421  */
422  StatusOr<ClusterList> ListClusters(std::string const& instance_id);
423 
424  /**
425  * Update an existing cluster of Cloud Bigtable.
426  *
427  * @warning Note that this is operation can take seconds or minutes to
428  * complete. The application may prefer to perform other work while waiting
429  * for this operation.
430  *
431  * @param cluster_config cluster with updated values.
432  * @return a future that becomes satisfied when (a) the operation has
433  * completed successfully, in which case it returns a proto with the
434  * Instance details, (b) the operation has failed, in which case the future
435  * contains an exception (typically `bigtable::GrpcError`) with the details
436  * of the failure, or (c) the state of the operation is unknown after the
437  * time allocated by the retry policies has expired, in which case the
438  * future contains an exception of type `bigtable::PollTimeout`.
439  *
440  * @par Idempotency
441  * This operation is always treated as non-idempotent.
442  *
443  * @par Thread-safety
444  * Two threads concurrently calling this member function on the same instance
445  * of this class are **not** guaranteed to work. Consider copying the object
446  * and using different copies in each thread.
447  *
448  * @par Example
449  * @snippet bigtable_instance_admin_snippets.cc update cluster
450  */
451  future<StatusOr<google::bigtable::admin::v2::Cluster>> UpdateCluster(
452  ClusterConfig cluster_config);
453 
454  /**
455  * Deletes the specified cluster of an instance in the project.
456  *
457  * @param instance_id the id of the instance in the project
458  * @param cluster_id the id of the cluster in the project that needs to be
459  * deleted
460  *
461  * @par Idempotency
462  * This operation is always treated as non-idempotent.
463  *
464  * @par Thread-safety
465  * Two threads concurrently calling this member function on the same instance
466  * of this class are **not** guaranteed to work. Consider copying the object
467  * and using different copies in each thread.
468  *
469  * @par Example
470  * @snippet bigtable_instance_admin_snippets.cc delete cluster
471  */
472  Status DeleteCluster(std::string const& instance_id,
473  std::string const& cluster_id);
474 
475  /**
476  * Gets the specified cluster of an instance in the project.
477  *
478  * @param instance_id the id of the instance in the project
479  * @param cluster_id the id of the cluster in the project that needs to be
480  * deleted
481  * @return a Cluster for given instance_id and cluster_id.
482  *
483  * @par Idempotency
484  * This operation is read-only and therefore it is always idempotent.
485  *
486  * @par Thread-safety
487  * Two threads concurrently calling this member function on the same instance
488  * of this class are **not** guaranteed to work. Consider copying the object
489  * and using different copies in each thread.
490  *
491  * @par Example
492  * @snippet bigtable_instance_admin_snippets.cc get cluster
493  */
494  StatusOr<google::bigtable::admin::v2::Cluster> GetCluster(
495  std::string const& instance_id, std::string const& cluster_id);
496 
497  /**
498  * Create a new application profile.
499  *
500  * @param instance_id the instance for the new application profile.
501  * @param config the configuration for the new application profile.
502  * @return The proto describing the new application profile.
503  *
504  * @par Idempotency
505  * This operation is always treated as non-idempotent.
506  *
507  * @par Thread-safety
508  * Two threads concurrently calling this member function on the same instance
509  * of this class are **not** guaranteed to work. Consider copying the object
510  * and using different copies in each thread.
511  *
512  * @par Multi-cluster Routing Example
513  * @snippet bigtable_instance_admin_snippets.cc create app profile
514  *
515  * @par Single Cluster Routing Example
516  * @snippet bigtable_instance_admin_snippets.cc create app profile cluster
517  */
518  StatusOr<google::bigtable::admin::v2::AppProfile> CreateAppProfile(
519  std::string const& instance_id, AppProfileConfig config);
520 
521  /**
522  * Fetch the detailed information about an existing application profile.
523  *
524  * @param instance_id the instance to look the profile in.
525  * @param profile_id the id of the profile within that instance.
526  * @return The proto describing the application profile.
527  *
528  * @par Idempotency
529  * This operation is read-only and therefore it is always idempotent.
530  *
531  * @par Thread-safety
532  * Two threads concurrently calling this member function on the same instance
533  * of this class are **not** guaranteed to work. Consider copying the object
534  * and using different copies in each thread.
535  *
536  * @par Example
537  * @snippet bigtable_instance_admin_snippets.cc get app profile
538  */
539  StatusOr<google::bigtable::admin::v2::AppProfile> GetAppProfile(
540  std::string const& instance_id, std::string const& profile_id);
541 
542  /**
543  * Updates an existing application profile.
544  *
545  * @param instance_id the instance for the new application profile.
546  * @param profile_id the id (not the full name) of the profile to update.
547  * @param config the configuration for the new application profile.
548  * @return The proto describing the new application profile.
549  *
550  * @par Idempotency
551  * This operation is always treated as non-idempotent.
552  *
553  * @par Thread-safety
554  * Two threads concurrently calling this member function on the same instance
555  * of this class are **not** guaranteed to work. Consider copying the object
556  * and using different copies in each thread.
557  *
558  * @par Change Description Example
559  * @snippet bigtable_instance_admin_snippets.cc update app profile description
560  *
561  * @par Change Routing to Any Cluster Example
562  * @snippet bigtable_instance_admin_snippets.cc update app profile routing any
563  *
564  * @par Change Routing to a Specific Cluster Example
565  * @snippet bigtable_instance_admin_snippets.cc update app profile routing
566  */
567  future<StatusOr<google::bigtable::admin::v2::AppProfile>> UpdateAppProfile(
568  std::string const& instance_id, std::string const& profile_id,
569  AppProfileUpdateConfig config);
570 
571  /**
572  * List the application profiles in an instance.
573  *
574  * @param instance_id the instance to list the profiles for.
575  * @return a std::vector with the protos describing any profiles.
576  *
577  * @par Idempotency
578  * This operation is read-only and therefore it is always idempotent.
579  *
580  * @par Thread-safety
581  * Two threads concurrently calling this member function on the same instance
582  * of this class are **not** guaranteed to work. Consider copying the object
583  * and using different copies in each thread.
584  *
585  * @par Example
586  * @snippet bigtable_instance_admin_snippets.cc list app profiles
587  */
588  StatusOr<std::vector<google::bigtable::admin::v2::AppProfile>>
589  ListAppProfiles(std::string const& instance_id);
590 
591  /**
592  * Delete an existing application profile.
593  *
594  * @param instance_id the instance to look the profile in.
595  * @param profile_id the id of the profile within that instance.
596  * @param ignore_warnings if true, ignore safety checks when deleting the
597  * application profile. This value is to to `true` by default. Passing
598  * `false` causes this function to fail even when no operations are
599  * pending.
600  *
601  * @par Idempotency
602  * This operation is always treated as non-idempotent.
603  *
604  * @par Thread-safety
605  * Two threads concurrently calling this member function on the same instance
606  * of this class are **not** guaranteed to work. Consider copying the object
607  * and using different copies in each thread.
608  *
609  * @par Example
610  * @snippet bigtable_instance_admin_snippets.cc delete app profile
611  */
612  Status DeleteAppProfile(std::string const& instance_id,
613  std::string const& profile_id,
614  bool ignore_warnings = true);
615 
616  /**
617  * Gets the native policy for @p instance_id.
618  *
619  * @param instance_id the instance to query.
620  * @return google::iam::v1::Policy the full IAM policy for the instance.
621  *
622  * @par Idempotency
623  * This operation is read-only and therefore it is always idempotent.
624  *
625  * @par Thread-safety
626  * Two threads concurrently calling this member function on the same instance
627  * of this class are **not** guaranteed to work. Consider copying the object
628  * and using different copies in each thread.
629  *
630  * @par Example
631  * @snippet bigtable_instance_admin_snippets.cc get native iam policy
632  */
633  StatusOr<google::iam::v1::Policy> GetNativeIamPolicy(
634  std::string const& instance_id);
635 
636  /**
637  * Sets the IAM policy for an instance.
638  *
639  * @param instance_id which instance to set the IAM policy for.
640  * @param iam_policy google::iam::v1::Policy object containing role and
641  * members.
642  * @return google::iam::v1::Policy the current IAM policy for the instance.
643  *
644  * @warning ETags are currently not used by Cloud Bigtable.
645  *
646  * @par Idempotency
647  * This operation is always treated as non-idempotent.
648  *
649  * @par Thread-safety
650  * Two threads concurrently calling this member function on the same instance
651  * of this class are **not** guaranteed to work. Consider copying the object
652  * and using different copies in each thread.
653  *
654  * @par Example
655  * @snippet bigtable_instance_admin_snippets.cc set native iam policy
656  */
657  StatusOr<google::iam::v1::Policy> SetIamPolicy(
658  std::string const& instance_id,
659  google::iam::v1::Policy const& iam_policy);
660 
661  /**
662  * Returns a permission set that the caller has on the specified instance.
663  *
664  * @param instance_id the ID of the instance to query.
665  * @param permissions set of permissions to check for the resource.
666  *
667  * @par Idempotency
668  * This operation is read-only and therefore it is always idempotent.
669  *
670  * @par Thread-safety
671  * Two threads concurrently calling this member function on the same instance
672  * of this class are **not** guaranteed to work. Consider copying the object
673  * and using different copies in each thread.
674  *
675  * @par Example
676  * @snippet bigtable_instance_admin_snippets.cc test iam permissions
677  *
678  * @see https://cloud.google.com/bigtable/docs/access-control for a list of
679  * valid permissions on Google Cloud Bigtable.
680  */
681  StatusOr<std::vector<std::string>> TestIamPermissions(
682  std::string const& instance_id,
683  std::vector<std::string> const& permissions);
684 
685  private:
686  friend class bigtable_internal::InstanceAdminTester;
687 
688  //@{
689  /// @name Helper functions to implement constructors with changed policies.
690  void ChangePolicy(RPCRetryPolicy const& policy) {
691  retry_prototype_ = policy.clone();
692  }
693 
694  void ChangePolicy(RPCBackoffPolicy const& policy) {
695  backoff_prototype_ = policy.clone();
696  }
697 
698  void ChangePolicy(PollingPolicy const& policy) {
699  polling_prototype_ = policy.clone();
700  }
701 
702  template <typename Policy, typename... Policies>
703  void ChangePolicies(Policy&& policy, Policies&&... policies) {
704  ChangePolicy(policy);
705  ChangePolicies(std::forward<Policies>(policies)...);
706  }
707  void ChangePolicies() {}
708  //@}
709 
710  std::shared_ptr<bigtable_admin::BigtableInstanceAdminConnection> connection_;
711  std::string project_id_;
712  std::string project_name_;
713  //@{
714  /// These prototypes are only used as temporary storage during construction of
715  /// the class, where they are consolidated as `policies_`.
716  std::shared_ptr<RPCRetryPolicy> retry_prototype_;
717  std::shared_ptr<RPCBackoffPolicy> backoff_prototype_;
718  std::shared_ptr<PollingPolicy> polling_prototype_;
719  //}
720  Options policies_;
721 };
722 
724 } // namespace bigtable
725 } // namespace cloud
726 } // namespace google
727 
728 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_BIGTABLE_INSTANCE_ADMIN_H