patch_jobs.proto 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739
  1. // Copyright 2020 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. // http://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. syntax = "proto3";
  15. package google.cloud.osconfig.v1;
  16. import "google/api/field_behavior.proto";
  17. import "google/api/resource.proto";
  18. import "google/cloud/osconfig/v1/osconfig_common.proto";
  19. import "google/protobuf/duration.proto";
  20. import "google/protobuf/timestamp.proto";
  21. option csharp_namespace = "Google.Cloud.OsConfig.V1";
  22. option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/v1;osconfig";
  23. option java_outer_classname = "PatchJobs";
  24. option java_package = "com.google.cloud.osconfig.v1";
  25. option php_namespace = "Google\\Cloud\\OsConfig\\V1";
  26. option ruby_package = "Google::Cloud::OsConfig::V1";
  27. // A request message to initiate patching across Compute Engine
  28. // instances.
  29. message ExecutePatchJobRequest {
  30. // Required. The project in which to run this patch in the form `projects/*`
  31. string parent = 1 [
  32. (google.api.field_behavior) = REQUIRED,
  33. (google.api.resource_reference) = {
  34. type: "cloudresourcemanager.googleapis.com/Project"
  35. }
  36. ];
  37. // Description of the patch job. Length of the description is limited
  38. // to 1024 characters.
  39. string description = 2;
  40. // Required. Instances to patch, either explicitly or filtered by some
  41. // criteria such as zone or labels.
  42. PatchInstanceFilter instance_filter = 7
  43. [(google.api.field_behavior) = REQUIRED];
  44. // Patch configuration being applied. If omitted, instances are
  45. // patched using the default configurations.
  46. PatchConfig patch_config = 4;
  47. // Duration of the patch job. After the duration ends, the patch job
  48. // times out.
  49. google.protobuf.Duration duration = 5;
  50. // If this patch is a dry-run only, instances are contacted but
  51. // will do nothing.
  52. bool dry_run = 6;
  53. // Display name for this patch job. This does not have to be unique.
  54. string display_name = 8;
  55. // Rollout strategy of the patch job.
  56. PatchRollout rollout = 9;
  57. }
  58. // Request to get an active or completed patch job.
  59. message GetPatchJobRequest {
  60. // Required. Name of the patch in the form `projects/*/patchJobs/*`
  61. string name = 1 [
  62. (google.api.field_behavior) = REQUIRED,
  63. (google.api.resource_reference) = {
  64. type: "osconfig.googleapis.com/PatchJob"
  65. }
  66. ];
  67. }
  68. // Request to list details for all instances that are part of a patch job.
  69. message ListPatchJobInstanceDetailsRequest {
  70. // Required. The parent for the instances are in the form of
  71. // `projects/*/patchJobs/*`.
  72. string parent = 1 [
  73. (google.api.field_behavior) = REQUIRED,
  74. (google.api.resource_reference) = {
  75. type: "osconfig.googleapis.com/PatchJob"
  76. }
  77. ];
  78. // The maximum number of instance details records to return. Default is 100.
  79. int32 page_size = 2;
  80. // A pagination token returned from a previous call
  81. // that indicates where this listing should continue from.
  82. string page_token = 3;
  83. // A filter expression that filters results listed in the response. This
  84. // field supports filtering results by instance zone, name, state, or
  85. // `failure_reason`.
  86. string filter = 4;
  87. }
  88. // A response message for listing the instances details for a patch job.
  89. message ListPatchJobInstanceDetailsResponse {
  90. // A list of instance status.
  91. repeated PatchJobInstanceDetails patch_job_instance_details = 1;
  92. // A pagination token that can be used to get the next page of results.
  93. string next_page_token = 2;
  94. }
  95. // Patch details for a VM instance. For more information about reviewing VM
  96. // instance details, see
  97. // [Listing all VM instance details for a specific patch
  98. // job](https://cloud.google.com/compute/docs/os-patch-management/manage-patch-jobs#list-instance-details).
  99. message PatchJobInstanceDetails {
  100. // The instance name in the form `projects/*/zones/*/instances/*`
  101. string name = 1 [(google.api.resource_reference) = {
  102. type: "compute.googleapis.com/Instance"
  103. }];
  104. // The unique identifier for the instance. This identifier is
  105. // defined by the server.
  106. string instance_system_id = 2;
  107. // Current state of instance patch.
  108. Instance.PatchState state = 3;
  109. // If the patch fails, this field provides the reason.
  110. string failure_reason = 4;
  111. // The number of times the agent that the agent attempts to apply the patch.
  112. int64 attempt_count = 5;
  113. }
  114. // A request message for listing patch jobs.
  115. message ListPatchJobsRequest {
  116. // Required. In the form of `projects/*`
  117. string parent = 1 [
  118. (google.api.field_behavior) = REQUIRED,
  119. (google.api.resource_reference) = {
  120. type: "cloudresourcemanager.googleapis.com/Project"
  121. }
  122. ];
  123. // The maximum number of instance status to return.
  124. int32 page_size = 2;
  125. // A pagination token returned from a previous call
  126. // that indicates where this listing should continue from.
  127. string page_token = 3;
  128. // If provided, this field specifies the criteria that must be met by patch
  129. // jobs to be included in the response.
  130. // Currently, filtering is only available on the patch_deployment field.
  131. string filter = 4;
  132. }
  133. // A response message for listing patch jobs.
  134. message ListPatchJobsResponse {
  135. // The list of patch jobs.
  136. repeated PatchJob patch_jobs = 1;
  137. // A pagination token that can be used to get the next page of results.
  138. string next_page_token = 2;
  139. }
  140. // A high level representation of a patch job that is either in progress
  141. // or has completed.
  142. //
  143. // Instance details are not included in the job. To paginate through instance
  144. // details, use ListPatchJobInstanceDetails.
  145. //
  146. // For more information about patch jobs, see
  147. // [Creating patch
  148. // jobs](https://cloud.google.com/compute/docs/os-patch-management/create-patch-job).
  149. message PatchJob {
  150. option (google.api.resource) = {
  151. type: "osconfig.googleapis.com/PatchJob"
  152. pattern: "projects/{project}/patchJobs/{patch_job}"
  153. };
  154. // A summary of the current patch state across all instances that this patch
  155. // job affects. Contains counts of instances in different states. These states
  156. // map to `InstancePatchState`. List patch job instance details to see the
  157. // specific states of each instance.
  158. message InstanceDetailsSummary {
  159. // Number of instances pending patch job.
  160. int64 pending_instance_count = 1;
  161. // Number of instances that are inactive.
  162. int64 inactive_instance_count = 2;
  163. // Number of instances notified about patch job.
  164. int64 notified_instance_count = 3;
  165. // Number of instances that have started.
  166. int64 started_instance_count = 4;
  167. // Number of instances that are downloading patches.
  168. int64 downloading_patches_instance_count = 5;
  169. // Number of instances that are applying patches.
  170. int64 applying_patches_instance_count = 6;
  171. // Number of instances rebooting.
  172. int64 rebooting_instance_count = 7;
  173. // Number of instances that have completed successfully.
  174. int64 succeeded_instance_count = 8;
  175. // Number of instances that require reboot.
  176. int64 succeeded_reboot_required_instance_count = 9;
  177. // Number of instances that failed.
  178. int64 failed_instance_count = 10;
  179. // Number of instances that have acked and will start shortly.
  180. int64 acked_instance_count = 11;
  181. // Number of instances that exceeded the time out while applying the patch.
  182. int64 timed_out_instance_count = 12;
  183. // Number of instances that are running the pre-patch step.
  184. int64 pre_patch_step_instance_count = 13;
  185. // Number of instances that are running the post-patch step.
  186. int64 post_patch_step_instance_count = 14;
  187. // Number of instances that do not appear to be running the agent. Check to
  188. // ensure that the agent is installed, running, and able to communicate with
  189. // the service.
  190. int64 no_agent_detected_instance_count = 15;
  191. }
  192. // Enumeration of the various states a patch job passes through as it
  193. // executes.
  194. enum State {
  195. // State must be specified.
  196. STATE_UNSPECIFIED = 0;
  197. // The patch job was successfully initiated.
  198. STARTED = 1;
  199. // The patch job is looking up instances to run the patch on.
  200. INSTANCE_LOOKUP = 2;
  201. // Instances are being patched.
  202. PATCHING = 3;
  203. // Patch job completed successfully.
  204. SUCCEEDED = 4;
  205. // Patch job completed but there were errors.
  206. COMPLETED_WITH_ERRORS = 5;
  207. // The patch job was canceled.
  208. CANCELED = 6;
  209. // The patch job timed out.
  210. TIMED_OUT = 7;
  211. }
  212. // Unique identifier for this patch job in the form
  213. // `projects/*/patchJobs/*`
  214. string name = 1;
  215. // Display name for this patch job. This is not a unique identifier.
  216. string display_name = 14;
  217. // Description of the patch job. Length of the description is limited
  218. // to 1024 characters.
  219. string description = 2;
  220. // Time this patch job was created.
  221. google.protobuf.Timestamp create_time = 3;
  222. // Last time this patch job was updated.
  223. google.protobuf.Timestamp update_time = 4;
  224. // The current state of the PatchJob.
  225. State state = 5;
  226. // Instances to patch.
  227. PatchInstanceFilter instance_filter = 13;
  228. // Patch configuration being applied.
  229. PatchConfig patch_config = 7;
  230. // Duration of the patch job. After the duration ends, the
  231. // patch job times out.
  232. google.protobuf.Duration duration = 8;
  233. // Summary of instance details.
  234. InstanceDetailsSummary instance_details_summary = 9;
  235. // If this patch job is a dry run, the agent reports that it has
  236. // finished without running any updates on the VM instance.
  237. bool dry_run = 10;
  238. // If this patch job failed, this message provides information about the
  239. // failure.
  240. string error_message = 11;
  241. // Reflects the overall progress of the patch job in the range of
  242. // 0.0 being no progress to 100.0 being complete.
  243. double percent_complete = 12;
  244. // Output only. Name of the patch deployment that created this patch job.
  245. string patch_deployment = 15 [
  246. (google.api.field_behavior) = OUTPUT_ONLY,
  247. (google.api.resource_reference) = {
  248. type: "osconfig.googleapis.com/PatchDeployment"
  249. }
  250. ];
  251. // Rollout strategy being applied.
  252. PatchRollout rollout = 16;
  253. }
  254. // Patch configuration specifications. Contains details on how to apply the
  255. // patch(es) to a VM instance.
  256. message PatchConfig {
  257. // Post-patch reboot settings.
  258. enum RebootConfig {
  259. // The default behavior is DEFAULT.
  260. REBOOT_CONFIG_UNSPECIFIED = 0;
  261. // The agent decides if a reboot is necessary by checking signals such as
  262. // registry keys on Windows or `/var/run/reboot-required` on APT based
  263. // systems. On RPM based systems, a set of core system package install times
  264. // are compared with system boot time.
  265. DEFAULT = 1;
  266. // Always reboot the machine after the update completes.
  267. ALWAYS = 2;
  268. // Never reboot the machine after the update completes.
  269. NEVER = 3;
  270. }
  271. // Post-patch reboot settings.
  272. RebootConfig reboot_config = 1;
  273. // Apt update settings. Use this setting to override the default `apt` patch
  274. // rules.
  275. AptSettings apt = 3;
  276. // Yum update settings. Use this setting to override the default `yum` patch
  277. // rules.
  278. YumSettings yum = 4;
  279. // Goo update settings. Use this setting to override the default `goo` patch
  280. // rules.
  281. GooSettings goo = 5;
  282. // Zypper update settings. Use this setting to override the default `zypper`
  283. // patch rules.
  284. ZypperSettings zypper = 6;
  285. // Windows update settings. Use this override the default windows patch rules.
  286. WindowsUpdateSettings windows_update = 7;
  287. // The `ExecStep` to run before the patch update.
  288. ExecStep pre_step = 8;
  289. // The `ExecStep` to run after the patch update.
  290. ExecStep post_step = 9;
  291. }
  292. // Namespace for instance state enums.
  293. message Instance {
  294. // Patch state of an instance.
  295. enum PatchState {
  296. // Unspecified.
  297. PATCH_STATE_UNSPECIFIED = 0;
  298. // The instance is not yet notified.
  299. PENDING = 1;
  300. // Instance is inactive and cannot be patched.
  301. INACTIVE = 2;
  302. // The instance is notified that it should be patched.
  303. NOTIFIED = 3;
  304. // The instance has started the patching process.
  305. STARTED = 4;
  306. // The instance is downloading patches.
  307. DOWNLOADING_PATCHES = 5;
  308. // The instance is applying patches.
  309. APPLYING_PATCHES = 6;
  310. // The instance is rebooting.
  311. REBOOTING = 7;
  312. // The instance has completed applying patches.
  313. SUCCEEDED = 8;
  314. // The instance has completed applying patches but a reboot is required.
  315. SUCCEEDED_REBOOT_REQUIRED = 9;
  316. // The instance has failed to apply the patch.
  317. FAILED = 10;
  318. // The instance acked the notification and will start shortly.
  319. ACKED = 11;
  320. // The instance exceeded the time out while applying the patch.
  321. TIMED_OUT = 12;
  322. // The instance is running the pre-patch step.
  323. RUNNING_PRE_PATCH_STEP = 13;
  324. // The instance is running the post-patch step.
  325. RUNNING_POST_PATCH_STEP = 14;
  326. // The service could not detect the presence of the agent. Check to ensure
  327. // that the agent is installed, running, and able to communicate with the
  328. // service.
  329. NO_AGENT_DETECTED = 15;
  330. }
  331. }
  332. // Message for canceling a patch job.
  333. message CancelPatchJobRequest {
  334. // Required. Name of the patch in the form `projects/*/patchJobs/*`
  335. string name = 1 [
  336. (google.api.field_behavior) = REQUIRED,
  337. (google.api.resource_reference) = {
  338. type: "osconfig.googleapis.com/PatchJob"
  339. }
  340. ];
  341. }
  342. // Apt patching is completed by executing `apt-get update && apt-get
  343. // upgrade`. Additional options can be set to control how this is executed.
  344. message AptSettings {
  345. // Apt patch type.
  346. enum Type {
  347. // By default, upgrade will be performed.
  348. TYPE_UNSPECIFIED = 0;
  349. // Runs `apt-get dist-upgrade`.
  350. DIST = 1;
  351. // Runs `apt-get upgrade`.
  352. UPGRADE = 2;
  353. }
  354. // By changing the type to DIST, the patching is performed
  355. // using `apt-get dist-upgrade` instead.
  356. Type type = 1;
  357. // List of packages to exclude from update. These packages will be excluded
  358. repeated string excludes = 2;
  359. // An exclusive list of packages to be updated. These are the only packages
  360. // that will be updated. If these packages are not installed, they will be
  361. // ignored. This field cannot be specified with any other patch configuration
  362. // fields.
  363. repeated string exclusive_packages = 3;
  364. }
  365. // Yum patching is performed by executing `yum update`. Additional options
  366. // can be set to control how this is executed.
  367. //
  368. // Note that not all settings are supported on all platforms.
  369. message YumSettings {
  370. // Adds the `--security` flag to `yum update`. Not supported on
  371. // all platforms.
  372. bool security = 1;
  373. // Will cause patch to run `yum update-minimal` instead.
  374. bool minimal = 2;
  375. // List of packages to exclude from update. These packages are excluded by
  376. // using the yum `--exclude` flag.
  377. repeated string excludes = 3;
  378. // An exclusive list of packages to be updated. These are the only packages
  379. // that will be updated. If these packages are not installed, they will be
  380. // ignored. This field must not be specified with any other patch
  381. // configuration fields.
  382. repeated string exclusive_packages = 4;
  383. }
  384. // Googet patching is performed by running `googet update`.
  385. message GooSettings {}
  386. // Zypper patching is performed by running `zypper patch`.
  387. // See also https://en.opensuse.org/SDB:Zypper_manual.
  388. message ZypperSettings {
  389. // Adds the `--with-optional` flag to `zypper patch`.
  390. bool with_optional = 1;
  391. // Adds the `--with-update` flag, to `zypper patch`.
  392. bool with_update = 2;
  393. // Install only patches with these categories.
  394. // Common categories include security, recommended, and feature.
  395. repeated string categories = 3;
  396. // Install only patches with these severities.
  397. // Common severities include critical, important, moderate, and low.
  398. repeated string severities = 4;
  399. // List of patches to exclude from update.
  400. repeated string excludes = 5;
  401. // An exclusive list of patches to be updated. These are the only patches
  402. // that will be installed using 'zypper patch patch:<patch_name>' command.
  403. // This field must not be used with any other patch configuration fields.
  404. repeated string exclusive_patches = 6;
  405. }
  406. // Windows patching is performed using the Windows Update Agent.
  407. message WindowsUpdateSettings {
  408. // Microsoft Windows update classifications as defined in
  409. // [1]
  410. // https://support.microsoft.com/en-us/help/824684/description-of-the-standard-terminology-that-is-used-to-describe-micro
  411. enum Classification {
  412. // Invalid. If classifications are included, they must be specified.
  413. CLASSIFICATION_UNSPECIFIED = 0;
  414. // "A widely released fix for a specific problem that addresses a critical,
  415. // non-security-related bug." [1]
  416. CRITICAL = 1;
  417. // "A widely released fix for a product-specific, security-related
  418. // vulnerability. Security vulnerabilities are rated by their severity. The
  419. // severity rating is indicated in the Microsoft security bulletin as
  420. // critical, important, moderate, or low." [1]
  421. SECURITY = 2;
  422. // "A widely released and frequent software update that contains additions
  423. // to a product's definition database. Definition databases are often used
  424. // to detect objects that have specific attributes, such as malicious code,
  425. // phishing websites, or junk mail." [1]
  426. DEFINITION = 3;
  427. // "Software that controls the input and output of a device." [1]
  428. DRIVER = 4;
  429. // "New product functionality that is first distributed outside the context
  430. // of a product release and that is typically included in the next full
  431. // product release." [1]
  432. FEATURE_PACK = 5;
  433. // "A tested, cumulative set of all hotfixes, security updates, critical
  434. // updates, and updates. Additionally, service packs may contain additional
  435. // fixes for problems that are found internally since the release of the
  436. // product. Service packs my also contain a limited number of
  437. // customer-requested design changes or features." [1]
  438. SERVICE_PACK = 6;
  439. // "A utility or feature that helps complete a task or set of tasks." [1]
  440. TOOL = 7;
  441. // "A tested, cumulative set of hotfixes, security updates, critical
  442. // updates, and updates that are packaged together for easy deployment. A
  443. // rollup generally targets a specific area, such as security, or a
  444. // component of a product, such as Internet Information Services (IIS)." [1]
  445. UPDATE_ROLLUP = 8;
  446. // "A widely released fix for a specific problem. An update addresses a
  447. // noncritical, non-security-related bug." [1]
  448. UPDATE = 9;
  449. }
  450. // Only apply updates of these windows update classifications. If empty, all
  451. // updates are applied.
  452. repeated Classification classifications = 1;
  453. // List of KBs to exclude from update.
  454. repeated string excludes = 2;
  455. // An exclusive list of kbs to be updated. These are the only patches
  456. // that will be updated. This field must not be used with other
  457. // patch configurations.
  458. repeated string exclusive_patches = 3;
  459. }
  460. // A step that runs an executable for a PatchJob.
  461. message ExecStep {
  462. // The ExecStepConfig for all Linux VMs targeted by the PatchJob.
  463. ExecStepConfig linux_exec_step_config = 1;
  464. // The ExecStepConfig for all Windows VMs targeted by the PatchJob.
  465. ExecStepConfig windows_exec_step_config = 2;
  466. }
  467. // Common configurations for an ExecStep.
  468. message ExecStepConfig {
  469. // The interpreter used to execute the a file.
  470. enum Interpreter {
  471. // Invalid for a Windows ExecStepConfig. For a Linux ExecStepConfig, the
  472. // interpreter will be parsed from the shebang line of the script if
  473. // unspecified.
  474. INTERPRETER_UNSPECIFIED = 0;
  475. // Indicates that the script is run with `/bin/sh` on Linux and `cmd`
  476. // on Windows.
  477. SHELL = 1;
  478. // Indicates that the file is run with PowerShell flags
  479. // `-NonInteractive`, `-NoProfile`, and `-ExecutionPolicy Bypass`.
  480. POWERSHELL = 2;
  481. }
  482. // Location of the executable.
  483. oneof executable {
  484. // An absolute path to the executable on the VM.
  485. string local_path = 1;
  486. // A Cloud Storage object containing the executable.
  487. GcsObject gcs_object = 2;
  488. }
  489. // Defaults to [0]. A list of possible return values that the
  490. // execution can return to indicate a success.
  491. repeated int32 allowed_success_codes = 3;
  492. // The script interpreter to use to run the script. If no interpreter is
  493. // specified the script will be executed directly, which will likely
  494. // only succeed for scripts with [shebang lines]
  495. // (https://en.wikipedia.org/wiki/Shebang_\(Unix\)).
  496. Interpreter interpreter = 4;
  497. }
  498. // Cloud Storage object representation.
  499. message GcsObject {
  500. // Required. Bucket of the Cloud Storage object.
  501. string bucket = 1 [(google.api.field_behavior) = REQUIRED];
  502. // Required. Name of the Cloud Storage object.
  503. string object = 2 [(google.api.field_behavior) = REQUIRED];
  504. // Required. Generation number of the Cloud Storage object. This is used to
  505. // ensure that the ExecStep specified by this PatchJob does not change.
  506. int64 generation_number = 3 [(google.api.field_behavior) = REQUIRED];
  507. }
  508. // A filter to target VM instances for patching. The targeted
  509. // VMs must meet all criteria specified. So if both labels and zones are
  510. // specified, the patch job targets only VMs with those labels and in those
  511. // zones.
  512. message PatchInstanceFilter {
  513. // Targets a group of VM instances by using their [assigned
  514. // labels](https://cloud.google.com/compute/docs/labeling-resources). Labels
  515. // are key-value pairs. A `GroupLabel` is a combination of labels
  516. // that is used to target VMs for a patch job.
  517. //
  518. // For example, a patch job can target VMs that have the following
  519. // `GroupLabel`: `{"env":"test", "app":"web"}`. This means that the patch job
  520. // is applied to VMs that have both the labels `env=test` and `app=web`.
  521. message GroupLabel {
  522. // Compute Engine instance labels that must be present for a VM
  523. // instance to be targeted by this filter.
  524. map<string, string> labels = 1;
  525. }
  526. // Target all VM instances in the project. If true, no other criteria is
  527. // permitted.
  528. bool all = 1;
  529. // Targets VM instances matching ANY of these GroupLabels. This allows
  530. // targeting of disparate groups of VM instances.
  531. repeated GroupLabel group_labels = 2;
  532. // Targets VM instances in ANY of these zones. Leave empty to target VM
  533. // instances in any zone.
  534. repeated string zones = 3;
  535. // Targets any of the VM instances specified. Instances are specified by their
  536. // URI in the form `zones/[ZONE]/instances/[INSTANCE_NAME]`,
  537. // `projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]`, or
  538. // `https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances/[INSTANCE_NAME]`
  539. repeated string instances = 4;
  540. // Targets VMs whose name starts with one of these prefixes. Similar to
  541. // labels, this is another way to group VMs when targeting configs, for
  542. // example prefix="prod-".
  543. repeated string instance_name_prefixes = 5;
  544. }
  545. // Patch rollout configuration specifications. Contains details on the
  546. // concurrency control when applying patch(es) to all targeted VMs.
  547. message PatchRollout {
  548. // Type of the rollout.
  549. enum Mode {
  550. // Mode must be specified.
  551. MODE_UNSPECIFIED = 0;
  552. // Patches are applied one zone at a time. The patch job begins in the
  553. // region with the lowest number of targeted VMs. Within the region,
  554. // patching begins in the zone with the lowest number of targeted VMs. If
  555. // multiple regions (or zones within a region) have the same number of
  556. // targeted VMs, a tie-breaker is achieved by sorting the regions or zones
  557. // in alphabetical order.
  558. ZONE_BY_ZONE = 1;
  559. // Patches are applied to VMs in all zones at the same time.
  560. CONCURRENT_ZONES = 2;
  561. }
  562. // Mode of the patch rollout.
  563. Mode mode = 1;
  564. // The maximum number (or percentage) of VMs per zone to disrupt at any given
  565. // moment. The number of VMs calculated from multiplying the percentage by the
  566. // total number of VMs in a zone is rounded up.
  567. //
  568. // During patching, a VM is considered disrupted from the time the agent is
  569. // notified to begin until patching has completed. This disruption time
  570. // includes the time to complete reboot and any post-patch steps.
  571. //
  572. // A VM contributes to the disruption budget if its patching operation fails
  573. // either when applying the patches, running pre or post patch steps, or if it
  574. // fails to respond with a success notification before timing out. VMs that
  575. // are not running or do not have an active agent do not count toward this
  576. // disruption budget.
  577. //
  578. // For zone-by-zone rollouts, if the disruption budget in a zone is exceeded,
  579. // the patch job stops, because continuing to the next zone requires
  580. // completion of the patch process in the previous zone.
  581. //
  582. // For example, if the disruption budget has a fixed value of `10`, and 8 VMs
  583. // fail to patch in the current zone, the patch job continues to patch 2 VMs
  584. // at a time until the zone is completed. When that zone is completed
  585. // successfully, patching begins with 10 VMs at a time in the next zone. If 10
  586. // VMs in the next zone fail to patch, the patch job stops.
  587. FixedOrPercent disruption_budget = 2;
  588. }