feature(spanner): low-cost instances (#6895)

devbww · web-flow · commit ed8c316520a9 · 2021-06-30T12:12:36.000-04:00
Support the provisioning of Spanner instances using `processing_units`
as an alternative to `node_count`. 1 node == 1,000 processing units.
diff --git a/google/cloud/spanner/create_instance_request_builder.h b/google/cloud/spanner/create_instance_request_builder.h
@@ -47,15 +47,14 @@ class CreateInstanceRequestBuilder {
       default;
 
   /**
-   * Constructor requires Instance and Cloud Spanner instance config name. It
-   * sets node_count = 1, and display_name = instance_id as the default values.
+   * Constructor requires Instance and Cloud Spanner instance config name.
+   * The display_name is set to a default value of in.instance_id().
    */
   CreateInstanceRequestBuilder(Instance const& in, std::string config) {
     request_.set_parent("projects/" + in.project_id());
     request_.set_instance_id(in.instance_id());
     request_.mutable_instance()->set_name(in.FullName());
     request_.mutable_instance()->set_display_name(in.instance_id());
-    request_.mutable_instance()->set_node_count(1);
     request_.mutable_instance()->set_config(std::move(config));
   }
 
@@ -79,6 +78,16 @@ class CreateInstanceRequestBuilder {
     return std::move(*this);
   }
 
+  CreateInstanceRequestBuilder& SetProcessingUnits(int processing_units) & {
+    request_.mutable_instance()->set_processing_units(processing_units);
+    return *this;
+  }
+
+  CreateInstanceRequestBuilder&& SetProcessingUnits(int processing_units) && {
+    request_.mutable_instance()->set_processing_units(processing_units);
+    return std::move(*this);
+  }
+
   CreateInstanceRequestBuilder& SetLabels(
       std::map<std::string, std::string> const& labels) & {
     for (auto const& pair : labels) {
@@ -98,9 +107,21 @@ class CreateInstanceRequestBuilder {
   }
 
   google::spanner::admin::instance::v1::CreateInstanceRequest& Build() & {
+    // Preserve original behavior of defaulting node_count to 1.
+    if (request_.instance().processing_units() == 0) {
+      if (request_.instance().node_count() == 0) {
+        request_.mutable_instance()->set_node_count(1);
+      }
+    }
     return request_;
   }
   google::spanner::admin::instance::v1::CreateInstanceRequest&& Build() && {
+    // Preserve original behavior of defaulting node_count to 1.
+    if (request_.instance().processing_units() == 0) {
+      if (request_.instance().node_count() == 0) {
+        request_.mutable_instance()->set_node_count(1);
+      }
+    }
     return std::move(request_);
   }
 
diff --git a/google/cloud/spanner/create_instance_request_builder_test.cc b/google/cloud/spanner/create_instance_request_builder_test.cc
@@ -70,14 +70,14 @@ TEST(CreateInstanceRequestBuilder, Lvalue) {
 
   auto builder = CreateInstanceRequestBuilder(in, expected_config);
   auto req = builder.SetDisplayName(expected_display_name)
-                 .SetNodeCount(1)
+                 .SetProcessingUnits(500)
                  .SetLabels({{"key", "value"}})
                  .Build();
   EXPECT_EQ("projects/test-project", req.parent());
   EXPECT_EQ("test-instance", req.instance_id());
   EXPECT_EQ(expected_name, req.instance().name());
   EXPECT_EQ(expected_config, req.instance().config());
-  EXPECT_EQ(1, req.instance().node_count());
+  EXPECT_EQ(500, req.instance().processing_units());
   EXPECT_EQ(1, req.instance().labels_size());
   EXPECT_EQ("value", req.instance().labels().at("key"));
   EXPECT_EQ(expected_display_name, req.instance().display_name());
diff --git a/google/cloud/spanner/samples/samples.cc b/google/cloud/spanner/samples/samples.cc
@@ -86,19 +86,56 @@ void CreateInstance(google::cloud::spanner::InstanceAdminClient client,
                   .Build())
           .get();
   if (!instance) throw std::runtime_error(instance.status().message());
-  std::cout << "Created instance [" << in << "]\n";
+  std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
 }
 //! [END spanner_create_instance] [create-instance]
 
+// [START spanner_create_instance_with_processing_units]
+void CreateInstanceWithProcessingUnits(
+    google::cloud::spanner::InstanceAdminClient client,
+    std::string const& project_id, std::string const& instance_id,
+    std::string const& display_name, std::string const& config) {
+  namespace spanner = google::cloud::spanner;
+  spanner::Instance in(project_id, instance_id);
+
+  std::string instance_config =
+      "projects/" + project_id + "/instanceConfigs/" + config;
+  auto instance =
+      client
+          .CreateInstance(
+              spanner::CreateInstanceRequestBuilder(in, instance_config)
+                  .SetDisplayName(display_name)
+                  .SetProcessingUnits(500)
+                  .SetLabels({{"cloud_spanner_samples", "true"}})
+                  .Build())
+          .get();
+  if (!instance) throw std::runtime_error(instance.status().message());
+  std::cout << "Created instance [" << in << "]:\n" << instance->DebugString();
+
+  instance = client.GetInstance(in);
+  if (!instance) throw std::runtime_error(instance.status().message());
+  std::cout << "Instance " << in << " has " << instance->processing_units()
+            << " processing units.\n";
+}
+// [END spanner_create_instance_with_processing_units]
+
 void CreateInstanceCommand(std::vector<std::string> argv) {
+  bool low_cost = !argv.empty() && argv.front() == "--low-cost";
+  if (low_cost) argv.erase(argv.begin());
   if (argv.size() != 3 && argv.size() != 4) {
     throw std::runtime_error(
-        "create-instance <project-id> <instance-id> <display_name> [config]");
+        "create-instance [--low-cost] <project-id> <instance-id>"
+        " <display_name> [config]");
   }
   google::cloud::spanner::InstanceAdminClient client(
       google::cloud::spanner::MakeInstanceAdminConnection());
   std::string config = argv.size() == 4 ? argv[3] : "regional-us-central1";
-  CreateInstance(std::move(client), argv[0], argv[1], argv[2], config);
+  if (low_cost) {
+    CreateInstanceWithProcessingUnits(std::move(client), argv[0], argv[1],
+                                      argv[2], config);
+  } else {
+    CreateInstance(std::move(client), argv[0], argv[1], argv[2], config);
+  }
 }
 
 //! [update-instance]
@@ -3418,6 +3455,21 @@ void RunAllSlowInstanceTests(
 
   std::cout << "\nRunning delete-instance sample" << std::endl;
   DeleteInstance(instance_admin_client, project_id, crud_instance_id);
+
+  if (!emulator) {
+    std::cout
+        << "\nRunning spanner_create_instance_with_processing_units sample"
+        << std::endl;
+    // TODO(#6894): Change "regional-us-central1" to `config` when low-cost
+    // instances are generally available (well, at least in the regions that
+    // `PickConfig()` might return).
+    CreateInstanceWithProcessingUnits(
+        instance_admin_client, project_id, crud_instance_id,
+        "Test Low-Cost Instance", "regional-us-central1");
+
+    std::cout << "\nRunning delete-instance sample" << std::endl;
+    DeleteInstance(instance_admin_client, project_id, crud_instance_id);
+  }
 }
 
 void RunAll(bool emulator) {
diff --git a/google/cloud/spanner/update_instance_request_builder.h b/google/cloud/spanner/update_instance_request_builder.h
@@ -93,6 +93,14 @@ class UpdateInstanceRequestBuilder {
     SetNodeCountImpl(node_count);
     return std::move(*this);
   }
+  UpdateInstanceRequestBuilder& SetProcessingUnits(int processing_units) & {
+    SetProcessingUnitsImpl(processing_units);
+    return *this;
+  }
+  UpdateInstanceRequestBuilder&& SetProcessingUnits(int processing_units) && {
+    SetProcessingUnitsImpl(processing_units);
+    return std::move(*this);
+  }
   UpdateInstanceRequestBuilder& AddLabels(
       std::map<std::string, std::string> const& labels) & {
     AddLabelsImpl(labels);
@@ -138,6 +146,13 @@ class UpdateInstanceRequestBuilder {
     }
     request_.mutable_instance()->set_node_count(node_count);
   }
+  void SetProcessingUnitsImpl(int processing_units) {
+    if (!google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
+            "processing_units", request_.field_mask())) {
+      request_.mutable_field_mask()->add_paths("processing_units");
+    }
+    request_.mutable_instance()->set_processing_units(processing_units);
+  }
   void AddLabelsImpl(std::map<std::string, std::string> const& labels) {
     if (!google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
             "labels", request_.field_mask())) {
diff --git a/google/cloud/spanner/update_instance_request_builder_test.cc b/google/cloud/spanner/update_instance_request_builder_test.cc
@@ -106,19 +106,19 @@ TEST(UpdateInstanceRequestBuilder, SetLabels) {
   instance.set_node_count(1);
   instance.mutable_labels()->insert({"key", "value"});
   auto builder = UpdateInstanceRequestBuilder(instance);
-  auto req = builder.SetNodeCount(2)
+  auto req = builder.SetProcessingUnits(500)
                  .SetDisplayName(expected_display_name)
                  .SetLabels({{"newkey", "newvalue"}})
                  .Build();
   EXPECT_EQ(expected_name, req.instance().name());
   EXPECT_EQ(expected_display_name, req.instance().display_name());
-  EXPECT_EQ(2, req.instance().node_count());
+  EXPECT_EQ(500, req.instance().processing_units());
   EXPECT_EQ(1, req.instance().labels_size());
   EXPECT_EQ("newvalue", req.instance().labels().at("newkey"));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
       "display_name", req.field_mask()));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
-      "node_count", req.field_mask()));
+      "processing_units", req.field_mask()));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
       "labels", req.field_mask()));
 }
@@ -133,19 +133,19 @@ TEST(UpdateInstanceRequestBuilder, SetLabelsRvalueReference) {
   instance.set_node_count(1);
   instance.mutable_labels()->insert({"key", "value"});
   auto req = UpdateInstanceRequestBuilder(instance)
-                 .SetNodeCount(2)
+                 .SetProcessingUnits(500)
                  .SetDisplayName(expected_display_name)
                  .SetLabels({{"newkey", "newvalue"}})
                  .Build();
   EXPECT_EQ(expected_name, req.instance().name());
   EXPECT_EQ(expected_display_name, req.instance().display_name());
-  EXPECT_EQ(2, req.instance().node_count());
+  EXPECT_EQ(500, req.instance().processing_units());
   EXPECT_EQ(1, req.instance().labels_size());
   EXPECT_EQ("newvalue", req.instance().labels().at("newkey"));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
       "display_name", req.field_mask()));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
-      "node_count", req.field_mask()));
+      "processing_units", req.field_mask()));
   EXPECT_TRUE(google::protobuf::util::FieldMaskUtil::IsPathInFieldMask(
       "labels", req.field_mask()));
 }
