patch_jobs.proto 10.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288
  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.agentendpoint.v1;
  16. option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1;agentendpoint";
  17. option java_outer_classname = "PatchJobs";
  18. option java_package = "com.google.cloud.osconfig.agentendpoint.v1";
  19. // Patch configuration specifications. Contains details on how to
  20. // apply patches to a VM instance.
  21. message PatchConfig {
  22. // Post-patch reboot settings.
  23. enum RebootConfig {
  24. // The default behavior is DEFAULT.
  25. REBOOT_CONFIG_UNSPECIFIED = 0;
  26. // The agent decides if a reboot is necessary by checking
  27. // signals such as registry keys on Windows or `/var/run/reboot-required` on
  28. // APT based systems. On RPM based systems, a set of core system package
  29. // install times are compared with system boot time.
  30. DEFAULT = 1;
  31. // Always reboot the machine after the update completes.
  32. ALWAYS = 2;
  33. // Never reboot the machine after the update completes.
  34. NEVER = 3;
  35. }
  36. // Post-patch reboot settings.
  37. RebootConfig reboot_config = 1;
  38. // Retry strategy can be defined to have the agent retry patching
  39. // during the window if patching fails. If omitted, the agent will use its
  40. // default retry strategy.
  41. RetryStrategy retry_strategy = 2;
  42. // Apt update settings. Use this override the default apt patch rules.
  43. AptSettings apt = 3;
  44. // Yum update settings. Use this override the default yum patch rules.
  45. YumSettings yum = 4;
  46. // Goo update settings. Use this override the default goo patch rules.
  47. GooSettings goo = 5;
  48. // Zypper update settings. Use this override the default zypper patch rules.
  49. ZypperSettings zypper = 6;
  50. // Windows update settings. Use this override the default windows patch rules.
  51. WindowsUpdateSettings windows_update = 7;
  52. // The ExecStep to run before the patch update.
  53. ExecStep pre_step = 8;
  54. // The ExecStep to run after the patch update.
  55. ExecStep post_step = 9;
  56. }
  57. // Apt patching will be performed by executing `apt-get update && apt-get
  58. // upgrade`. Additional options can be set to control how this is executed.
  59. message AptSettings {
  60. // Apt patch type.
  61. enum Type {
  62. // By default, upgrade will be performed.
  63. TYPE_UNSPECIFIED = 0;
  64. // Runs `apt-get dist-upgrade`.
  65. DIST = 1;
  66. // Runs `apt-get upgrade`.
  67. UPGRADE = 2;
  68. }
  69. // By changing the type to DIST, the patching will be performed
  70. // using `apt-get dist-upgrade` instead.
  71. Type type = 1;
  72. // List of packages to exclude from update.
  73. repeated string excludes = 2;
  74. // An exclusive list of packages to be updated. These are the only packages
  75. // that will be updated. If these packages are not installed, they will be
  76. // ignored. This field cannot be specified with any other patch configuration
  77. // fields.
  78. repeated string exclusive_packages = 3;
  79. }
  80. // Yum patching will be performed by executing `yum update`. Additional options
  81. // can be set to control how this is executed.
  82. //
  83. // Note that not all settings are supported on all platforms.
  84. message YumSettings {
  85. // Adds the `--security` flag to `yum update`. Not supported on
  86. // all platforms.
  87. bool security = 1;
  88. // Will cause patch to run `yum update-minimal` instead.
  89. bool minimal = 2;
  90. // List of packages to exclude from update. These packages will be excluded by
  91. // using the yum `--exclude` flag.
  92. repeated string excludes = 3;
  93. // An exclusive list of packages to be updated. These are the only packages
  94. // that will be updated. If these packages are not installed, they will be
  95. // ignored. This field must not be specified with any other patch
  96. // configuration fields.
  97. repeated string exclusive_packages = 4;
  98. }
  99. // Googet patching is performed by running `googet update`.
  100. message GooSettings {
  101. }
  102. // Zypper patching is performed by running `zypper patch`.
  103. // See also https://en.opensuse.org/SDB:Zypper_manual.
  104. message ZypperSettings {
  105. // Adds the `--with-optional` flag to `zypper patch`.
  106. bool with_optional = 1;
  107. // Adds the `--with-update` flag, to `zypper patch`.
  108. bool with_update = 2;
  109. // Install only patches with these categories.
  110. // Common categories include security, recommended, and feature.
  111. repeated string categories = 3;
  112. // Install only patches with these severities.
  113. // Common severities include critical, important, moderate, and low.
  114. repeated string severities = 4;
  115. // List of patches to exclude from update.
  116. repeated string excludes = 5;
  117. // An exclusive list of patches to be updated. These are the only patches
  118. // that will be installed using 'zypper patch patch:<patch_name>' command.
  119. // This field must not be used with any other patch configuration fields.
  120. repeated string exclusive_patches = 6;
  121. }
  122. // Windows patching is performed using the Windows Update Agent.
  123. message WindowsUpdateSettings {
  124. // Microsoft Windows update classifications as defined in
  125. // [1]
  126. // https://support.microsoft.com/en-us/help/824684/description-of-the-standard-terminology-that-is-used-to-describe-micro
  127. enum Classification {
  128. // Invalid. If classifications are included, they must be specified.
  129. CLASSIFICATION_UNSPECIFIED = 0;
  130. // "A widely released fix for a specific problem that addresses a critical,
  131. // non-security-related bug." [1]
  132. CRITICAL = 1;
  133. // "A widely released fix for a product-specific, security-related
  134. // vulnerability. Security vulnerabilities are rated by their severity. The
  135. // severity rating is indicated in the Microsoft security bulletin as
  136. // critical, important, moderate, or low." [1]
  137. SECURITY = 2;
  138. // "A widely released and frequent software update that contains additions
  139. // to a product’s definition database. Definition databases are often used
  140. // to detect objects that have specific attributes, such as malicious code,
  141. // phishing websites, or junk mail." [1]
  142. DEFINITION = 3;
  143. // "Software that controls the input and output of a device." [1]
  144. DRIVER = 4;
  145. // "New product functionality that is first distributed outside the context
  146. // of a product release and that is typically included in the next full
  147. // product release." [1]
  148. FEATURE_PACK = 5;
  149. // "A tested, cumulative set of all hotfixes, security updates, critical
  150. // updates, and updates. Additionally, service packs may contain additional
  151. // fixes for problems that are found internally since the release of the
  152. // product. Service packs my also contain a limited number of
  153. // customer-requested design changes or features." [1]
  154. SERVICE_PACK = 6;
  155. // "A utility or feature that helps complete a task or set of tasks." [1]
  156. TOOL = 7;
  157. // "A tested, cumulative set of hotfixes, security updates, critical
  158. // updates, and updates that are packaged together for easy deployment. A
  159. // rollup generally targets a specific area, such as security, or a
  160. // component of a product, such as Internet Information Services (IIS)." [1]
  161. UPDATE_ROLLUP = 8;
  162. // "A widely released fix for a specific problem. An update addresses a
  163. // noncritical, non-security-related bug." [1]
  164. UPDATE = 9;
  165. }
  166. // Only apply updates of these windows update classifications. If empty, all
  167. // updates will be applied.
  168. repeated Classification classifications = 1;
  169. // List of KBs to exclude from update.
  170. repeated string excludes = 2;
  171. // An exclusive list of kbs to be updated. These are the only patches
  172. // that will be updated. This field must not be used with other
  173. // patch configurations.
  174. repeated string exclusive_patches = 3;
  175. }
  176. // The strategy for retrying failed patches during the patch window.
  177. message RetryStrategy {
  178. // If true, the agent will continue to try and patch until the window has
  179. // ended.
  180. bool enabled = 1;
  181. }
  182. // A step that runs an executable for a PatchJob.
  183. message ExecStep {
  184. // The ExecStepConfig for all Linux VMs targeted by the PatchJob.
  185. ExecStepConfig linux_exec_step_config = 1;
  186. // The ExecStepConfig for all Windows VMs targeted by the PatchJob.
  187. ExecStepConfig windows_exec_step_config = 2;
  188. }
  189. // Common configurations for an ExecStep.
  190. message ExecStepConfig {
  191. // The interpreter used to execute the a file.
  192. enum Interpreter {
  193. // Invalid for a Windows ExecStepConfig. For a Linux ExecStepConfig, the
  194. // interpreter will be parsed from the shebang line of the script if
  195. // unspecified.
  196. INTERPRETER_UNSPECIFIED = 0;
  197. // Indicates that the script will be run with /bin/sh on Linux and cmd
  198. // on windows.
  199. SHELL = 1;
  200. // Indicates that the file will be run with PowerShell.
  201. POWERSHELL = 2;
  202. }
  203. // Location of the executable.
  204. oneof executable {
  205. // An absolute path to the executable on the VM.
  206. string local_path = 1;
  207. // A GCS object containing the executable.
  208. GcsObject gcs_object = 2;
  209. }
  210. // Defaults to [0]. A list of possible return values that the
  211. // execution can return to indicate a success.
  212. repeated int32 allowed_success_codes = 3;
  213. // The script interpreter to use to run the script. If no interpreter is
  214. // specified the script will be executed directly, which will likely
  215. // only succeed for scripts with shebang lines.
  216. // [Wikipedia shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)).
  217. Interpreter interpreter = 4;
  218. }
  219. // GCS object representation.
  220. message GcsObject {
  221. // Bucket of the GCS object.
  222. string bucket = 1;
  223. // Name of the GCS object.
  224. string object = 2;
  225. // Generation number of the GCS object. This is used to ensure that the
  226. // ExecStep specified by this PatchJob does not change.
  227. int64 generation_number = 3;
  228. }