docs:clarify some defaults and required or optional values

Google APIs · copybara-github · commit 97e3b44f2f08 · 2024-03-04T14:14:21.000-08:00
feat:support mounting NFS and GCS volumes in Cloud Run Jobs and Services
feat:support specifying a per-Service min-instance-count
feat:support disabling waiting for health checks during Service deployment.
feat:allow disabling the default URL (run.app) for Cloud Run Services

PiperOrigin-RevId: 612580574
diff --git a/google/cloud/run/v2/BUILD.bazel b/google/cloud/run/v2/BUILD.bazel
@@ -9,14 +9,17 @@
 #    * extra_protoc_file_parameters
 # The complete list of preserved parameters can be found in the source code.
 
+# buildifier: disable=load-on-top
+
 # This is an API workspace, having public visibility by default makes perfect sense.
 package(default_visibility = ["//visibility:public"])
 
 ##############################################################################
 # Common
 ##############################################################################
-load("@rules_proto//proto:defs.bzl", "proto_library")
+# buildifier: disable=same-origin-load
 load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info")
+load("@rules_proto//proto:defs.bzl", "proto_library")
 
 proto_library(
     name = "run_proto",
@@ -29,6 +32,7 @@ proto_library(
         "revision.proto",
         "revision_template.proto",
         "service.proto",
+        "status.proto",
         "task.proto",
         "task_template.proto",
         "traffic_target.proto",
@@ -62,6 +66,7 @@ proto_library_with_info(
 ##############################################################################
 # Java
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "java_gapic_assembly_gradle_pkg",
@@ -136,6 +141,7 @@ java_gapic_assembly_gradle_pkg(
 ##############################################################################
 # Go
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "go_gapic_assembly_pkg",
@@ -151,7 +157,6 @@ go_proto_library(
     deps = [
         "//google/api:annotations_go_proto",
         "//google/api:api_go_proto",
-        "//google/api:routing_go_proto",
         "//google/iam/v1:iam_go_proto",
         "//google/longrunning:longrunning_go_proto",
         "//google/rpc:status_go_proto",
@@ -194,6 +199,7 @@ go_gapic_assembly_pkg(
 ##############################################################################
 # Python
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "py_gapic_assembly_pkg",
@@ -234,6 +240,7 @@ py_gapic_assembly_pkg(
 ##############################################################################
 # PHP
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "php_gapic_assembly_pkg",
@@ -254,7 +261,9 @@ php_gapic_library(
     rest_numeric_enums = True,
     service_yaml = "run_v2.yaml",
     transport = "grpc+rest",
-    deps = [":run_php_proto"],
+    deps = [
+        ":run_php_proto",
+    ],
 )
 
 # Open Source Packages
@@ -269,6 +278,7 @@ php_gapic_assembly_pkg(
 ##############################################################################
 # Node.js
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "nodejs_gapic_assembly_pkg",
@@ -299,6 +309,7 @@ nodejs_gapic_assembly_pkg(
 ##############################################################################
 # Ruby
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "ruby_cloud_gapic_library",
@@ -353,6 +364,7 @@ ruby_gapic_assembly_pkg(
 ##############################################################################
 # C#
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "csharp_gapic_assembly_pkg",
@@ -363,6 +375,7 @@ load(
 
 csharp_proto_library(
     name = "run_csharp_proto",
+    extra_opts = [],
     deps = [":run_proto"],
 )
 
@@ -399,6 +412,7 @@ csharp_gapic_assembly_pkg(
 ##############################################################################
 # C++
 ##############################################################################
+# buildifier: disable=same-origin-load
 load(
     "@com_google_googleapis_imports//:imports.bzl",
     "cc_grpc_library",
diff --git a/google/cloud/run/v2/k8s.min.proto b/google/cloud/run/v2/k8s.min.proto
@@ -100,7 +100,7 @@ message Container {
 
 // ResourceRequirements describes the compute resource requirements.
 message ResourceRequirements {
-  // Only ´memory´ and 'cpu' are supported.
+  // Only `memory` and `cpu` keys in the map are supported.
   //
   // <p>Notes:
   //  * The only supported values for CPU are '1', '2', '4', and '8'. Setting 4
@@ -110,7 +110,9 @@ message ResourceRequirements {
   //  https://cloud.google.com/run/docs/configuring/memory-limits
   map<string, string> limits = 1;
 
-  // Determines whether CPU should be throttled or not outside of requests.
+  // Determines whether CPU is only allocated during requests (true by default).
+  // However, if ResourceRequirements is set, the caller must explicitly
+  // set this field to true to preserve the default behavior.
   bool cpu_idle = 2;
 
   // Determines whether CPU should be boosted on startup of a new container
@@ -208,6 +210,12 @@ message Volume {
 
     // Ephemeral storage used as a shared volume.
     EmptyDirVolumeSource empty_dir = 4;
+
+    // For NFS Voumes, contains the path to the nfs Volume
+    NFSVolumeSource nfs = 5;
+
+    // Persistent storage backed by a Google Cloud Storage bucket.
+    GCSVolumeSource gcs = 6;
   }
 }
 
@@ -322,6 +330,27 @@ message EmptyDirVolumeSource {
   string size_limit = 2;
 }
 
+// Represents an NFS mount.
+message NFSVolumeSource {
+  // Hostname or IP address of the NFS server
+  string server = 1;
+
+  // Path that is exported by the NFS server.
+  string path = 2;
+
+  // If true, mount the NFS volume as read only
+  bool read_only = 3;
+}
+
+// Represents a GCS Bucket mounted as a volume.
+message GCSVolumeSource {
+  // GCS Bucket name
+  string bucket = 1;
+
+  // If true, mount the GCS bucket as read-only
+  bool read_only = 2;
+}
+
 // Probe describes a health check to be performed against a container to
 // determine whether it is alive or ready to receive traffic.
 message Probe {
diff --git a/google/cloud/run/v2/revision.proto b/google/cloud/run/v2/revision.proto
@@ -24,6 +24,7 @@ import "google/api/resource.proto";
 import "google/api/routing.proto";
 import "google/cloud/run/v2/condition.proto";
 import "google/cloud/run/v2/k8s.min.proto";
+import "google/cloud/run/v2/status.proto";
 import "google/cloud/run/v2/vendor_settings.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/duration.proto";
@@ -293,6 +294,10 @@ message Revision {
   // Enable session affinity.
   bool session_affinity = 38;
 
+  // Output only. The current effective scaling settings for the revision.
+  RevisionScalingStatus scaling_status = 39
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
   // Output only. A system-generated fingerprint for this version of the
   // resource. May be used to detect modification conflict during updates.
   string etag = 99 [(google.api.field_behavior) = OUTPUT_ONLY];
diff --git a/google/cloud/run/v2/revision_template.proto b/google/cloud/run/v2/revision_template.proto
@@ -16,6 +16,7 @@ syntax = "proto3";
 
 package google.cloud.run.v2;
 
+import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 import "google/cloud/run/v2/k8s.min.proto";
 import "google/cloud/run/v2/vendor_settings.proto";
@@ -98,6 +99,9 @@ message RevisionTemplate {
   // Sets the maximum number of requests that each serving instance can receive.
   int32 max_instance_request_concurrency = 15;
 
-  // Enable session affinity.
-  bool session_affinity = 19;
+  // Optional. Enable session affinity.
+  bool session_affinity = 19 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Disables health checking containers during deployment.
+  bool health_check_disabled = 20 [(google.api.field_behavior) = OPTIONAL];
 }
diff --git a/google/cloud/run/v2/service.proto b/google/cloud/run/v2/service.proto
@@ -301,23 +301,22 @@ message Service {
   // APIs, its JSON representation will be a `string` instead of an `integer`.
   int64 generation = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
 
-  // Unstructured key value map that can be used to organize and categorize
-  // objects.
-  // User-provided labels are shared with Google's billing system, so they can
-  // be used to filter, or break down billing charges by team, component,
-  // environment, state, etc. For more information, visit
+  // Optional. Unstructured key value map that can be used to organize and
+  // categorize objects. User-provided labels are shared with Google's billing
+  // system, so they can be used to filter, or break down billing charges by
+  // team, component, environment, state, etc. For more information, visit
   // https://cloud.google.com/resource-manager/docs/creating-managing-labels or
   // https://cloud.google.com/run/docs/configuring/labels.
   //
   // <p>Cloud Run API v2 does not support labels with  `run.googleapis.com`,
   // `cloud.googleapis.com`, `serving.knative.dev`, or `autoscaling.knative.dev`
   // namespaces, and they will be rejected. All system labels in v1 now have a
   // corresponding field in v2 Service.
-  map<string, string> labels = 5;
+  map<string, string> labels = 5 [(google.api.field_behavior) = OPTIONAL];
 
-  // Unstructured key value map that may be set by external tools to store and
-  // arbitrary metadata. They are not queryable and should be preserved
-  // when modifying objects.
+  // Optional. Unstructured key value map that may be set by external tools to
+  // store and arbitrary metadata. They are not queryable and should be
+  // preserved when modifying objects.
   //
   // <p>Cloud Run API v2 does not support annotations with `run.googleapis.com`,
   // `cloud.googleapis.com`, `serving.knative.dev`, or `autoscaling.knative.dev`
@@ -326,7 +325,7 @@ message Service {
   //
   // <p>This field follows Kubernetes
   // annotations' namespacing, limits, and rules.
-  map<string, string> annotations = 6;
+  map<string, string> annotations = 6 [(google.api.field_behavior) = OPTIONAL];
 
   // Output only. The creation time.
   google.protobuf.Timestamp create_time = 7
@@ -385,6 +384,12 @@ message Service {
   // 100% traffic to the latest `Ready` Revision.
   repeated TrafficTarget traffic = 19;
 
+  // Optional. Specifies service-level scaling settings
+  ServiceScaling scaling = 20 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Disables public resolution of the default URI of this service.
+  bool default_uri_disabled = 22 [(google.api.field_behavior) = OPTIONAL];
+
   // Output only. The generation of this Service currently serving traffic. See
   // comments in `reconciling` for additional information on reconciliation
   // process in Cloud Run. Please note that unlike v1, this is an int64 value.
diff --git a/google/cloud/run/v2/status.proto b/google/cloud/run/v2/status.proto
@@ -0,0 +1,28 @@
+// Copyright 2023 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package google.cloud.run.v2;
+
+option go_package = "cloud.google.com/go/run/apiv2/runpb;runpb";
+option java_multiple_files = true;
+option java_outer_classname = "StatusProto";
+option java_package = "com.google.cloud.run.v2";
+
+// Effective settings for the current revision
+message RevisionScalingStatus {
+  // The current number of min instances provisioned for this revision.
+  int32 desired_min_instance_count = 1;
+}
diff --git a/google/cloud/run/v2/vendor_settings.proto b/google/cloud/run/v2/vendor_settings.proto
@@ -16,7 +16,6 @@ syntax = "proto3";
 
 package google.cloud.run.v2;
 
-import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
 
 option go_package = "cloud.google.com/go/run/apiv2/runpb;runpb";
@@ -139,3 +138,12 @@ enum EncryptionKeyRevocationAction {
   // Shuts down existing instances, and prevents creation of new ones.
   SHUTDOWN = 2;
 }
+
+// Scaling settings applied at the service level rather than
+// at the revision level.
+message ServiceScaling {
+  // total min instances for the service. This number of instances is
+  // divided among all revisions with specified traffic based on the percent
+  // of traffic they are receiving. (BETA)
+  int32 min_instance_count = 1;
+}
