os_policy.proto 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535
  1. // Copyright 2021 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.v1alpha;
  16. import "google/api/field_behavior.proto";
  17. option csharp_namespace = "Google.Cloud.OsConfig.V1Alpha";
  18. option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/v1alpha;osconfig";
  19. option java_multiple_files = true;
  20. option java_outer_classname = "OSPolicyProto";
  21. option java_package = "com.google.cloud.osconfig.v1alpha";
  22. option php_namespace = "Google\\Cloud\\OsConfig\\V1alpha";
  23. option ruby_package = "Google::Cloud::OsConfig::V1alpha";
  24. // An OS policy defines the desired state configuration for a VM.
  25. message OSPolicy {
  26. // The `OSFilter` is used to specify the OS filtering criteria for the
  27. // resource group.
  28. message OSFilter {
  29. // This should match OS short name emitted by the OS inventory agent.
  30. // An empty value matches any OS.
  31. string os_short_name = 1;
  32. // This value should match the version emitted by the OS inventory
  33. // agent.
  34. // Prefix matches are supported if asterisk(*) is provided as the
  35. // last character. For example, to match all versions with a major
  36. // version of `7`, specify the following value for this field `7.*`
  37. string os_version = 2;
  38. }
  39. // An OS policy resource is used to define the desired state configuration
  40. // and provides a specific functionality like installing/removing packages,
  41. // executing a script etc.
  42. //
  43. // The system ensures that resources are always in their desired state by
  44. // taking necessary actions if they have drifted from their desired state.
  45. message Resource {
  46. // A remote or local file.
  47. message File {
  48. // Specifies a file available via some URI.
  49. message Remote {
  50. // Required. URI from which to fetch the object. It should contain both the
  51. // protocol and path following the format `{protocol}://{location}`.
  52. string uri = 1 [(google.api.field_behavior) = REQUIRED];
  53. // SHA256 checksum of the remote file.
  54. string sha256_checksum = 2;
  55. }
  56. // Specifies a file available as a Cloud Storage Object.
  57. message Gcs {
  58. // Required. Bucket of the Cloud Storage object.
  59. string bucket = 1 [(google.api.field_behavior) = REQUIRED];
  60. // Required. Name of the Cloud Storage object.
  61. string object = 2 [(google.api.field_behavior) = REQUIRED];
  62. // Generation number of the Cloud Storage object.
  63. int64 generation = 3;
  64. }
  65. // A specific type of file.
  66. oneof type {
  67. // A generic remote file.
  68. Remote remote = 1;
  69. // A Cloud Storage object.
  70. Gcs gcs = 2;
  71. // A local path within the VM to use.
  72. string local_path = 3;
  73. }
  74. // Defaults to false. When false, files are subject to validations
  75. // based on the file type:
  76. //
  77. // Remote: A checksum must be specified.
  78. // Cloud Storage: An object generation number must be specified.
  79. bool allow_insecure = 4;
  80. }
  81. // A resource that manages a system package.
  82. message PackageResource {
  83. // A deb package file. dpkg packages only support INSTALLED state.
  84. message Deb {
  85. // Required. A deb package.
  86. File source = 1 [(google.api.field_behavior) = REQUIRED];
  87. // Whether dependencies should also be installed.
  88. // - install when false: `dpkg -i package`
  89. // - install when true: `apt-get update && apt-get -y install
  90. // package.deb`
  91. bool pull_deps = 2;
  92. }
  93. // A package managed by APT.
  94. // - install: `apt-get update && apt-get -y install [name]`
  95. // - remove: `apt-get -y remove [name]`
  96. message APT {
  97. // Required. Package name.
  98. string name = 1 [(google.api.field_behavior) = REQUIRED];
  99. }
  100. // An RPM package file. RPM packages only support INSTALLED state.
  101. message RPM {
  102. // Required. An rpm package.
  103. File source = 1 [(google.api.field_behavior) = REQUIRED];
  104. // Whether dependencies should also be installed.
  105. // - install when false: `rpm --upgrade --replacepkgs package.rpm`
  106. // - install when true: `yum -y install package.rpm` or
  107. // `zypper -y install package.rpm`
  108. bool pull_deps = 2;
  109. }
  110. // A package managed by YUM.
  111. // - install: `yum -y install package`
  112. // - remove: `yum -y remove package`
  113. message YUM {
  114. // Required. Package name.
  115. string name = 1 [(google.api.field_behavior) = REQUIRED];
  116. }
  117. // A package managed by Zypper.
  118. // - install: `zypper -y install package`
  119. // - remove: `zypper -y rm package`
  120. message Zypper {
  121. // Required. Package name.
  122. string name = 1 [(google.api.field_behavior) = REQUIRED];
  123. }
  124. // A package managed by GooGet.
  125. // - install: `googet -noconfirm install package`
  126. // - remove: `googet -noconfirm remove package`
  127. message GooGet {
  128. // Required. Package name.
  129. string name = 1 [(google.api.field_behavior) = REQUIRED];
  130. }
  131. // An MSI package. MSI packages only support INSTALLED state.
  132. message MSI {
  133. // Required. The MSI package.
  134. File source = 1 [(google.api.field_behavior) = REQUIRED];
  135. // Additional properties to use during installation.
  136. // This should be in the format of Property=Setting.
  137. // Appended to the defaults of `ACTION=INSTALL
  138. // REBOOT=ReallySuppress`.
  139. repeated string properties = 2;
  140. }
  141. // The desired state that the OS Config agent maintains on the VM.
  142. enum DesiredState {
  143. // Unspecified is invalid.
  144. DESIRED_STATE_UNSPECIFIED = 0;
  145. // Ensure that the package is installed.
  146. INSTALLED = 1;
  147. // The agent ensures that the package is not installed and
  148. // uninstalls it if detected.
  149. REMOVED = 2;
  150. }
  151. // Required. The desired state the agent should maintain for this package.
  152. DesiredState desired_state = 1 [(google.api.field_behavior) = REQUIRED];
  153. // A system package.
  154. oneof system_package {
  155. // A package managed by Apt.
  156. APT apt = 2;
  157. // A deb package file.
  158. Deb deb = 3;
  159. // A package managed by YUM.
  160. YUM yum = 4;
  161. // A package managed by Zypper.
  162. Zypper zypper = 5;
  163. // An rpm package file.
  164. RPM rpm = 6;
  165. // A package managed by GooGet.
  166. GooGet googet = 7;
  167. // An MSI package.
  168. MSI msi = 8;
  169. }
  170. }
  171. // A resource that manages a package repository.
  172. message RepositoryResource {
  173. // Represents a single apt package repository. These will be added to
  174. // a repo file that will be managed at
  175. // `/etc/apt/sources.list.d/google_osconfig.list`.
  176. message AptRepository {
  177. // Type of archive.
  178. enum ArchiveType {
  179. // Unspecified is invalid.
  180. ARCHIVE_TYPE_UNSPECIFIED = 0;
  181. // Deb indicates that the archive contains binary files.
  182. DEB = 1;
  183. // Deb-src indicates that the archive contains source files.
  184. DEB_SRC = 2;
  185. }
  186. // Required. Type of archive files in this repository.
  187. ArchiveType archive_type = 1 [(google.api.field_behavior) = REQUIRED];
  188. // Required. URI for this repository.
  189. string uri = 2 [(google.api.field_behavior) = REQUIRED];
  190. // Required. Distribution of this repository.
  191. string distribution = 3 [(google.api.field_behavior) = REQUIRED];
  192. // Required. List of components for this repository. Must contain at least one
  193. // item.
  194. repeated string components = 4 [(google.api.field_behavior) = REQUIRED];
  195. // URI of the key file for this repository. The agent maintains a
  196. // keyring at `/etc/apt/trusted.gpg.d/osconfig_agent_managed.gpg`.
  197. string gpg_key = 5;
  198. }
  199. // Represents a single yum package repository. These are added to a
  200. // repo file that is managed at
  201. // `/etc/yum.repos.d/google_osconfig.repo`.
  202. message YumRepository {
  203. // Required. A one word, unique name for this repository. This is the `repo
  204. // id` in the yum config file and also the `display_name` if
  205. // `display_name` is omitted. This id is also used as the unique
  206. // identifier when checking for resource conflicts.
  207. string id = 1 [(google.api.field_behavior) = REQUIRED];
  208. // The display name of the repository.
  209. string display_name = 2;
  210. // Required. The location of the repository directory.
  211. string base_url = 3 [(google.api.field_behavior) = REQUIRED];
  212. // URIs of GPG keys.
  213. repeated string gpg_keys = 4;
  214. }
  215. // Represents a single zypper package repository. These are added to a
  216. // repo file that is managed at
  217. // `/etc/zypp/repos.d/google_osconfig.repo`.
  218. message ZypperRepository {
  219. // Required. A one word, unique name for this repository. This is the `repo
  220. // id` in the zypper config file and also the `display_name` if
  221. // `display_name` is omitted. This id is also used as the unique
  222. // identifier when checking for GuestPolicy conflicts.
  223. string id = 1 [(google.api.field_behavior) = REQUIRED];
  224. // The display name of the repository.
  225. string display_name = 2;
  226. // Required. The location of the repository directory.
  227. string base_url = 3 [(google.api.field_behavior) = REQUIRED];
  228. // URIs of GPG keys.
  229. repeated string gpg_keys = 4;
  230. }
  231. // Represents a Goo package repository. These are added to a repo file
  232. // that is managed at
  233. // `C:/ProgramData/GooGet/repos/google_osconfig.repo`.
  234. message GooRepository {
  235. // Required. The name of the repository.
  236. string name = 1 [(google.api.field_behavior) = REQUIRED];
  237. // Required. The url of the repository.
  238. string url = 2 [(google.api.field_behavior) = REQUIRED];
  239. }
  240. // A specific type of repository.
  241. oneof repository {
  242. // An Apt Repository.
  243. AptRepository apt = 1;
  244. // A Yum Repository.
  245. YumRepository yum = 2;
  246. // A Zypper Repository.
  247. ZypperRepository zypper = 3;
  248. // A Goo Repository.
  249. GooRepository goo = 4;
  250. }
  251. }
  252. // A resource that allows executing scripts on the VM.
  253. //
  254. // The `ExecResource` has 2 stages: `validate` and `enforce` and both stages
  255. // accept a script as an argument to execute.
  256. //
  257. // When the `ExecResource` is applied by the agent, it first executes the
  258. // script in the `validate` stage. The `validate` stage can signal that the
  259. // `ExecResource` is already in the desired state by returning an exit code
  260. // of `100`. If the `ExecResource` is not in the desired state, it should
  261. // return an exit code of `101`. Any other exit code returned by this stage
  262. // is considered an error.
  263. //
  264. // If the `ExecResource` is not in the desired state based on the exit code
  265. // from the `validate` stage, the agent proceeds to execute the script from
  266. // the `enforce` stage. If the `ExecResource` is already in the desired
  267. // state, the `enforce` stage will not be run.
  268. // Similar to `validate` stage, the `enforce` stage should return an exit
  269. // code of `100` to indicate that the resource in now in its desired state.
  270. // Any other exit code is considered an error.
  271. //
  272. // NOTE: An exit code of `100` was chosen over `0` (and `101` vs `1`) to
  273. // have an explicit indicator of `in desired state`, `not in desired state`
  274. // and errors. Because, for example, Powershell will always return an exit
  275. // code of `0` unless an `exit` statement is provided in the script. So, for
  276. // reasons of consistency and being explicit, exit codes `100` and `101`
  277. // were chosen.
  278. message ExecResource {
  279. // A file or script to execute.
  280. message Exec {
  281. // The interpreter to use.
  282. enum Interpreter {
  283. // Defaults to NONE.
  284. INTERPRETER_UNSPECIFIED = 0;
  285. // If no interpreter is specified the
  286. // source will be executed directly, which will likely only
  287. // succeed for executables and scripts with shebang lines.
  288. // [Wikipedia
  289. // shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)).
  290. NONE = 1;
  291. // Indicates that the script will be run with /bin/sh on Linux and
  292. // cmd.exe on windows.
  293. SHELL = 2;
  294. // Indicates that the script will be run with powershell.
  295. POWERSHELL = 3;
  296. }
  297. // What to execute.
  298. oneof source {
  299. // A remote or local file.
  300. File file = 1;
  301. // An inline script.
  302. // The size of the script is limited to 1024 characters.
  303. string script = 2;
  304. }
  305. // Optional arguments to pass to the source during execution.
  306. repeated string args = 3;
  307. // Required. The script interpreter to use.
  308. Interpreter interpreter = 4 [(google.api.field_behavior) = REQUIRED];
  309. // Only recorded for enforce Exec.
  310. // Path to an output file (that is created by this Exec) whose
  311. // content will be recorded in OSPolicyResourceCompliance after a
  312. // successful run. Absence or failure to read this file will result in
  313. // this ExecResource being non-compliant. Output file size is limited to
  314. // 100K bytes.
  315. string output_file_path = 5;
  316. }
  317. // Required. What to run to validate this resource is in the desired state.
  318. // An exit code of 100 indicates "in desired state", and exit code of 101
  319. // indicates "not in desired state". Any other exit code indicates a
  320. // failure running validate.
  321. Exec validate = 1 [(google.api.field_behavior) = REQUIRED];
  322. // What to run to bring this resource into the desired state.
  323. // An exit code of 100 indicates "success", any other exit code indicates
  324. // a failure running enforce.
  325. Exec enforce = 2;
  326. }
  327. // A resource that manages the state of a file.
  328. message FileResource {
  329. // Desired state of the file.
  330. enum DesiredState {
  331. // Unspecified is invalid.
  332. DESIRED_STATE_UNSPECIFIED = 0;
  333. // Ensure file at path is present.
  334. PRESENT = 1;
  335. // Ensure file at path is absent.
  336. ABSENT = 2;
  337. // Ensure the contents of the file at path matches. If the file does
  338. // not exist it will be created.
  339. CONTENTS_MATCH = 3;
  340. }
  341. // The source for the contents of the file.
  342. oneof source {
  343. // A remote or local source.
  344. File file = 1;
  345. // A a file with this content.
  346. // The size of the content is limited to 1024 characters.
  347. string content = 2;
  348. }
  349. // Required. The absolute path of the file within the VM.
  350. string path = 3 [(google.api.field_behavior) = REQUIRED];
  351. // Required. Desired state of the file.
  352. DesiredState state = 4 [(google.api.field_behavior) = REQUIRED];
  353. // Consists of three octal digits which represent, in
  354. // order, the permissions of the owner, group, and other users for the
  355. // file (similarly to the numeric mode used in the linux chmod
  356. // utility). Each digit represents a three bit number with the 4 bit
  357. // corresponding to the read permissions, the 2 bit corresponds to the
  358. // write bit, and the one bit corresponds to the execute permission.
  359. // Default behavior is 755.
  360. //
  361. // Below are some examples of permissions and their associated values:
  362. // read, write, and execute: 7
  363. // read and execute: 5
  364. // read and write: 6
  365. // read only: 4
  366. string permissions = 5;
  367. }
  368. // Required. The id of the resource with the following restrictions:
  369. //
  370. // * Must contain only lowercase letters, numbers, and hyphens.
  371. // * Must start with a letter.
  372. // * Must be between 1-63 characters.
  373. // * Must end with a number or a letter.
  374. // * Must be unique within the OS policy.
  375. string id = 1 [(google.api.field_behavior) = REQUIRED];
  376. // Resource type.
  377. oneof resource_type {
  378. // Package resource
  379. PackageResource pkg = 2;
  380. // Package repository resource
  381. RepositoryResource repository = 3;
  382. // Exec resource
  383. ExecResource exec = 4;
  384. // File resource
  385. FileResource file = 5;
  386. }
  387. }
  388. // Resource groups provide a mechanism to group OS policy resources.
  389. //
  390. // Resource groups enable OS policy authors to create a single OS policy
  391. // to be applied to VMs running different operating Systems.
  392. //
  393. // When the OS policy is applied to a target VM, the appropriate resource
  394. // group within the OS policy is selected based on the `OSFilter` specified
  395. // within the resource group.
  396. message ResourceGroup {
  397. // Used to specify the OS filter for a resource group
  398. OSFilter os_filter = 1;
  399. // Required. List of resources configured for this resource group.
  400. // The resources are executed in the exact order specified here.
  401. repeated Resource resources = 2 [(google.api.field_behavior) = REQUIRED];
  402. }
  403. // Policy mode
  404. enum Mode {
  405. // Invalid mode
  406. MODE_UNSPECIFIED = 0;
  407. // This mode checks if the configuration resources in the policy are in
  408. // their desired state. No actions are performed if they are not in the
  409. // desired state. This mode is used for reporting purposes.
  410. VALIDATION = 1;
  411. // This mode checks if the configuration resources in the policy are in
  412. // their desired state, and if not, enforces the desired state.
  413. ENFORCEMENT = 2;
  414. }
  415. // Required. The id of the OS policy with the following restrictions:
  416. //
  417. // * Must contain only lowercase letters, numbers, and hyphens.
  418. // * Must start with a letter.
  419. // * Must be between 1-63 characters.
  420. // * Must end with a number or a letter.
  421. // * Must be unique within the assignment.
  422. string id = 1 [(google.api.field_behavior) = REQUIRED];
  423. // Policy description.
  424. // Length of the description is limited to 1024 characters.
  425. string description = 2;
  426. // Required. Policy mode
  427. Mode mode = 3 [(google.api.field_behavior) = REQUIRED];
  428. // Required. List of resource groups for the policy.
  429. // For a particular VM, resource groups are evaluated in the order specified
  430. // and the first resource group that is applicable is selected and the rest
  431. // are ignored.
  432. //
  433. // If none of the resource groups are applicable for a VM, the VM is
  434. // considered to be non-compliant w.r.t this policy. This behavior can be
  435. // toggled by the flag `allow_no_resource_group_match`
  436. repeated ResourceGroup resource_groups = 4 [(google.api.field_behavior) = REQUIRED];
  437. // This flag determines the OS policy compliance status when none of the
  438. // resource groups within the policy are applicable for a VM. Set this value
  439. // to `true` if the policy needs to be reported as compliant even if the
  440. // policy has nothing to validate or enforce.
  441. bool allow_no_resource_group_match = 5;
  442. }