From 4b0ad15b0ff483486ae90d73092e7be00f8c1848 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Wed, 11 Nov 2020 09:10:56 -0800 Subject: [PATCH] feat: Added PatchRollout feature to PatchDeployments feat: Added Inventory proto definitions for VM Manager Inventory. PiperOrigin-RevId: 341842584 --- google/cloud/osconfig/v1/BUILD.bazel | 128 ++++----- google/cloud/osconfig/v1/inventory.proto | 258 ++++++++++++++++++ .../cloud/osconfig/v1/osconfig_common.proto | 38 +++ google/cloud/osconfig/v1/osconfig_v1.yaml | 5 +- .../cloud/osconfig/v1/patch_deployments.proto | 89 +++--- google/cloud/osconfig/v1/patch_jobs.proto | 80 +++++- 6 files changed, 470 insertions(+), 128 deletions(-) create mode 100644 google/cloud/osconfig/v1/inventory.proto create mode 100644 google/cloud/osconfig/v1/osconfig_common.proto diff --git a/google/cloud/osconfig/v1/BUILD.bazel b/google/cloud/osconfig/v1/BUILD.bazel index 6ef114e0e..609e4a1b3 100644 --- a/google/cloud/osconfig/v1/BUILD.bazel +++ b/google/cloud/osconfig/v1/BUILD.bazel @@ -1,17 +1,59 @@ # This file was automatically generated by BuildFileGenerator +# https://github.com/googleapis/gapic-generator/tree/master/rules_gapic/bazel -# This is an API workspace, having public visibility by default makes perfect sense. -package(default_visibility = ["//visibility:public"]) +# Most of the manual changes to this file will be overwritten. +# It's **only** allowed to change the following rule attribute values: +# - names of *_gapic_assembly_* rules +# - certain parameters of *_gapic_library rules, including but not limited to: +# * extra_protoc_parameters +# * extra_protoc_file_parameters +# The complete list of preserved parameters can be found in the source code. ############################################################################## # Common ############################################################################## load("@rules_proto//proto:defs.bzl", "proto_library") -load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info") +load( + "@com_google_googleapis_imports//:imports.bzl", + "csharp_gapic_assembly_pkg", + "csharp_gapic_library", + "csharp_grpc_library", + "csharp_proto_library", + "go_gapic_assembly_pkg", + "go_gapic_library", + "go_proto_library", + "go_test", + "java_gapic_assembly_gradle_pkg", + "java_gapic_library", + "java_gapic_test", + "java_grpc_library", + "java_proto_library", + "moved_proto_library", + "nodejs_gapic_assembly_pkg", + "nodejs_gapic_library", + "php_gapic_assembly_pkg", + "php_gapic_library", + "php_grpc_library", + "php_proto_library", + "proto_library_with_info", + "py_gapic_assembly_pkg", + "py_gapic_library", + "py_grpc_library", + "py_proto_library", + "ruby_gapic_assembly_pkg", + "ruby_gapic_library", + "ruby_grpc_library", + "ruby_proto_library", +) + +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) proto_library( name = "osconfig_proto", srcs = [ + "inventory.proto", + "osconfig_common.proto", "osconfig_service.proto", "patch_deployments.proto", "patch_jobs.proto", @@ -38,18 +80,6 @@ proto_library_with_info( ], ) -############################################################################## -# Java -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "java_gapic_assembly_gradle_pkg", - "java_gapic_library", - "java_gapic_test", - "java_grpc_library", - "java_proto_library", -) - java_proto_library( name = "osconfig_java_proto", deps = [":osconfig_proto"], @@ -95,17 +125,6 @@ java_gapic_assembly_gradle_pkg( ], ) -############################################################################## -# Go -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "go_gapic_assembly_pkg", - "go_gapic_library", - "go_proto_library", - "go_test", -) - go_proto_library( name = "osconfig_go_proto", compilers = ["@io_bazel_rules_go//proto:go_grpc"], @@ -148,18 +167,6 @@ go_gapic_assembly_pkg( ], ) -############################################################################## -# Python -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "moved_proto_library", - "py_gapic_assembly_pkg", - "py_gapic_library", - "py_grpc_library", - "py_proto_library", -) - moved_proto_library( name = "osconfig_moved_proto", srcs = [":osconfig_proto"], @@ -212,17 +219,6 @@ py_gapic_assembly_pkg( ], ) -############################################################################## -# PHP -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "php_gapic_assembly_pkg", - "php_gapic_library", - "php_grpc_library", - "php_proto_library", -) - php_proto_library( name = "osconfig_php_proto", deps = [":osconfig_proto"], @@ -257,15 +253,6 @@ php_gapic_assembly_pkg( ], ) -############################################################################## -# Node.js -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "nodejs_gapic_assembly_pkg", - "nodejs_gapic_library", -) - nodejs_gapic_library( name = "osconfig_nodejs_gapic", package_name = "@google-cloud/os-config", @@ -285,17 +272,6 @@ nodejs_gapic_assembly_pkg( ], ) -############################################################################## -# Ruby -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "ruby_gapic_assembly_pkg", - "ruby_gapic_library", - "ruby_grpc_library", - "ruby_proto_library", -) - ruby_proto_library( name = "osconfig_ruby_proto", deps = [":osconfig_proto"], @@ -311,6 +287,7 @@ ruby_gapic_library( name = "osconfig_ruby_gapic", src = ":osconfig_proto_with_info", gapic_yaml = "osconfig_gapic.yaml", + grpc_service_config = "osconfig_grpc_service_config.json", package = "google.cloud.osconfig.v1", service_yaml = "osconfig_v1.yaml", deps = [ @@ -329,17 +306,6 @@ ruby_gapic_assembly_pkg( ], ) -############################################################################## -# C# -############################################################################## -load( - "@com_google_googleapis_imports//:imports.bzl", - "csharp_gapic_assembly_pkg", - "csharp_gapic_library", - "csharp_grpc_library", - "csharp_proto_library", -) - csharp_proto_library( name = "osconfig_csharp_proto", deps = [":osconfig_proto"], @@ -354,8 +320,8 @@ csharp_grpc_library( csharp_gapic_library( name = "osconfig_csharp_gapic", srcs = [":osconfig_proto_with_info"], - grpc_service_config = "osconfig_grpc_service_config.json", common_resources_config = "@gax_dotnet//:Google.Api.Gax/ResourceNames/CommonResourcesConfig.json", + grpc_service_config = "osconfig_grpc_service_config.json", deps = [ ":osconfig_csharp_grpc", ":osconfig_csharp_proto", diff --git a/google/cloud/osconfig/v1/inventory.proto b/google/cloud/osconfig/v1/inventory.proto new file mode 100644 index 000000000..ba3318e70 --- /dev/null +++ b/google/cloud/osconfig/v1/inventory.proto @@ -0,0 +1,258 @@ +// Copyright 2020 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.osconfig.v1; + +import "google/protobuf/timestamp.proto"; + +option csharp_namespace = "Google.Cloud.OsConfig.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/v1;osconfig"; +option java_multiple_files = true; +option java_outer_classname = "Inventories"; +option java_package = "com.google.cloud.osconfig.v1"; +option php_namespace = "Google\\Cloud\\OsConfig\\V1"; +option ruby_package = "Google::Cloud::OsConfig::V1"; + +// OS Config Inventory is a service for collecting and reporting operating +// system and package information on VM instances. + +// The inventory details of a VM. +message Inventory { + // Operating system information for the VM. + message OsInfo { + // The VM hostname. + string hostname = 9; + + // The operating system long name. + // For example 'Debian GNU/Linux 9' or 'Microsoft Window Server 2019 + // Datacenter'. + string long_name = 2; + + // The operating system short name. + // For example, 'windows' or 'debian'. + string short_name = 3; + + // The version of the operating system. + string version = 4; + + // The system architecture of the operating system. + string architecture = 5; + + // The kernel version of the operating system. + string kernel_version = 6; + + // The kernel release of the operating system. + string kernel_release = 7; + + // The current version of the OS Config agent running on the VM. + string osconfig_agent_version = 8; + } + + // A single piece of inventory on a VM. + message Item { + // The origin of a specific inventory item. + enum OriginType { + // Invalid. An origin type must be specified. + ORIGIN_TYPE_UNSPECIFIED = 0; + + // This inventory item was discovered as the result of the agent + // reporting inventory via the reporting API. + INVENTORY_REPORT = 1; + } + + // The different types of inventory that are tracked on a VM. + enum Type { + // Invalid. An type must be specified. + TYPE_UNSPECIFIED = 0; + + // This represents a package that is installed on the VM. + INSTALLED_PACKAGE = 1; + + // This represents an update that is available for a package. + AVAILABLE_PACKAGE = 2; + } + + // Identifier for this item, unique across items for this VM. + string id = 1; + + // The origin of this inventory item. + OriginType origin_type = 2; + + // When this inventory item was first detected. + google.protobuf.Timestamp create_time = 8; + + // When this inventory item was last modified. + google.protobuf.Timestamp update_time = 9; + + // The specific type of inventory, correlating to its specific details. + Type type = 5; + + // Specific details of this inventory item based on its type. + oneof details { + // Software package present on the VM instance. + SoftwarePackage installed_package = 6; + + // Software package available to be installed on the VM instance. + SoftwarePackage available_package = 7; + } + } + + // Software package information of the operating system. + message SoftwarePackage { + // Information about the different types of software packages. + oneof details { + // Yum package info. + // For details about the yum package manager, see + // https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/6/html/deployment_guide/ch-yum. + VersionedPackage yum_package = 1; + + // Details of an APT package. + // For details about the apt package manager, see + // https://wiki.debian.org/Apt. + VersionedPackage apt_package = 2; + + // Details of a Zypper package. + // For details about the Zypper package manager, see + // https://en.opensuse.org/SDB:Zypper_manual. + VersionedPackage zypper_package = 3; + + // Details of a Googet package. + // For details about the googet package manager, see + // https://github.com/google/googet. + VersionedPackage googet_package = 4; + + // Details of a Zypper patch. + // For details about the Zypper package manager, see + // https://en.opensuse.org/SDB:Zypper_manual. + ZypperPatch zypper_patch = 5; + + // Details of a Windows Update package. + // See https://docs.microsoft.com/en-us/windows/win32/api/_wua/ for + // information about Windows Update. + WindowsUpdatePackage wua_package = 6; + + // Details of a Windows Quick Fix engineering package. + // See + // https://docs.microsoft.com/en-us/windows/win32/cimwin32prov/win32-quickfixengineering + // for info in Windows Quick Fix Engineering. + WindowsQuickFixEngineeringPackage qfe_package = 7; + + // Details of a COS package. + VersionedPackage cos_package = 8; + } + } + + // Information related to the a standard versioned package. This includes + // package info for APT, Yum, Zypper, and Googet package managers. + message VersionedPackage { + // The name of the package. + string package_name = 4; + + // The system architecture this package is intended for. + string architecture = 2; + + // The version of the package. + string version = 3; + } + + // Details related to a Windows Update package. + // Field data and names are taken from Windows Update API IUpdate Interface: + // https://docs.microsoft.com/en-us/windows/win32/api/_wua/ + // Descriptive fields like title, and description are localized based on + // the locale of the VM being updated. + message WindowsUpdatePackage { + // Categories specified by the Windows Update. + message WindowsUpdateCategory { + // The identifier of the windows update category. + string id = 1; + + // The name of the windows update category. + string name = 2; + } + + // The localized title of the update package. + string title = 1; + + // The localized description of the update package. + string description = 2; + + // The categories that are associated with this update package. + repeated WindowsUpdateCategory categories = 3; + + // A collection of Microsoft Knowledge Base article IDs that are associated + // with the update package. + repeated string kb_article_ids = 4; + + // A hyperlink to the language-specific support information for the update. + string support_url = 11; + + // A collection of URLs that provide more information about the update + // package. + repeated string more_info_urls = 5; + + // Gets the identifier of an update package. Stays the same across + // revisions. + string update_id = 6; + + // The revision number of this update package. + int32 revision_number = 7; + + // The last published date of the update, in (UTC) date and time. + google.protobuf.Timestamp last_deployment_change_time = 10; + } + + // Details related to a Zypper Patch. + message ZypperPatch { + // The name of the patch. + string patch_name = 5; + + // The category of the patch. + string category = 2; + + // The severity specified for this patch + string severity = 3; + + // Any summary information provided about this patch. + string summary = 4; + } + + // Information related to a Quick Fix Engineering package. + // Fields are taken from Windows QuickFixEngineering Interface and match + // the source names: + // https://docs.microsoft.com/en-us/windows/win32/cimwin32prov/win32-quickfixengineering + message WindowsQuickFixEngineeringPackage { + // A short textual description of the QFE update. + string caption = 1; + + // A textual description of the QFE update. + string description = 2; + + // Unique identifier associated with a particular QFE update. + string hot_fix_id = 3; + + // Date that the QFE update was installed. Mapped from installed_on field. + google.protobuf.Timestamp install_time = 5; + } + + // Base level operating system information for the VM. + OsInfo os_info = 1; + + // Inventory items related to the VM keyed by an opaque unique identifier for + // each inventory item. The identifier is unique to each distinct and + // addressable inventory item and will change, when there is a new package + // version. + map items = 2; +} diff --git a/google/cloud/osconfig/v1/osconfig_common.proto b/google/cloud/osconfig/v1/osconfig_common.proto new file mode 100644 index 000000000..43059e9a6 --- /dev/null +++ b/google/cloud/osconfig/v1/osconfig_common.proto @@ -0,0 +1,38 @@ +// Copyright 2020 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.osconfig.v1; + +option csharp_namespace = "Google.Cloud.OsConfig.V1"; +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/v1;osconfig"; +option java_outer_classname = "Common"; +option java_package = "com.google.cloud.osconfig.v1"; +option php_namespace = "Google\\Cloud\\OsConfig\\V1"; +option ruby_package = "Google::Cloud::OsConfig::V1"; + +// Message encapsulating a value that can be either absolute ("fixed") or +// relative ("percent") to a value. +message FixedOrPercent { + // Type of the value. + oneof mode { + // Specifies a fixed value. + int32 fixed = 1; + + // Specifies the relative value defined as a percentage, which will be + // multiplied by a reference value. + int32 percent = 2; + } +} diff --git a/google/cloud/osconfig/v1/osconfig_v1.yaml b/google/cloud/osconfig/v1/osconfig_v1.yaml index 32fa1aeaa..0a4a3ec8e 100644 --- a/google/cloud/osconfig/v1/osconfig_v1.yaml +++ b/google/cloud/osconfig/v1/osconfig_v1.yaml @@ -1,11 +1,14 @@ type: google.api.Service config_version: 3 name: osconfig.googleapis.com -title: Cloud OS Config API +title: OS Config API apis: - name: google.cloud.osconfig.v1.OsConfigService +types: +- name: google.cloud.osconfig.v1.Inventory + documentation: summary: |- OS management tools that can be used for patch management, patch diff --git a/google/cloud/osconfig/v1/patch_deployments.proto b/google/cloud/osconfig/v1/patch_deployments.proto index 10ea5d1a7..d8bb84a91 100644 --- a/google/cloud/osconfig/v1/patch_deployments.proto +++ b/google/cloud/osconfig/v1/patch_deployments.proto @@ -49,47 +49,59 @@ message PatchDeployment { // This field is ignored when you create a new patch deployment. string name = 1; - // Optional. Description of the patch deployment. Length of the description is limited - // to 1024 characters. + // Optional. Description of the patch deployment. Length of the description is + // limited to 1024 characters. string description = 2 [(google.api.field_behavior) = OPTIONAL]; // Required. VM instances to patch. - PatchInstanceFilter instance_filter = 3 [(google.api.field_behavior) = REQUIRED]; + PatchInstanceFilter instance_filter = 3 + [(google.api.field_behavior) = REQUIRED]; // Optional. Patch configuration that is applied. PatchConfig patch_config = 4 [(google.api.field_behavior) = OPTIONAL]; - // Optional. Duration of the patch. After the duration ends, the patch times out. - google.protobuf.Duration duration = 5 [(google.api.field_behavior) = OPTIONAL]; + // Optional. Duration of the patch. After the duration ends, the patch times + // out. + google.protobuf.Duration duration = 5 + [(google.api.field_behavior) = OPTIONAL]; // Schedule for the patch. oneof schedule { // Required. Schedule a one-time execution. - OneTimeSchedule one_time_schedule = 6 [(google.api.field_behavior) = REQUIRED]; + OneTimeSchedule one_time_schedule = 6 + [(google.api.field_behavior) = REQUIRED]; // Required. Schedule recurring executions. - RecurringSchedule recurring_schedule = 7 [(google.api.field_behavior) = REQUIRED]; + RecurringSchedule recurring_schedule = 7 + [(google.api.field_behavior) = REQUIRED]; } // Output only. Time the patch deployment was created. Timestamp is in // [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text format. - google.protobuf.Timestamp create_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp create_time = 8 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. Time the patch deployment was last updated. Timestamp is in // [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text format. - google.protobuf.Timestamp update_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp update_time = 9 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The last time a patch job was started by this deployment. // Timestamp is in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text // format. - google.protobuf.Timestamp last_execute_time = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp last_execute_time = 10 + [(google.api.field_behavior) = OUTPUT_ONLY]; + + // Optional. Rollout strategy of the patch job. + PatchRollout rollout = 11 [(google.api.field_behavior) = OPTIONAL]; } // Sets the time for a one time patch deployment. Timestamp is in // [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text format. message OneTimeSchedule { // Required. The desired patch job execution time. - google.protobuf.Timestamp execute_time = 1 [(google.api.field_behavior) = REQUIRED]; + google.protobuf.Timestamp execute_time = 1 + [(google.api.field_behavior) = REQUIRED]; } // Sets the time for recurring patch deployments. @@ -114,14 +126,17 @@ message RecurringSchedule { // Optional. The time that the recurring schedule becomes effective. // Defaults to `create_time` of the patch deployment. - google.protobuf.Timestamp start_time = 2 [(google.api.field_behavior) = OPTIONAL]; + google.protobuf.Timestamp start_time = 2 + [(google.api.field_behavior) = OPTIONAL]; - // Optional. The end time at which a recurring patch deployment schedule is no longer - // active. - google.protobuf.Timestamp end_time = 3 [(google.api.field_behavior) = OPTIONAL]; + // Optional. The end time at which a recurring patch deployment schedule is no + // longer active. + google.protobuf.Timestamp end_time = 3 + [(google.api.field_behavior) = OPTIONAL]; // Required. Time of the day to run a recurring deployment. - google.type.TimeOfDay time_of_day = 4 [(google.api.field_behavior) = REQUIRED]; + google.type.TimeOfDay time_of_day = 4 + [(google.api.field_behavior) = REQUIRED]; // Required. The frequency unit of this recurring schedule. Frequency frequency = 5 [(google.api.field_behavior) = REQUIRED]; @@ -137,16 +152,19 @@ message RecurringSchedule { } // Output only. The time the last patch job ran successfully. - google.protobuf.Timestamp last_execute_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp last_execute_time = 9 + [(google.api.field_behavior) = OUTPUT_ONLY]; // Output only. The time the next patch job is scheduled to run. - google.protobuf.Timestamp next_execute_time = 10 [(google.api.field_behavior) = OUTPUT_ONLY]; + google.protobuf.Timestamp next_execute_time = 10 + [(google.api.field_behavior) = OUTPUT_ONLY]; } // Represents a weekly schedule. message WeeklySchedule { // Required. Day of the week. - google.type.DayOfWeek day_of_week = 1 [(google.api.field_behavior) = REQUIRED]; + google.type.DayOfWeek day_of_week = 1 + [(google.api.field_behavior) = REQUIRED]; } // Represents a monthly schedule. An example of a valid monthly schedule is @@ -155,29 +173,32 @@ message MonthlySchedule { // One day in a month. oneof day_of_month { // Required. Week day in a month. - WeekDayOfMonth week_day_of_month = 1 [(google.api.field_behavior) = REQUIRED]; + WeekDayOfMonth week_day_of_month = 1 + [(google.api.field_behavior) = REQUIRED]; - // Required. One day of the month. 1-31 indicates the 1st to the 31st day. -1 - // indicates the last day of the month. - // Months without the target day will be skipped. For example, a schedule to - // run "every month on the 31st" will not run in February, April, June, etc. + // Required. One day of the month. 1-31 indicates the 1st to the 31st day. + // -1 indicates the last day of the month. Months without the target day + // will be skipped. For example, a schedule to run "every month on the 31st" + // will not run in February, April, June, etc. int32 month_day = 2 [(google.api.field_behavior) = REQUIRED]; } } // Represents one week day in a month. An example is "the 4th Sunday". message WeekDayOfMonth { - // Required. Week number in a month. 1-4 indicates the 1st to 4th week of the month. -1 - // indicates the last week of the month. + // Required. Week number in a month. 1-4 indicates the 1st to 4th week of the + // month. -1 indicates the last week of the month. int32 week_ordinal = 1 [(google.api.field_behavior) = REQUIRED]; // Required. A day of the week. - google.type.DayOfWeek day_of_week = 2 [(google.api.field_behavior) = REQUIRED]; + google.type.DayOfWeek day_of_week = 2 + [(google.api.field_behavior) = REQUIRED]; } // A request message for creating a patch deployment. message CreatePatchDeploymentRequest { - // Required. The project to apply this patch deployment to in the form `projects/*`. + // Required. The project to apply this patch deployment to in the form + // `projects/*`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -185,8 +206,8 @@ message CreatePatchDeploymentRequest { } ]; - // Required. A name for the patch deployment in the project. When creating a name - // the following rules apply: + // Required. A name for the patch deployment in the project. When creating a + // name the following rules apply: // * Must contain only lowercase letters, numbers, and hyphens. // * Must start with a letter. // * Must be between 1-63 characters. @@ -220,11 +241,13 @@ message ListPatchDeploymentsRequest { } ]; - // Optional. The maximum number of patch deployments to return. Default is 100. + // Optional. The maximum number of patch deployments to return. Default is + // 100. int32 page_size = 2 [(google.api.field_behavior) = OPTIONAL]; - // Optional. A pagination token returned from a previous call to ListPatchDeployments - // that indicates where this listing should continue from. + // Optional. A pagination token returned from a previous call to + // ListPatchDeployments that indicates where this listing should continue + // from. string page_token = 3 [(google.api.field_behavior) = OPTIONAL]; } diff --git a/google/cloud/osconfig/v1/patch_jobs.proto b/google/cloud/osconfig/v1/patch_jobs.proto index 553c9e471..1fffb532a 100644 --- a/google/cloud/osconfig/v1/patch_jobs.proto +++ b/google/cloud/osconfig/v1/patch_jobs.proto @@ -18,6 +18,7 @@ package google.cloud.osconfig.v1; import "google/api/field_behavior.proto"; import "google/api/resource.proto"; +import "google/cloud/osconfig/v1/osconfig_common.proto"; import "google/protobuf/duration.proto"; import "google/protobuf/timestamp.proto"; @@ -43,9 +44,10 @@ message ExecutePatchJobRequest { // to 1024 characters. string description = 2; - // Required. Instances to patch, either explicitly or filtered by some criteria such - // as zone or labels. - PatchInstanceFilter instance_filter = 7 [(google.api.field_behavior) = REQUIRED]; + // Required. Instances to patch, either explicitly or filtered by some + // criteria such as zone or labels. + PatchInstanceFilter instance_filter = 7 + [(google.api.field_behavior) = REQUIRED]; // Patch configuration being applied. If omitted, instances are // patched using the default configurations. @@ -61,6 +63,9 @@ message ExecutePatchJobRequest { // Display name for this patch job. This does not have to be unique. string display_name = 8; + + // Rollout strategy of the patch job. + PatchRollout rollout = 9; } // Request to get an active or completed patch job. @@ -76,7 +81,8 @@ message GetPatchJobRequest { // Request to list details for all instances that are part of a patch job. message ListPatchJobInstanceDetailsRequest { - // Required. The parent for the instances are in the form of `projects/*/patchJobs/*`. + // Required. The parent for the instances are in the form of + // `projects/*/patchJobs/*`. string parent = 1 [ (google.api.field_behavior) = REQUIRED, (google.api.resource_reference) = { @@ -113,8 +119,8 @@ message ListPatchJobInstanceDetailsResponse { message PatchJobInstanceDetails { // The instance name in the form `projects/*/zones/*/instances/*` string name = 1 [(google.api.resource_reference) = { - type: "compute.googleapis.com/Instance" - }]; + type: "compute.googleapis.com/Instance" + }]; // The unique identifier for the instance. This identifier is // defined by the server. @@ -165,7 +171,7 @@ message ListPatchJobsResponse { // A high level representation of a patch job that is either in progress // or has completed. // -// Instances details are not included in the job. To paginate through instance +// Instance details are not included in the job. To paginate through instance // details, use ListPatchJobInstanceDetails. // // For more information about patch jobs, see @@ -275,7 +281,7 @@ message PatchJob { // Last time this patch job was updated. google.protobuf.Timestamp update_time = 4; - // The current state of the PatchJob . + // The current state of the PatchJob. State state = 5; // Instances to patch. @@ -310,6 +316,9 @@ message PatchJob { type: "osconfig.googleapis.com/PatchDeployment" } ]; + + // Rollout strategy being applied. + PatchRollout rollout = 16; } // Patch configuration specifications. Contains details on how to apply the @@ -416,8 +425,6 @@ message Instance { // service. NO_AGENT_DETECTED = 15; } - - } // Message for canceling a patch job. @@ -484,9 +491,7 @@ message YumSettings { } // Googet patching is performed by running `googet update`. -message GooSettings { - -} +message GooSettings {} // Zypper patching is performed by running `zypper patch`. // See also https://en.opensuse.org/SDB:Zypper_manual. @@ -683,3 +688,52 @@ message PatchInstanceFilter { // example prefix="prod-". repeated string instance_name_prefixes = 5; } + +// Patch rollout configuration specifications. Contains details on the +// concurrency control when applying patch(es) to all targeted VMs. +message PatchRollout { + // Type of the rollout. + enum Mode { + // Mode must be specified. + MODE_UNSPECIFIED = 0; + + // Patches are applied one zone at a time. The patch job begins in the + // region with the lowest number of targeted VMs. Within the region, + // patching begins in the zone with the lowest number of targeted VMs. If + // multiple regions (or zones within a region) have the same number of + // targeted VMs, a tie-breaker is achieved by sorting the regions or zones + // in alphabetical order. + ZONE_BY_ZONE = 1; + + // Patches are applied to VMs in all zones at the same time. + CONCURRENT_ZONES = 2; + } + + // Mode of the patch rollout. + Mode mode = 1; + + // The maximum number (or percentage) of VMs per zone to disrupt at any given + // moment. The number of VMs calculated from multiplying the percentage by the + // total number of VMs in a zone is rounded up. + // + // During patching, a VM is considered disrupted from the time the agent is + // notified to begin until patching has completed. This disruption time + // includes the time to complete reboot and any post-patch steps. + // + // A VM contributes to the disruption budget if its patching operation fails + // either when applying the patches, running pre or post patch steps, or if it + // fails to respond with a success notification before timing out. VMs that + // are not running or do not have an active agent do not count toward this + // disruption budget. + // + // For zone-by-zone rollouts, if the disruption budget in a zone is exceeded, + // the patch job stops, because continuing to the next zone requires + // completion of the patch process in the previous zone. + // + // For example, if the disruption budget has a fixed value of `10`, and 8 VMs + // fail to patch in the current zone, the patch job continues to patch 2 VMs + // at a time until the zone is completed. When that zone is completed + // successfully, patching begins with 10 VMs at a time in the next zone. If 10 + // VMs in the next zone fail to patch, the patch job stops. + FixedOrPercent disruption_budget = 2; +}