Google Cloud Spanner C++ Client  2.2.1
A C++ Client Library for Google Cloud Spanner
instance_admin_client.h
Go to the documentation of this file.
1 // Copyright 2019 Google LLC
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_SPANNER_INSTANCE_ADMIN_CLIENT_H
16 #define GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INSTANCE_ADMIN_CLIENT_H
17 
18 #include "google/cloud/spanner/iam_updater.h"
19 #include "google/cloud/spanner/instance.h"
20 #include "google/cloud/spanner/instance_admin_connection.h"
21 #include "google/cloud/spanner/version.h"
22 #include "google/cloud/status_or.h"
23 #include <string>
24 #include <vector>
25 
26 namespace google {
27 namespace cloud {
28 namespace spanner {
30 
31 /**
32  * Performs instance administration operations on Cloud Spanner.
33  *
34  * Applications use this class to perform operations on
35  * [Spanner Databases][spanner-doc-link].
36  *
37  * @par Performance
38  *
39  * `InstanceAdminClient` objects are cheap to create, copy, and move. However,
40  * each `InstanceAdminClient` object must be created with a
41  * `std::shared_ptr<InstanceAdminConnection>`, which itself is relatively
42  * expensive to create. Therefore, connection instances should be shared when
43  * possible. See the `MakeInstanceAdminConnection()` method and the
44  * `InstanceAdminConnection` interface for more details.
45  *
46  * @par Thread Safety
47  *
48  * Instances of this class created via copy-construction or copy-assignment
49  * share the underlying pool of connections. Access to these copies via multiple
50  * threads is guaranteed to work. Two threads operating on the same instance of
51  * this class is not guaranteed to work.
52  *
53  * @par Error Handling
54  *
55  * This class uses `StatusOr<T>` to report errors. When an operation fails to
56  * perform its work the returned `StatusOr<T>` contains the error details. If
57  * the `ok()` member function in the `StatusOr<T>` returns `true` then it
58  * contains the expected result. Please consult the
59  * [`StatusOr<T>` documentation](#google::cloud::v0::StatusOr) for more details.
60  *
61  * [spanner-doc-link]:
62  * https://cloud.google.com/spanner/docs/api-libraries-overview
63  */
66  public:
67  explicit InstanceAdminClient(std::shared_ptr<InstanceAdminConnection> conn)
68  : conn_(std::move(conn)) {}
69 
70  /// No default construction.
71  /// Use `InstanceAdminClient(std::shared_ptr<InstanceAdminConnection>)`
72  InstanceAdminClient() = delete;
73 
74  //@{
75  // @name Copy and move support
80  //@}
81 
82  //@{
83  // @name Equality
84  friend bool operator==(InstanceAdminClient const& a,
85  InstanceAdminClient const& b) {
86  return a.conn_ == b.conn_;
87  }
88  friend bool operator!=(InstanceAdminClient const& a,
89  InstanceAdminClient const& b) {
90  return !(a == b);
91  }
92  //@}
93 
94  /**
95  * Retrieve metadata information about a Cloud Spanner Instance.
96  *
97  * @par Idempotency
98  * This is a read-only operation and therefore it is always treated as
99  * idempotent.
100  *
101  * @par Example
102  * @snippet samples.cc get-instance
103  */
104  StatusOr<google::spanner::admin::instance::v1::Instance> GetInstance(
105  Instance const& in);
106 
107  /**
108  * Creates a new Cloud Spanner instance in the given project.
109  *
110  * Use CreateInstanceRequestBuilder to build the
111  * `google::spanner::admin::instance::v1::CreateInstanceRequest` object.
112  *
113  * Note that the instance id must be between 2 and 64 characters long, it must
114  * start with a lowercase letter (`[a-z]`), it must end with a lowercase
115  * letter or a number (`[a-z0-9]`) and any characters between the beginning
116  * and ending characters must be lower case letters, numbers, or dashes (`-`),
117  * that is, they must belong to the `[-a-z0-9]` character set.
118  *
119  * @par Example
120  * @snippet samples.cc create-instance
121  *
122  */
123  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
125  google::spanner::admin::instance::v1::CreateInstanceRequest const&);
126 
127  /**
128  * Updates a Cloud Spanner instance.
129  *
130  * Use `google::cloud::spanner::UpdateInstanceRequestBuilder` to build the
131  * `google::spanner::admin::instance::v1::UpdateInstanceRequest` object.
132  *
133  * @par Idempotency
134  * This operation is idempotent as its result does not depend on the previous
135  * state of the instance. Note that, as is the case with all operations, it is
136  * subject to race conditions if multiple tasks are attempting to change the
137  * same fields in the same instance.
138  *
139  * @par Example
140  * @snippet samples.cc update-instance
141  *
142  */
143  future<StatusOr<google::spanner::admin::instance::v1::Instance>>
145  google::spanner::admin::instance::v1::UpdateInstanceRequest const&);
146 
147  /**
148  * Deletes an existing Cloud Spanner instance.
149  *
150  * @warning Deleting an instance deletes all the databases in the
151  * instance. This is an unrecoverable operation.
152  *
153  * @par Example
154  * @snippet samples.cc delete-instance
155  */
157 
158  /**
159  * Retrieve information about a Cloud Spanner Instance Config.
160  *
161  * @par Idempotency
162  * This is a read-only operation and therefore it is always treated as
163  * idempotent.
164  *
165  * @par Example
166  * @snippet samples.cc get-instance-config
167  */
168  StatusOr<google::spanner::admin::instance::v1::InstanceConfig>
169  GetInstanceConfig(std::string const& name);
170 
171  /**
172  * Retrieve a list of instance configs for a given project.
173  *
174  * @par Idempotency
175  * This is a read-only operation and therefore it is always treated as
176  * idempotent.
177  *
178  * @par Example
179  * @snippet samples.cc list-instance-configs
180  */
181  ListInstanceConfigsRange ListInstanceConfigs(std::string project_id);
182 
183  /**
184  * Retrieve a list of instances for a given project.
185  *
186  * @par Idempotency
187  * This is a read-only operation and therefore it is always treated as
188  * idempotent.
189  *
190  * @par Example
191  * @snippet samples.cc list-instances
192  */
193  ListInstancesRange ListInstances(std::string project_id, std::string filter);
194 
195  /**
196  * Get the IAM policy in effect for the given instance.
197  *
198  * This function retrieves the IAM policy configured in the given instance,
199  * that is, which roles are enabled in the instance, and what entities are
200  * members of each role.
201  *
202  * @par Idempotency
203  * This is a read-only operation and therefore it is always treated as
204  * idempotent.
205  *
206  * @par Example
207  * @snippet samples.cc instance-get-iam-policy
208  *
209  * @see The [Cloud Spanner
210  * documentation](https://cloud.google.com/spanner/docs/iam) for a
211  * description of the roles and permissions supported by Cloud Spanner.
212  * @see [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions)
213  * for an introduction to Identity and Access Management in Google Cloud
214  * Platform.
215  */
216  StatusOr<google::iam::v1::Policy> GetIamPolicy(Instance const& in);
217 
218  /**
219  * Set the IAM policy for the given instance.
220  *
221  * This function changes the IAM policy configured in the given instance to
222  * the value of @p policy.
223  *
224  * @par Idempotency
225  * This function is only idempotent if the `etag` field in @p policy is set.
226  * Therefore, the underlying RPCs are only retried if the field is set, and
227  * the function returns the first RPC error in any other case.
228  *
229  * @par Example
230  * @snippet samples.cc add-database-reader
231  *
232  * @see The [Cloud Spanner
233  * documentation](https://cloud.google.com/spanner/docs/iam) for a
234  * description of the roles and permissions supported by Cloud Spanner.
235  * @see [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions)
236  * for an introduction to Identity and Access Management in Google Cloud
237  * Platform.
238  */
239  StatusOr<google::iam::v1::Policy> SetIamPolicy(
240  Instance const& in, google::iam::v1::Policy policy);
241 
242  /**
243  * Updates the IAM policy for an instance using an optimistic concurrency
244  * control loop.
245  *
246  * This function repeatedly reads the current IAM policy in @p in, and then
247  * calls the @p updater with the this policy. The @p updater returns an empty
248  * optional if no changes are required, or it returns the new desired value
249  * for the IAM policy. This function then updates the policy.
250  *
251  * Updating an IAM policy can fail with retryable errors or can be aborted
252  * because there were simultaneous changes the to IAM policy. In these cases
253  * this function reruns the loop until it succeeds.
254  *
255  * The function returns the final IAM policy, or an error if the rerun policy
256  * for the underlying connection has expired.
257  *
258  * @par Idempotency
259  * This function always sets the `etag` field on the policy, so the underlying
260  * RPCs are retried automatically.
261  *
262  * @param in the identifier for the instance where you want to change the IAM
263  * policy.
264  * @param updater a callback to modify the policy. Return an unset optional
265  * to indicate that no changes to the policy are needed.
266  */
267  StatusOr<google::iam::v1::Policy> SetIamPolicy(Instance const& in,
268  IamUpdater const& updater);
269 
270  /**
271  * @copydoc SetIamPolicy(Instance const&,IamUpdater const&)
272  *
273  * @param rerun_policy controls for how long (or how many times) the updater
274  * will be rerun after the IAM policy update aborts.
275  * @param backoff_policy controls how long `SetIamPolicy` waits between
276  * reruns.
277  */
278  StatusOr<google::iam::v1::Policy> SetIamPolicy(
279  Instance const& in, IamUpdater const& updater,
280  std::unique_ptr<TransactionRerunPolicy> rerun_policy,
281  std::unique_ptr<BackoffPolicy> backoff_policy);
282 
283  /**
284  * Get the subset of the permissions the caller has on the given instance.
285  *
286  * This function compares the given list of permissions against those
287  * permissions granted to the caller, and returns the subset of the list that
288  * the caller actually holds.
289  *
290  * @note Permission wildcards, such as `spanner.*` are not allowed.
291  *
292  * @par Example
293  * @snippet samples.cc instance-test-iam-permissions
294  *
295  * @see The [Cloud Spanner
296  * documentation](https://cloud.google.com/spanner/docs/iam) for a description
297  * of the roles and permissions supported by Cloud Spanner.
298  * @see [IAM Overview](https://cloud.google.com/iam/docs/overview#permissions)
299  * for an introduction to Identity and Access Management in Google Cloud
300  * Platform.
301  */
302  StatusOr<google::iam::v1::TestIamPermissionsResponse> TestIamPermissions(
303  Instance const& in, std::vector<std::string> permissions);
304 
305  private:
306  std::shared_ptr<InstanceAdminConnection> conn_;
307 };
308 
310 } // namespace spanner
311 } // namespace cloud
312 } // namespace google
313 
314 #endif // GOOGLE_CLOUD_CPP_GOOGLE_CLOUD_SPANNER_INSTANCE_ADMIN_CLIENT_H