Agentendpoint API: minor doc updates, addition of exclusive_packages|patches to PatchConfigs.

PiperOrigin-RevId: 279326626

google/cloud/osconfig/agentendpoint/v1beta/agentendpoint.proto

@@ -31,23 +31,19 @@ service AgentEndpointService {
   option (google.api.default_host) = "osconfig.googleapis.com";
 
   // Stream established by client to receive Task notifications.
-  // This method is called by an agent and not an active developer method..
   rpc ReceiveTaskNotification(ReceiveTaskNotificationRequest) returns (stream ReceiveTaskNotificationResponse) {
   }
 
   // Signals the start of a task execution and returns the task info.
-  // This method is called by an agent and not an active developer method..
   rpc ReportTaskStart(ReportTaskStartRequest) returns (ReportTaskStartResponse) {
   }
 
   // Signals an intermediary progress checkpoint in task execution.
-  // This method is called by an agent and not an active developer method..
   rpc ReportTaskProgress(ReportTaskProgressRequest) returns (ReportTaskProgressResponse) {
   }
 
   // Signals that the task execution is complete and optionally returns the next
   // task.
-  // This method is called by an agent and not an active developer method..
   rpc ReportTaskComplete(ReportTaskCompleteRequest) returns (ReportTaskCompleteResponse) {
   }
 }
@@ -63,8 +59,8 @@ message ReceiveTaskNotificationRequest {
   string agent_version = 2 [(google.api.field_behavior) = REQUIRED];
 }
 
-// The streaming rpc message that will notify the agent when it has a task
-// it needs to perform on the instance.
+// The streaming rpc message that notifies the agent when it has a task
+// that it needs to perform on the VM instance.
 message ReceiveTaskNotificationResponse {
 
 }
@@ -130,8 +126,8 @@ message ReportTaskCompleteRequest {
 
   // Required. The type of task to report completed.
   //
-  // Output must include the appropriate message based on this enum as
-  // specified below:
+  // The output must include the appropriate message based on the following
+  // enum values:
   // APPLY_PATCHES = ApplyPatchesTaskOutput
   // EXEC_STEP = ExecStepTaskOutput
   TaskType task_type = 3 [(google.api.field_behavior) = REQUIRED];

google/cloud/osconfig/agentendpoint/v1beta/agentendpoint_grpc_service_config.json

@@ -0,0 +1,22 @@
+{
+  "methodConfig": [{
+    "name": [{ "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService" }],
+    "timeout": "60s",
+    "retryPolicy": {
+      "maxAttempts": 5,
+      "initialBackoff": "1s",
+      "maxBackoff": "60s",
+      "backoffMultiplier": 1.3,
+      "retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"]
+    }
+  },
+  {
+    "name": [
+      { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReceiveTaskNotification" },
+      { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskStart" },
+      { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskProgress" },
+      { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskComplete" }
+    ],
+    "timeout": "60s"
+  }]
+}

google/cloud/osconfig/agentendpoint/v1beta/osconfig_v1beta.yaml

@@ -15,3 +15,5 @@ backend:
   rules:
   - selector: 'google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService.*'
     deadline: 30.0
+  - selector: google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService.ReceiveTaskNotification
+    deadline: 3600.0

google/cloud/osconfig/agentendpoint/v1beta/patch_jobs.proto

@@ -21,24 +21,24 @@ option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agente
 option java_outer_classname = "PatchJobs";
 option java_package = "com.google.cloud.osconfig.agentendpoint.v1beta";
 
-// Patch configuration specifications. Contains details on specifically how to
-// apply the patch(es) to an instance.
+// Patch configuration specifications. Contains details on how to
+// apply patches to a VM instance.
 message PatchConfig {
   // Post-patch reboot settings.
   enum RebootConfig {
     // The default behavior is DEFAULT.
     REBOOT_CONFIG_UNSPECIFIED = 0;
 
-    // The agent will decide if a reboot is necessary by checking well known
+    // The agent decides if a reboot is necessary by checking
     // signals such as registry keys on Windows or `/var/run/reboot-required` on
-    // APT based systems. On RPM based systems a set of core system package
-    // install times will be compared with system boot time.
+    // APT based systems. On RPM based systems, a set of core system package
+    // install times are compared with system boot time.
     DEFAULT = 1;
 
-    // Always reboot the machine after the update has completed.
+    // Always reboot the machine after the update completes.
     ALWAYS = 2;
 
-    // Never reboot the machine after the update has completed.
+    // Never reboot the machine after the update completes.
     NEVER = 3;
   }
 
@@ -77,16 +77,28 @@ message PatchConfig {
 message AptSettings {
   // Apt patch type.
   enum Type {
-    // By default, a full upgrade will be performed.
+    // By default, upgrade will be performed.
     TYPE_UNSPECIFIED = 0;
 
-    // run `apt-get dist-upgrade` instead.
+    // Runs `apt-get dist-upgrade`.
     DIST = 1;
+
+    // Runs `apt-get upgrade`.
+    UPGRADE = 2;
   }
 
   // By changing the type to DIST, the patching will be performed
   // using `apt-get dist-upgrade` instead.
   Type type = 1;
+
+  // List of packages to exclude from update.
+  repeated string excludes = 2;
+
+  // An exclusive list of packages to be updated. These are the only packages
+  // that will be updated. If these packages are not installed, they will be
+  // ignored. This field cannot be specified with any other patch configuration
+  // fields.
+  repeated string exclusive_packages = 3;
 }
 
 // Yum patching will be performed by executing `yum update`. Additional options
@@ -104,6 +116,12 @@ message YumSettings {
   // List of packages to exclude from update. These packages will be excluded by
   // using the yum `--exclude` flag.
   repeated string excludes = 3;
+
+  // An exclusive list of packages to be updated. These are the only packages
+  // that will be updated. If these packages are not installed, they will be
+  // ignored. This field must not be specified with any other patch
+  // configuration fields.
+  repeated string exclusive_packages = 4;
 }
 
 // Googet patching is performed by running `googet update`.
@@ -127,6 +145,14 @@ message ZypperSettings {
   // Install only patches with these severities.
   // Common severities include critical, important, moderate, and low.
   repeated string severities = 4;
+
+  // List of patches to exclude from update.
+  repeated string excludes = 5;
+
+  // An exclusive list of patches to be updated. These are the only patches
+  // that will be installed using 'zypper patch patch:<patch_name>' command.
+  // This field must not be used with any other patch configuration fields.
+  repeated string exclusive_patches = 6;
 }
 
 // Windows patching is performed using the Windows Update Agent.
@@ -189,6 +215,11 @@ message WindowsUpdateSettings {
 
   // List of KBs to exclude from update.
   repeated string excludes = 2;
+
+  // An exclusive list of kbs to be updated. These are the only patches
+  // that will be updated. This field must not be used with other
+  // patch configurations.
+  repeated string exclusive_patches = 3;
 }
 
 // The strategy for retrying failed patches during the patch window.
@@ -211,7 +242,9 @@ message ExecStep {
 message ExecStepConfig {
   // The interpreter used to execute the a file.
   enum Interpreter {
-    // Default value.
+    // Invalid for a Windows ExecStepConfig. For a Linux ExecStepConfig, the
+    // interpreter will be parsed from the shebang line of the script if
+    // unspecified.
     INTERPRETER_UNSPECIFIED = 0;
 
     // Indicates that the script will be run with /bin/sh on Linux and cmd

google/cloud/osconfig/agentendpoint/v1beta/tasks.proto

@@ -105,7 +105,7 @@ message ApplyPatchesTaskProgress {
     // The agent is currently applying patches.
     APPLYING_PATCHES = 2;
 
-    // The agent is currently rebooting the instance.
+    // The agent is currently rebooting the VM instance.
     REBOOTING = 3;
   }
 
@@ -159,7 +159,7 @@ message ExecStepTaskProgress {
 message ExecStepTaskOutput {
   // The final states of exec steps.
   enum State {
-    // Unspecified is invalid.s
+    // Unspecified is invalid.
     STATE_UNSPECIFIED = 0;
 
     // The exec step completed normally.
@@ -167,6 +167,9 @@ message ExecStepTaskOutput {
 
     // The exec step was terminated because it took too long.
     TIMED_OUT = 2;
+
+    // The exec step task was cancelled before it started.
+    CANCELLED = 3;
   }
 
   // Required. The final state of the exec step.