From 551cf1e6e3addcc63740427c4f9b40dedd3dac27 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Tue, 24 Mar 2020 18:38:06 -0700 Subject: [PATCH] feat: Add OS Config AgentEndpointService v1 PatchJobs and Tasks APIs. PiperOrigin-RevId: 302792195 --- .../osconfig/agentendpoint/v1/BUILD.bazel | 356 ++++++++++++++++++ .../agentendpoint/v1/agentendpoint.proto | 154 ++++++++ .../v1/agentendpoint_grpc_service_config.json | 22 ++ .../agentendpoint/v1/osconfig_gapic.yaml | 148 ++++++++ .../agentendpoint/v1/osconfig_v1.yaml | 19 + .../agentendpoint/v1/patch_jobs.proto | 288 ++++++++++++++ .../osconfig/agentendpoint/v1/tasks.proto | 179 +++++++++ 7 files changed, 1166 insertions(+) create mode 100644 google/cloud/osconfig/agentendpoint/v1/BUILD.bazel create mode 100644 google/cloud/osconfig/agentendpoint/v1/agentendpoint.proto create mode 100644 google/cloud/osconfig/agentendpoint/v1/agentendpoint_grpc_service_config.json create mode 100644 google/cloud/osconfig/agentendpoint/v1/osconfig_gapic.yaml create mode 100644 google/cloud/osconfig/agentendpoint/v1/osconfig_v1.yaml create mode 100644 google/cloud/osconfig/agentendpoint/v1/patch_jobs.proto create mode 100644 google/cloud/osconfig/agentendpoint/v1/tasks.proto diff --git a/google/cloud/osconfig/agentendpoint/v1/BUILD.bazel b/google/cloud/osconfig/agentendpoint/v1/BUILD.bazel new file mode 100644 index 000000000..1d3d649c8 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/BUILD.bazel @@ -0,0 +1,356 @@ +# This file was automatically generated by BuildFileGenerator + +# This is an API workspace, having public visibility by default makes perfect sense. +package(default_visibility = ["//visibility:public"]) + +############################################################################## +# Common +############################################################################## +load("@rules_proto//proto:defs.bzl", "proto_library") +load("@com_google_googleapis_imports//:imports.bzl", "proto_library_with_info") + +proto_library( + name = "agentendpoint_proto", + srcs = [ + "agentendpoint.proto", + "patch_jobs.proto", + "tasks.proto", + ], + deps = [ + "//google/api:client_proto", + "//google/api:field_behavior_proto", + ], +) + +proto_library_with_info( + name = "agentendpoint_proto_with_info", + deps = [ + ":agentendpoint_proto", + "//google/cloud:common_resources_proto", + ], +) + +############################################################################## +# 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 = "agentendpoint_java_proto", + deps = [":agentendpoint_proto"], +) + +java_grpc_library( + name = "agentendpoint_java_grpc", + srcs = [":agentendpoint_proto"], + deps = [":agentendpoint_java_proto"], +) + +java_gapic_library( + name = "agentendpoint_java_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + test_deps = [ + ":agentendpoint_java_grpc", + ], + deps = [ + ":agentendpoint_java_proto", + ], +) + +java_gapic_test( + name = "agentendpoint_java_gapic_test_suite", + test_classes = [ + "com.google.cloud.osconfig.agentendpoint.v1.AgentEndpointServiceClientTest", + ], + runtime_deps = [":agentendpoint_java_gapic_test"], +) + +# Open Source Packages +java_gapic_assembly_gradle_pkg( + name = "google-cloud-osconfig-agentendpoint-v1-java", + deps = [ + ":agentendpoint_java_gapic", + ":agentendpoint_java_grpc", + ":agentendpoint_java_proto", + ":agentendpoint_proto", + ], +) + +############################################################################## +# Go +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "go_gapic_assembly_pkg", + "go_gapic_library", + "go_proto_library", + "go_test", +) + +go_proto_library( + name = "agentendpoint_go_proto", + compilers = ["@io_bazel_rules_go//proto:go_grpc"], + importpath = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1", + protos = [":agentendpoint_proto"], + deps = [ + "//google/api:annotations_go_proto", + ], +) + +go_gapic_library( + name = "agentendpoint_go_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + importpath = "cloud.google.com/go/osconfig/agentendpoint/apiv1", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + deps = [ + ":agentendpoint_go_proto", + ], +) + +go_test( + name = "agentendpoint_go_gapic_test", + srcs = [":agentendpoint_go_gapic_srcjar_test"], + embed = [":agentendpoint_go_gapic"], + importpath = "cloud.google.com/go/osconfig/agentendpoint/apiv1", +) + +# Open Source Packages +go_gapic_assembly_pkg( + name = "gapi-cloud-osconfig-agentendpoint-v1-go", + deps = [ + ":agentendpoint_go_gapic", + ":agentendpoint_go_gapic_srcjar-smoke-test.srcjar", + ":agentendpoint_go_gapic_srcjar-test.srcjar", + ":agentendpoint_go_proto", + ], +) + +############################################################################## +# 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 = "agentendpoint_moved_proto", + srcs = [":agentendpoint_proto"], + deps = [ + "//google/api:client_proto", + "//google/api:field_behavior_proto", + ], +) + +py_proto_library( + name = "agentendpoint_py_proto", + plugin = "@protoc_docs_plugin//:docs_plugin", + deps = [":agentendpoint_moved_proto"], +) + +py_grpc_library( + name = "agentendpoint_py_grpc", + srcs = [":agentendpoint_moved_proto"], + deps = [":agentendpoint_py_proto"], +) + +py_gapic_library( + name = "agentendpoint_py_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + deps = [ + ":agentendpoint_py_grpc", + ":agentendpoint_py_proto", + ], +) + +# Open Source Packages +py_gapic_assembly_pkg( + name = "osconfig-agentendpoint-v1-py", + deps = [ + ":agentendpoint_py_gapic", + ":agentendpoint_py_grpc", + ":agentendpoint_py_proto", + ], +) + +############################################################################## +# 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 = "agentendpoint_php_proto", +# deps = [":agentendpoint_proto"], +# ) +# +# php_grpc_library( +# name = "agentendpoint_php_grpc", +# srcs = [":agentendpoint_proto"], +# deps = [":agentendpoint_php_proto"], +# ) +# +# php_gapic_library( +# name = "agentendpoint_php_gapic", +# src = ":agentendpoint_proto_with_info", +# gapic_yaml = "osconfig_gapic.yaml", +# package = "google.cloud.osconfig.agentendpoint.v1", +# service_yaml = "osconfig_v1.yaml", +# deps = [ +# ":agentendpoint_php_grpc", +# ":agentendpoint_php_proto", +# ], +# ) +# +# # Open Source Packages +# php_gapic_assembly_pkg( +# name = "google-cloud-osconfig-agentendpoint-v1-php", +# deps = [ +# ":agentendpoint_php_gapic", +# ":agentendpoint_php_grpc", +# ":agentendpoint_php_proto", +# ], +# ) + +############################################################################## +# Node.js +############################################################################## +load( + "@com_google_googleapis_imports//:imports.bzl", + "nodejs_gapic_assembly_pkg", + "nodejs_gapic_library", +) + +nodejs_gapic_library( + name = "agentendpoint_nodejs_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + deps = [], +) + +nodejs_gapic_assembly_pkg( + name = "osconfig-agentendpoint-v1-nodejs", + deps = [ + ":agentendpoint_nodejs_gapic", + ":agentendpoint_proto", + ], +) + +############################################################################## +# 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 = "agentendpoint_ruby_proto", + deps = [":agentendpoint_proto"], +) + +ruby_grpc_library( + name = "agentendpoint_ruby_grpc", + srcs = [":agentendpoint_proto"], + deps = [":agentendpoint_ruby_proto"], +) + +ruby_gapic_library( + name = "agentendpoint_ruby_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + deps = [ + ":agentendpoint_ruby_grpc", + ":agentendpoint_ruby_proto", + ], +) + +# Open Source Packages +ruby_gapic_assembly_pkg( + name = "google-cloud-osconfig-agentendpoint-v1-ruby", + deps = [ + ":agentendpoint_ruby_gapic", + ":agentendpoint_ruby_grpc", + ":agentendpoint_ruby_proto", + ], +) + +############################################################################## +# 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 = "agentendpoint_csharp_proto", + deps = [":agentendpoint_proto"], +) + +csharp_grpc_library( + name = "agentendpoint_csharp_grpc", + srcs = [":agentendpoint_proto"], + deps = [":agentendpoint_csharp_proto"], +) + +csharp_gapic_library( + name = "agentendpoint_csharp_gapic", + src = ":agentendpoint_proto_with_info", + gapic_yaml = "osconfig_gapic.yaml", + package = "google.cloud.osconfig.agentendpoint.v1", + service_yaml = "osconfig_v1.yaml", + deps = [ + ":agentendpoint_csharp_grpc", + ":agentendpoint_csharp_proto", + ], +) + +# Open Source Packages +csharp_gapic_assembly_pkg( + name = "google-cloud-osconfig-agentendpoint-v1-csharp", + deps = [ + ":agentendpoint_csharp_gapic", + ":agentendpoint_csharp_grpc", + ":agentendpoint_csharp_proto", + ], +) + +############################################################################## +# C++ +############################################################################## +# Put your C++ rules here diff --git a/google/cloud/osconfig/agentendpoint/v1/agentendpoint.proto b/google/cloud/osconfig/agentendpoint/v1/agentendpoint.proto new file mode 100644 index 000000000..bfcaf7144 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/agentendpoint.proto @@ -0,0 +1,154 @@ +// 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.agentendpoint.v1; + +import "google/api/client.proto"; +import "google/api/field_behavior.proto"; +import "google/cloud/osconfig/agentendpoint/v1/tasks.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1;agentendpoint"; +option java_multiple_files = true; +option java_outer_classname = "AgentEndpointProto"; +option java_package = "com.google.cloud.osconfig.agentendpoint.v1"; + +// OS Config agent endpoint API. +service AgentEndpointService { + option (google.api.default_host) = "osconfig.googleapis.com"; + + // Stream established by client to receive Task notifications. + rpc ReceiveTaskNotification(ReceiveTaskNotificationRequest) returns (stream ReceiveTaskNotificationResponse) { + option (google.api.method_signature) = "instance_id_token,agent_version"; + } + + // Signals the start of a task execution and returns the task info. + rpc StartNextTask(StartNextTaskRequest) returns (StartNextTaskResponse) { + option (google.api.method_signature) = "instance_id_token"; + } + + // Signals an intermediary progress checkpoint in task execution. + rpc ReportTaskProgress(ReportTaskProgressRequest) returns (ReportTaskProgressResponse) { + option (google.api.method_signature) = "instance_id_token,task_id,task_type"; + } + + // Signals that the task execution is complete and optionally returns the next + // task. + rpc ReportTaskComplete(ReportTaskCompleteRequest) returns (ReportTaskCompleteResponse) { + option (google.api.method_signature) = "instance_id_token,task_id,task_type,error_message"; + } +} + +// A request message to receive task notifications. +message ReceiveTaskNotificationRequest { + // Required. This is the GCE instance identity token described in + // https://cloud.google.com/compute/docs/instances/verifying-instance-identity + // where the audience is 'osconfig.googleapis.com' and the format is 'full'. + string instance_id_token = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The version of the agent making the request. + string agent_version = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// The streaming rpc message that notifies the agent when it has a task +// that it needs to perform on the VM instance. +message ReceiveTaskNotificationResponse { + +} + +// A request message for signaling the start of a task execution. +message StartNextTaskRequest { + // Required. This is the GCE instance identity token described in + // https://cloud.google.com/compute/docs/instances/verifying-instance-identity + // where the audience is 'osconfig.googleapis.com' and the format is 'full'. + string instance_id_token = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// A response message that contains the details of the task to work on. +message StartNextTaskResponse { + // The details of the task that should be worked on. Can be empty if there + // is no new task to work on. + Task task = 1; +} + +// A request message for reporting the progress of current task. +message ReportTaskProgressRequest { + // Required. This is the GCE instance identity token described in + // https://cloud.google.com/compute/docs/instances/verifying-instance-identity + // where the audience is 'osconfig.googleapis.com' and the format is 'full'. + string instance_id_token = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Unique identifier of the task this applies to. + string task_id = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The type of task to report progress on. + // + // Progress must include the appropriate message based on this enum as + // specified below: + // APPLY_PATCHES = ApplyPatchesTaskProgress + // EXEC_STEP = Progress not supported for this type. + TaskType task_type = 3 [(google.api.field_behavior) = REQUIRED]; + + // Intermediate progress of the current task. + oneof progress { + // Details about the progress of the apply patches task. + ApplyPatchesTaskProgress apply_patches_task_progress = 4; + + // Details about the progress of the exec step task. + ExecStepTaskProgress exec_step_task_progress = 5; + } +} + +// The response message after the agent reported the current task progress. +message ReportTaskProgressResponse { + // Instructs agent to continue or not. + TaskDirective task_directive = 1; +} + +// A request message for signaling the completion of a task execution. +message ReportTaskCompleteRequest { + // Required. This is the GCE instance identity token described in + // https://cloud.google.com/compute/docs/instances/verifying-instance-identity + // where the audience is 'osconfig.googleapis.com' and the format is 'full'. + string instance_id_token = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. Unique identifier of the task this applies to. + string task_id = 2 [(google.api.field_behavior) = REQUIRED]; + + // Required. The type of task to report completed. + // + // The output must include the appropriate message based on the following + // enum values: + // APPLY_PATCHES = ApplyPatchesTaskOutput + // EXEC_STEP = ExecStepTaskOutput + TaskType task_type = 3 [(google.api.field_behavior) = REQUIRED]; + + // Descriptive error message if the task execution ended in error. + string error_message = 4; + + // Final output details of the current task. + oneof output { + // Final output details of the apply patches task; + ApplyPatchesTaskOutput apply_patches_task_output = 5; + + // Final output details of the exec step task; + ExecStepTaskOutput exec_step_task_output = 6; + } +} + +// The response message after the agent signaled the current task complete. +message ReportTaskCompleteResponse { + +} diff --git a/google/cloud/osconfig/agentendpoint/v1/agentendpoint_grpc_service_config.json b/google/cloud/osconfig/agentendpoint/v1/agentendpoint_grpc_service_config.json new file mode 100644 index 000000000..8de5fbe4c --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/agentendpoint_grpc_service_config.json @@ -0,0 +1,22 @@ +{ + "methodConfig": [{ + "name": [{ "service": "google.cloud.osconfig.agentendpoint.v1.AgentEndpointService" }], + "timeout": "60s", + "retryPolicy": { + "maxAttempts": 5, + "initialBackoff": "1s", + "maxBackoff": "60s", + "backoffMultiplier": 1.3, + "retryableStatusCodes": ["UNAVAILABLE", "DEADLINE_EXCEEDED"] + } + }, + { + "name": [ + { "service": "google.cloud.osconfig.agentendpoint.v1.AgentEndpointService", "method": "ReceiveTaskNotification" }, + { "service": "google.cloud.osconfig.agentendpoint.v1.AgentEndpointService", "method": "StartNextTask" }, + { "service": "google.cloud.osconfig.agentendpoint.v1.AgentEndpointService", "method": "ReportTaskProgress" }, + { "service": "google.cloud.osconfig.agentendpoint.v1.AgentEndpointService", "method": "ReportTaskComplete" } + ], + "timeout": "60s" + }] +} diff --git a/google/cloud/osconfig/agentendpoint/v1/osconfig_gapic.yaml b/google/cloud/osconfig/agentendpoint/v1/osconfig_gapic.yaml new file mode 100644 index 000000000..6e6362512 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/osconfig_gapic.yaml @@ -0,0 +1,148 @@ +type: com.google.api.codegen.ConfigProto +config_schema_version: 1.0.0 +# The settings of generated code in a specific language. +language_settings: + java: + package_name: com.google.cloud.osconfig.agentendpoint.v1 + python: + package_name: google.cloud.osconfig.agentendpoint_v1.gapic + go: + package_name: cloud.google.com/go/osconfig/agentendpoint/apiv1 + csharp: + package_name: Google.Cloud.OsConfig.Agentendpoint.V1 + ruby: + package_name: Google::Cloud::OsConfig::Agentendpoint::V1 + php: + package_name: Google\Cloud\OsConfig\Agentendpoint\V1 + nodejs: + package_name: agentendpoint.v1 +# A list of API interface configurations. +interfaces: +# The fully qualified name of the API interface. +- name: google.cloud.osconfig.agentendpoint.v1.AgentEndpointService + # A list of resource collection configurations. + # Consists of a name_pattern and an entity_name. + # The name_pattern is a pattern to describe the names of the resources of this + # collection, using the platform's conventions for URI patterns. A generator + # may use this to generate methods to compose and decompose such names. The + # pattern should use named placeholders as in `shelves/{shelf}/books/{book}`; + # those will be taken as hints for the parameter names of the generated + # methods. If empty, no name methods are generated. + # The entity_name is the name to be used as a basis for generated methods and + # classes. + collections: [] + # Definition for retryable codes. + retry_codes_def: + - name: idempotent + retry_codes: + - DEADLINE_EXCEEDED + - UNAVAILABLE + - name: non_idempotent + retry_codes: [] + # Definition for retry/backoff parameters. + retry_params_def: + - name: default + initial_retry_delay_millis: 100 + retry_delay_multiplier: 1.3 + max_retry_delay_millis: 60000 + initial_rpc_timeout_millis: 20000 + rpc_timeout_multiplier: 1 + max_rpc_timeout_millis: 20000 + total_timeout_millis: 600000 + # A list of method configurations. + # Common properties: + # + # name - The simple name of the method. + # + # flattening - Specifies the configuration for parameter flattening. + # Describes the parameter groups for which a generator should produce method + # overloads which allow a client to directly pass request message fields as + # method parameters. This information may or may not be used, depending on + # the target language. + # Consists of groups, which each represent a list of parameters to be + # flattened. Each parameter listed must be a field of the request message. + # + # required_fields - Fields that are always required for a request to be + # valid. + # + # page_streaming - Specifies the configuration for paging. + # Describes information for generating a method which transforms a paging + # list RPC into a stream of resources. + # Consists of a request and a response. + # The request specifies request information of the list method. It defines + # which fields match the paging pattern in the request. The request consists + # of a page_size_field and a token_field. The page_size_field is the name of + # the optional field specifying the maximum number of elements to be + # returned in the response. The token_field is the name of the field in the + # request containing the page token. + # The response specifies response information of the list method. It defines + # which fields match the paging pattern in the response. The response + # consists of a token_field and a resources_field. The token_field is the + # name of the field in the response containing the next page token. The + # resources_field is the name of the field in the response containing the + # list of resources belonging to the page. + # + # retry_codes_name - Specifies the configuration for retryable codes. The + # name must be defined in interfaces.retry_codes_def. + # + # retry_params_name - Specifies the configuration for retry/backoff + # parameters. The name must be defined in interfaces.retry_params_def. + # + # field_name_patterns - Maps the field name of the request type to + # entity_name of interfaces.collections. + # Specifies the string pattern that the field must follow. + # + # timeout_millis - Specifies the default timeout for a non-retrying call. If + # the call is retrying, refer to retry_params_name instead. + methods: + - name: ReceiveTaskNotification + flattening: + groups: + - parameters: + - instance_id_token + - agent_version + required_fields: + - instance_id_token + - agent_version + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: StartNextTask + flattening: + groups: + - parameters: + - instance_id_token + required_fields: + - instance_id_token + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ReportTaskProgress + flattening: + groups: + - parameters: + - instance_id_token + - task_id + - task_type + required_fields: + - instance_id_token + - task_id + - task_type + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 + - name: ReportTaskComplete + flattening: + groups: + - parameters: + - instance_id_token + - task_id + - task_type + - error_message + required_fields: + - instance_id_token + - task_id + - task_type + retry_codes_name: non_idempotent + retry_params_name: default + timeout_millis: 60000 diff --git a/google/cloud/osconfig/agentendpoint/v1/osconfig_v1.yaml b/google/cloud/osconfig/agentendpoint/v1/osconfig_v1.yaml new file mode 100644 index 000000000..f3f7d4432 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/osconfig_v1.yaml @@ -0,0 +1,19 @@ +type: google.api.Service +config_version: 3 +name: osconfig.googleapis.com +title: Cloud OS Config API + +apis: +- name: google.cloud.osconfig.agentendpoint.v1.AgentEndpointService + +documentation: + summary: |- + OS management tools that can be used for patch management, patch + compliance, and configuration management on VM instances. + +backend: + rules: + - selector: 'google.cloud.osconfig.agentendpoint.v1.AgentEndpointService.*' + deadline: 30.0 + - selector: google.cloud.osconfig.agentendpoint.v1.AgentEndpointService.ReceiveTaskNotification + deadline: 3600.0 diff --git a/google/cloud/osconfig/agentendpoint/v1/patch_jobs.proto b/google/cloud/osconfig/agentendpoint/v1/patch_jobs.proto new file mode 100644 index 000000000..8f37db3f8 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/patch_jobs.proto @@ -0,0 +1,288 @@ +// 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.agentendpoint.v1; + +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1;agentendpoint"; +option java_outer_classname = "PatchJobs"; +option java_package = "com.google.cloud.osconfig.agentendpoint.v1"; + +// Patch configuration specifications. Contains details on how to +// apply patches to a VM instance. +message PatchConfig { + // Post-patch reboot settings. + enum RebootConfig { + // The default behavior is DEFAULT. + REBOOT_CONFIG_UNSPECIFIED = 0; + + // The agent decides if a reboot is necessary by checking + // signals such as registry keys on Windows or `/var/run/reboot-required` on + // APT based systems. On RPM based systems, a set of core system package + // install times are compared with system boot time. + DEFAULT = 1; + + // Always reboot the machine after the update completes. + ALWAYS = 2; + + // Never reboot the machine after the update completes. + NEVER = 3; + } + + // Post-patch reboot settings. + RebootConfig reboot_config = 1; + + // Retry strategy can be defined to have the agent retry patching + // during the window if patching fails. If omitted, the agent will use its + // default retry strategy. + RetryStrategy retry_strategy = 2; + + // Apt update settings. Use this override the default apt patch rules. + AptSettings apt = 3; + + // Yum update settings. Use this override the default yum patch rules. + YumSettings yum = 4; + + // Goo update settings. Use this override the default goo patch rules. + GooSettings goo = 5; + + // Zypper update settings. Use this override the default zypper patch rules. + ZypperSettings zypper = 6; + + // Windows update settings. Use this override the default windows patch rules. + WindowsUpdateSettings windows_update = 7; + + // The ExecStep to run before the patch update. + ExecStep pre_step = 8; + + // The ExecStep to run after the patch update. + ExecStep post_step = 9; +} + +// Apt patching will be performed by executing `apt-get update && apt-get +// upgrade`. Additional options can be set to control how this is executed. +message AptSettings { + // Apt patch type. + enum Type { + // By default, upgrade will be performed. + TYPE_UNSPECIFIED = 0; + + // Runs `apt-get dist-upgrade`. + DIST = 1; + + // Runs `apt-get upgrade`. + UPGRADE = 2; + } + + // By changing the type to DIST, the patching will be performed + // using `apt-get dist-upgrade` instead. + Type type = 1; + + // List of packages to exclude from update. + repeated string excludes = 2; + + // An exclusive list of packages to be updated. These are the only packages + // that will be updated. If these packages are not installed, they will be + // ignored. This field cannot be specified with any other patch configuration + // fields. + repeated string exclusive_packages = 3; +} + +// Yum patching will be performed by executing `yum update`. Additional options +// can be set to control how this is executed. +// +// Note that not all settings are supported on all platforms. +message YumSettings { + // Adds the `--security` flag to `yum update`. Not supported on + // all platforms. + bool security = 1; + + // Will cause patch to run `yum update-minimal` instead. + bool minimal = 2; + + // List of packages to exclude from update. These packages will be excluded by + // using the yum `--exclude` flag. + repeated string excludes = 3; + + // An exclusive list of packages to be updated. These are the only packages + // that will be updated. If these packages are not installed, they will be + // ignored. This field must not be specified with any other patch + // configuration fields. + repeated string exclusive_packages = 4; +} + +// Googet patching is performed by running `googet update`. +message GooSettings { + +} + +// Zypper patching is performed by running `zypper patch`. +// See also https://en.opensuse.org/SDB:Zypper_manual. +message ZypperSettings { + // Adds the `--with-optional` flag to `zypper patch`. + bool with_optional = 1; + + // Adds the `--with-update` flag, to `zypper patch`. + bool with_update = 2; + + // Install only patches with these categories. + // Common categories include security, recommended, and feature. + repeated string categories = 3; + + // Install only patches with these severities. + // Common severities include critical, important, moderate, and low. + repeated string severities = 4; + + // List of patches to exclude from update. + repeated string excludes = 5; + + // An exclusive list of patches to be updated. These are the only patches + // that will be installed using 'zypper patch patch:' command. + // This field must not be used with any other patch configuration fields. + repeated string exclusive_patches = 6; +} + +// Windows patching is performed using the Windows Update Agent. +message WindowsUpdateSettings { + // Microsoft Windows update classifications as defined in + // [1] + // https://support.microsoft.com/en-us/help/824684/description-of-the-standard-terminology-that-is-used-to-describe-micro + enum Classification { + // Invalid. If classifications are included, they must be specified. + CLASSIFICATION_UNSPECIFIED = 0; + + // "A widely released fix for a specific problem that addresses a critical, + // non-security-related bug." [1] + CRITICAL = 1; + + // "A widely released fix for a product-specific, security-related + // vulnerability. Security vulnerabilities are rated by their severity. The + // severity rating is indicated in the Microsoft security bulletin as + // critical, important, moderate, or low." [1] + SECURITY = 2; + + // "A widely released and frequent software update that contains additions + // to a product’s definition database. Definition databases are often used + // to detect objects that have specific attributes, such as malicious code, + // phishing websites, or junk mail." [1] + DEFINITION = 3; + + // "Software that controls the input and output of a device." [1] + DRIVER = 4; + + // "New product functionality that is first distributed outside the context + // of a product release and that is typically included in the next full + // product release." [1] + FEATURE_PACK = 5; + + // "A tested, cumulative set of all hotfixes, security updates, critical + // updates, and updates. Additionally, service packs may contain additional + // fixes for problems that are found internally since the release of the + // product. Service packs my also contain a limited number of + // customer-requested design changes or features." [1] + SERVICE_PACK = 6; + + // "A utility or feature that helps complete a task or set of tasks." [1] + TOOL = 7; + + // "A tested, cumulative set of hotfixes, security updates, critical + // updates, and updates that are packaged together for easy deployment. A + // rollup generally targets a specific area, such as security, or a + // component of a product, such as Internet Information Services (IIS)." [1] + UPDATE_ROLLUP = 8; + + // "A widely released fix for a specific problem. An update addresses a + // noncritical, non-security-related bug." [1] + UPDATE = 9; + } + + // Only apply updates of these windows update classifications. If empty, all + // updates will be applied. + repeated Classification classifications = 1; + + // List of KBs to exclude from update. + repeated string excludes = 2; + + // An exclusive list of kbs to be updated. These are the only patches + // that will be updated. This field must not be used with other + // patch configurations. + repeated string exclusive_patches = 3; +} + +// The strategy for retrying failed patches during the patch window. +message RetryStrategy { + // If true, the agent will continue to try and patch until the window has + // ended. + bool enabled = 1; +} + +// A step that runs an executable for a PatchJob. +message ExecStep { + // The ExecStepConfig for all Linux VMs targeted by the PatchJob. + ExecStepConfig linux_exec_step_config = 1; + + // The ExecStepConfig for all Windows VMs targeted by the PatchJob. + ExecStepConfig windows_exec_step_config = 2; +} + +// Common configurations for an ExecStep. +message ExecStepConfig { + // The interpreter used to execute the a file. + enum Interpreter { + // Invalid for a Windows ExecStepConfig. For a Linux ExecStepConfig, the + // interpreter will be parsed from the shebang line of the script if + // unspecified. + INTERPRETER_UNSPECIFIED = 0; + + // Indicates that the script will be run with /bin/sh on Linux and cmd + // on windows. + SHELL = 1; + + // Indicates that the file will be run with PowerShell. + POWERSHELL = 2; + } + + // Location of the executable. + oneof executable { + // An absolute path to the executable on the VM. + string local_path = 1; + + // A GCS object containing the executable. + GcsObject gcs_object = 2; + } + + // Defaults to [0]. A list of possible return values that the + // execution can return to indicate a success. + repeated int32 allowed_success_codes = 3; + + // The script interpreter to use to run the script. If no interpreter is + // specified the script will be executed directly, which will likely + // only succeed for scripts with shebang lines. + // [Wikipedia shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)). + Interpreter interpreter = 4; +} + +// GCS object representation. +message GcsObject { + // Bucket of the GCS object. + string bucket = 1; + + // Name of the GCS object. + string object = 2; + + // Generation number of the GCS object. This is used to ensure that the + // ExecStep specified by this PatchJob does not change. + int64 generation_number = 3; +} diff --git a/google/cloud/osconfig/agentendpoint/v1/tasks.proto b/google/cloud/osconfig/agentendpoint/v1/tasks.proto new file mode 100644 index 000000000..426dc22f1 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1/tasks.proto @@ -0,0 +1,179 @@ +// 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.agentendpoint.v1; + +import "google/api/field_behavior.proto"; +import "google/cloud/osconfig/agentendpoint/v1/patch_jobs.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1;agentendpoint"; +option java_outer_classname = "Tasks"; +option java_package = "com.google.cloud.osconfig.agentendpoint.v1"; + +// Specifies the current agent behavior. +enum TaskDirective { + // Unspecified is invalid. + TASK_DIRECTIVE_UNSPECIFIED = 0; + + // The task should continue to progress. + CONTINUE = 1; + + // Task should not be started, or if already in progress, should stop + // at first safe stopping point. Task should be considered done and will + // never repeat. + STOP = 2; +} + +// Specifies the type of task to perform. +enum TaskType { + // Unspecified is invalid. + TASK_TYPE_UNSPECIFIED = 0; + + // The apply patches task. + APPLY_PATCHES = 1; + + // The exec step task. + EXEC_STEP_TASK = 2; +} + +// A unit of work to be performed by the agent. +message Task { + // Unique task id. + string task_id = 1; + + // The type of task to perform. + // + // Task details must include the appropriate message based on this enum as + // specified below: + // APPLY_PATCHES = ApplyPatchesTask + // EXEC_STEP = ExecStepTask; + TaskType task_type = 2; + + // Current directive to the agent. + TaskDirective task_directive = 3; + + // Specific details about the current task to perform. + oneof task_details { + // Details about the apply patches task to perform. + ApplyPatchesTask apply_patches_task = 4; + + // Details about the exec step task to perform. + ExecStepTask exec_step_task = 5; + } + + // Labels describing the task. Used for logging by the agent. + map service_labels = 6; +} + +// Message which instructs agent to apply patches. +message ApplyPatchesTask { + // Specific information about how patches should be applied. + PatchConfig patch_config = 1; + + // If true, the agent will report its status as it goes through the motions + // but won't actually run any updates or perform any reboots. + bool dry_run = 3; +} + +// Information reported from the agent about applying patches execution. +message ApplyPatchesTaskProgress { + // The intermediate states of applying patches. + enum State { + // Unspecified is invalid. + STATE_UNSPECIFIED = 0; + + // The agent has started the patch task. + STARTED = 4; + + // The agent is currently downloading patches. + DOWNLOADING_PATCHES = 1; + + // The agent is currently applying patches. + APPLYING_PATCHES = 2; + + // The agent is currently rebooting the VM instance. + REBOOTING = 3; + } + + // Required. The current state of this patch execution. + State state = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// Information reported from the agent about applying patches execution. +message ApplyPatchesTaskOutput { + // The final states of applying patches. + enum State { + // Unspecified is invalid. + STATE_UNSPECIFIED = 0; + + // Applying patches completed successfully. + SUCCEEDED = 1; + + // Applying patches completed successfully, but a reboot is required. + SUCCEEDED_REBOOT_REQUIRED = 2; + + // Applying patches failed. + FAILED = 3; + } + + // Required. The final state of this task. + State state = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// Message which instructs agent to execute the following command. +message ExecStepTask { + // Details of the exec step to run. + ExecStep exec_step = 1; +} + +// Information reported from the agent about the exec step execution. +message ExecStepTaskProgress { + // The intermediate states of exec steps. + enum State { + // Unspecified is invalid. + STATE_UNSPECIFIED = 0; + + // The agent has started the exec step task. + STARTED = 1; + } + + // Required. The current state of this exec step. + State state = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// Information reported from the agent about the exec step execution. +message ExecStepTaskOutput { + // The final states of exec steps. + enum State { + // Unspecified is invalid. + STATE_UNSPECIFIED = 0; + + // The exec step completed normally. + COMPLETED = 1; + + // The exec step was terminated because it took too long. + TIMED_OUT = 2; + + // The exec step task was cancelled before it started. + CANCELLED = 3; + } + + // Required. The final state of the exec step. + State state = 1 [(google.api.field_behavior) = REQUIRED]; + + // Required. The exit code received from the script which ran as part of the exec step. + int32 exit_code = 2 [(google.api.field_behavior) = REQUIRED]; +}