From f337f7fb702c85833b7b6ca56afaf9a1bf32c096 Mon Sep 17 00:00:00 2001 From: Google APIs Date: Thu, 5 Dec 2019 09:27:32 -0800 Subject: [PATCH] OSConfig AgentEndpoint: add LookupEffectiveGuestPolicy rpc PiperOrigin-RevId: 283989762 --- .../osconfig/agentendpoint/v1beta/BUILD.bazel | 1 + .../agentendpoint/v1beta/agentendpoint.proto | 6 + .../agentendpoint_grpc_service_config.json | 3 +- .../agentendpoint/v1beta/guest_policies.proto | 562 ++++++++++++++++++ 4 files changed, 571 insertions(+), 1 deletion(-) create mode 100644 google/cloud/osconfig/agentendpoint/v1beta/guest_policies.proto diff --git a/google/cloud/osconfig/agentendpoint/v1beta/BUILD.bazel b/google/cloud/osconfig/agentendpoint/v1beta/BUILD.bazel index 92f27765..742b2702 100644 --- a/google/cloud/osconfig/agentendpoint/v1beta/BUILD.bazel +++ b/google/cloud/osconfig/agentendpoint/v1beta/BUILD.bazel @@ -13,6 +13,7 @@ proto_library( name = "agentendpoint_proto", srcs = [ "agentendpoint.proto", + "guest_policies.proto", "patch_jobs.proto", "tasks.proto", ], diff --git a/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint.proto b/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint.proto index 0dba3bf3..84a37db2 100644 --- a/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint.proto +++ b/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint.proto @@ -18,6 +18,7 @@ syntax = "proto3"; package google.cloud.osconfig.agentendpoint.v1beta; import "google/api/field_behavior.proto"; +import "google/cloud/osconfig/agentendpoint/v1beta/guest_policies.proto"; import "google/cloud/osconfig/agentendpoint/v1beta/tasks.proto"; import "google/api/client.proto"; @@ -46,6 +47,11 @@ service AgentEndpointService { // task. rpc ReportTaskComplete(ReportTaskCompleteRequest) returns (ReportTaskCompleteResponse) { } + + // Lookup the effective guest policy that applies to a VM instance. This + // lookup merges all policies that are assigned to the instance ancestry. + rpc LookupEffectiveGuestPolicy(LookupEffectiveGuestPolicyRequest) returns (EffectiveGuestPolicy) { + } } // A request message to receive task notifications. diff --git a/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint_grpc_service_config.json b/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint_grpc_service_config.json index 1c8cdfc7..ff47ee66 100644 --- a/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint_grpc_service_config.json +++ b/google/cloud/osconfig/agentendpoint/v1beta/agentendpoint_grpc_service_config.json @@ -15,7 +15,8 @@ { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReceiveTaskNotification" }, { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "StartNextTask" }, { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskProgress" }, - { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskComplete" } + { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "ReportTaskComplete" }, + { "service": "google.cloud.osconfig.agentendpoint.v1beta.AgentEndpointService", "method": "LookupEffectiveGuestPolicy" } ], "timeout": "60s" }] diff --git a/google/cloud/osconfig/agentendpoint/v1beta/guest_policies.proto b/google/cloud/osconfig/agentendpoint/v1beta/guest_policies.proto new file mode 100644 index 00000000..fb55c5e0 --- /dev/null +++ b/google/cloud/osconfig/agentendpoint/v1beta/guest_policies.proto @@ -0,0 +1,562 @@ +// Copyright 2019 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.v1beta; + +import "google/api/field_behavior.proto"; + +option go_package = "google.golang.org/genproto/googleapis/cloud/osconfig/agentendpoint/v1beta;agentendpoint"; +option java_outer_classname = "GuestPolicies"; +option java_package = "com.google.cloud.osconfig.agentendpoint.v1beta"; + +// The desired state that the OS Config agent will maintain on the VM. +enum DesiredState { + // The default is to ensure the package is installed. + DESIRED_STATE_UNSPECIFIED = 0; + + // The agent ensures that the package is installed. + INSTALLED = 1; + + // The agent ensures that the package is installed and + // periodically checks for and install any updates. + UPDATED = 2; + + // The agent ensures that the package is not installed and uninstall it + // if detected. + REMOVED = 3; +} + +// Package is a reference to the software package to be installed or removed. +// The agent on the VM instance uses the system package manager to apply the +// config. +// +// +// These are the commands that the agent uses to install or remove +// packages. +// +// Apt +// install: `apt-get update && apt-get -y install package1 package2 package3` +// remove: `apt-get -y remove package1 package2 package3` +// +// Yum +// install: `yum -y install package1 package2 package3` +// remove: `yum -y remove package1 package2 package3` +// +// Zypper +// install: `zypper install package1 package2 package3` +// remove: `zypper rm package1 package2` +// +// Googet +// install: `googet -noconfirm install package1 package2 package3` +// remove: `googet -noconfirm remove package1 package2 package3` +message Package { + // Types of package managers that may be used to manage this package. + enum Manager { + // The default behavior is ANY. + MANAGER_UNSPECIFIED = 0; + + // Apply this package config using the default system package manager. + ANY = 1; + + // Apply this package config only if Apt is available on the system. + APT = 2; + + // Apply this package config only if Yum is available on the system. + YUM = 3; + + // Apply this package config only if Zypper is available on the system. + ZYPPER = 4; + + // Apply this package config only if GooGet is available on the system. + GOO = 5; + } + + // The name of the package. A package is uniquely identified for conflict + // validation by checking the package name and the manager(s) that the + // package targets. + string name = 1; + + // The desired_state the agent should maintain for this package. The + // default is to ensure the package is installed. + DesiredState desired_state = 2; + + // Type of package manager that can be used to install this package. + // If a system does not have the package manager, the package is not + // installed or removed no error message is returned. By default, + // or if you specify `ANY`, + // the agent attempts to install and remove this package using the default + // package manager. This is useful when creating a policy that applies to + // different types of systems. + // + // The default behavior is ANY. + Manager manager = 3; +} + +// Represents a single Apt package repository. This repository is added to +// a repo file that is stored at +// `/etc/apt/sources.list.d/google_osconfig.list`. +message AptRepository { + // Type of archive. + enum ArchiveType { + // Unspecified. + ARCHIVE_TYPE_UNSPECIFIED = 0; + + // DEB indicates that the archive contains binary files. + DEB = 1; + + // DEB_SRC indicates that the archive contains source files. + DEB_SRC = 2; + } + + // Type of archive files in this repository. The default behavior is DEB. + ArchiveType archive_type = 1; + + // URI for this repository. + string uri = 2; + + // Distribution of this repository. + string distribution = 3; + + // List of components for this repository. Must contain at least one item. + repeated string components = 4; + + // URI of the key file for this repository. The agent maintains + // a keyring at `/etc/apt/trusted.gpg.d/osconfig_agent_managed.gpg` containing + // all the keys in any applied guest policy. + string gpg_key = 5; +} + +// Represents a single Yum package repository. This repository is added to a +// repo file that is stored at `/etc/yum.repos.d/google_osconfig.repo`. +message YumRepository { + // A one word, unique name for this repository. This is + // the `repo id` in the Yum config file and also the `display_name` if + // `display_name` is omitted. This id is also used as the unique identifier + // when checking for guest policy conflicts. + string id = 1; + + // The display name of the repository. + string display_name = 2; + + // The location of the repository directory. + string base_url = 3; + + // URIs of GPG keys. + repeated string gpg_keys = 4; +} + +// Represents a single Zypper package repository. This repository is added to a +// repo file that is stored at `/etc/zypp/repos.d/google_osconfig.repo`. +message ZypperRepository { + // A one word, unique name for this repository. This is + // the `repo id` in the zypper config file and also the `display_name` if + // `display_name` is omitted. This id is also used as the unique identifier + // when checking for guest policy conflicts. + string id = 1; + + // The display name of the repository. + string display_name = 2; + + // The location of the repository directory. + string base_url = 3; + + // URIs of GPG keys. + repeated string gpg_keys = 4; +} + +// Represents a Goo package repository. These is added to a repo file +// that is stored at C:/ProgramData/GooGet/repos/google_osconfig.repo. +message GooRepository { + // The name of the repository. + string name = 1; + + // The url of the repository. + string url = 2; +} + +// A package repository. +message PackageRepository { + // A specific type of repository. + oneof repository { + // An Apt Repository. + AptRepository apt = 1; + + // A Yum Repository. + YumRepository yum = 2; + + // A Zypper Repository. + ZypperRepository zypper = 3; + + // A Goo Repository. + GooRepository goo = 4; + } +} + +// A software recipe is a set of instructions for installing and configuring a +// piece of software. It consists of a set of artifacts that are +// downloaded, and a set of steps that install, configure, and/or update the +// software. +// +// Recipes support installing and updating software from artifacts in the +// following formats: +// Zip archive, Tar archive, Windows MSI, Debian package, and RPM package. +// +// Additionally, recipes support executing a script (either defined in a file or +// directly in this api) in bash, sh, cmd, and powershell. +// +// Updating a software recipe +// +// If a recipe is assigned to an instance and there is a recipe with the same +// name but a lower version already installed and the assigned state +// of the recipe is `INSTALLED_KEEP_UPDATED`, then the recipe is updated to +// the new version. +// +// Script Working Directories +// +// Each script or execution step is run in its own temporary directory which +// is deleted after completing the step. +message SoftwareRecipe { + // Specifies a resource to be used in the recipe. + message Artifact { + // Specifies an artifact available via some URI. + message Remote { + // URI from which to fetch the object. It should contain both the protocol + // and path following the format {protocol}://{location}. + string uri = 1; + + // Must be provided if `allow_insecure` is `false`. + // SHA256 checksum in hex format, to compare to the checksum of the + // artifact. If the checksum is not empty and it doesn't match the + // artifact then the recipe installation fails before running any of the + // steps. + string checksum = 2; + } + + // Specifies an artifact available as a Cloud Storage object. + message Gcs { + // Bucket of the Cloud Storage object. + // Given an example URL: + // `https://storage.googleapis.com/my-bucket/foo/bar#1234567` + // this value would be `my-bucket`. + string bucket = 1; + + // Name of the Cloud Storage object. + // As specified [here] + // (https://cloud.google.com/storage/docs/naming#objectnames) + // Given an example URL: + // `https://storage.googleapis.com/my-bucket/foo/bar#1234567` + // this value would be `foo/bar`. + string object = 2; + + // Must be provided if allow_insecure is false. + // Generation number of the Cloud Storage object. + // `https://storage.googleapis.com/my-bucket/foo/bar#1234567` + // this value would be `1234567`. + int64 generation = 3; + } + + // Id of the artifact, which the installation and update steps of this + // recipe can reference. Artifacts in a recipe cannot have the same id. + string id = 1; + + // A specific type of artifact. + oneof artifact { + // A generic remote artifact. + Remote remote = 2; + + // A Cloud Storage artifact. + Gcs gcs = 3; + } + + // Defaults to false. When false, recipes are subject to validations + // based on the artifact type: + // + // Remote: A checksum must be specified, and only protocols with + // transport-layer security are permitted. + // GCS: An object generation number must be specified. + bool allow_insecure = 4; + } + + // An action that can be taken as part of installing or updating a recipe. + message Step { + // Copies the artifact to the specified path on the instance. + message CopyFile { + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + + // The absolute path on the instance to put the file. + string destination = 2; + + // Whether to allow this step to overwrite existing files. If this is + // false and the file already exists the file is not overwritten + // and the step is considered a success. Defaults to false. + bool overwrite = 3; + + // Consists of three octal digits which represent, in + // order, the permissions of the owner, group, and other users for the + // file (similarly to the numeric mode used in the linux chmod utility). + // Each digit represents a three bit number with the 4 bit + // corresponding to the read permissions, the 2 bit corresponds to the + // write bit, and the one bit corresponds to the execute permission. + // Default behavior is 755. + // + // Below are some examples of permissions and their associated values: + // read, write, and execute: 7 + // read and execute: 5 + // read and write: 6 + // read only: 4 + string permissions = 4; + } + + // Extracts an archive of the type specified in the specified directory. + message ExtractArchive { + // Specifying the type of archive. + enum ArchiveType { + // Indicates that the archive type isn't specified. + ARCHIVE_TYPE_UNSPECIFIED = 0; + + // Indicates that the archive is a tar archive with no encryption. + TAR = 1; + + // Indicates that the archive is a tar archive with gzip encryption. + TAR_GZIP = 2; + + // Indicates that the archive is a tar archive with bzip encryption. + TAR_BZIP = 3; + + // Indicates that the archive is a tar archive with lzma encryption. + TAR_LZMA = 4; + + // Indicates that the archive is a tar archive with xz encryption. + TAR_XZ = 5; + + // Indicates that the archive is a zip archive. + ZIP = 11; + } + + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + + // Directory to extract archive to. + // Defaults to `/` on Linux or `C:\` on Windows. + string destination = 2; + + // The type of the archive to extract. + ArchiveType type = 3; + } + + // Installs an MSI file. + message InstallMsi { + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + + // The flags to use when installing the MSI + // defaults to ["/i"] (i.e. the install flag). + repeated string flags = 2; + + // Return codes that indicate that the software installed or updated + // successfully. Behaviour defaults to [0] + repeated int32 allowed_exit_codes = 3; + } + + // Installs a deb via dpkg. + message InstallDpkg { + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + } + + // Installs an rpm file via the rpm utility. + message InstallRpm { + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + } + + // Executes an artifact or local file. + message ExecFile { + // Location of the file to execute. + oneof location_type { + // The id of the relevant artifact in the recipe. + string artifact_id = 1; + + // The absolute path of the file on the local filesystem. + string local_path = 2; + } + + // Arguments to be passed to the provided executable. + repeated string args = 3; + + // Defaults to [0]. A list of possible return values that the program + // can return to indicate a success. + repeated int32 allowed_exit_codes = 4; + } + + // Runs a script through an interpreter. + message RunScript { + // The interpreter used to execute a script. + enum Interpreter { + // Default value for ScriptType. + INTERPRETER_UNSPECIFIED = 0; + + // Indicates that the script is run with `/bin/sh` on Linux and `cmd` + // on windows. + SHELL = 1; + + // Indicates that the script is run with powershell. + POWERSHELL = 3; + } + + // The shell script to be executed. + string script = 1; + + // Return codes that indicate that the software installed or updated + // successfully. Behaviour defaults to [0] + repeated int32 allowed_exit_codes = 2; + + // The script interpreter to use to run the script. If no interpreter is + // specified the script is executed directly, which likely + // only succeed for scripts with + // [shebang lines](https://en.wikipedia.org/wiki/Shebang_(Unix)). + Interpreter interpreter = 3; + } + + // A specific type of step. + oneof step { + // Copies a file onto the instance. + CopyFile file_copy = 1; + + // Extracts an archive into the specified directory. + ExtractArchive archive_extraction = 2; + + // Installs an MSI file. + InstallMsi msi_installation = 3; + + // Installs a deb file via dpkg. + InstallDpkg dpkg_installation = 4; + + // Installs an rpm file via the rpm utility. + InstallRpm rpm_installation = 5; + + // Executes an artifact or local file. + ExecFile file_exec = 6; + + // Runs commands in a shell. + RunScript script_run = 7; + } + } + + // Unique identifier for the recipe. Only one recipe with a given name is + // installed on an instance. + // + // Names are also used to identify resources which helps to determine whether + // guest policies have conflicts. This means that requests to create multiple + // recipes with the same name and version are rejected since they + // could potentially have conflicting assignments. + string name = 1; + + // The version of this software recipe. Version can be up to 4 period + // separated numbers (e.g. 12.34.56.78). + string version = 2; + + // Resources available to be used in the steps in the recipe. + repeated Artifact artifacts = 3; + + // Actions to be taken for installing this recipe. On failure it stops + // executing steps and does not attempt another installation. Any steps taken + // (including partially completed steps) are not rolled back. Install steps + // must be specified and are used on first installation. + repeated Step install_steps = 4; + + // Actions to be taken for updating this recipe. On failure it stops + // executing steps and does not attempt another update for this recipe. Any + // steps taken (including partially completed steps) are not rolled back. + // Upgrade steps are not mandatory and are only used when upgrading. + repeated Step update_steps = 5; + + // Default is INSTALLED. The desired state the agent should maintain for this + // recipe. + // + // INSTALLED: The software recipe is installed on the instance but won't be + // updated to new versions. + // UPDATED: The software recipe is installed on the instance. The recipe is + // updated to a higher version, if a higher version of + // the recipe is assigned to this instance. + // REMOVE: Remove is unsupported for software recipes and attempts to + // create or update a recipe to the REMOVE state is rejected. + DesiredState desired_state = 6; +} + +// A request message for getting effective policy assigned to the instance. +message LookupEffectiveGuestPolicyRequest { + // 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]; + + // Short name of the OS running on the instance. The OS Config agent only + // provideS this field for targeting if OS Inventory is enabled for that + // instance. + string os_short_name = 2; + + // Version of the OS running on the instance. The OS Config agent only + // provide this field for targeting if OS Inventory is enabled for that + // VM instance. + string os_version = 3; + + // Architecture of OS running on the instance. The OS Config agent only + // provide this field for targeting if OS Inventory is enabled for that + // instance. + string os_architecture = 4; +} + +// The effective guest policy assigned to the instance. +message EffectiveGuestPolicy { + // A guest policy package including its source. + message SourcedPackage { + // Name of the guest policy providing this config. + string source = 1; + + // A software package to configure on the VM instance. + Package package = 2; + } + + // A guest policy package repository including its source. + message SourcedPackageRepository { + // Name of the guest policy providing this config. + string source = 1; + + // A software package repository to configure on the VM instance. + PackageRepository package_repository = 2; + } + + // A guest policy recipe including its source. + message SourcedSoftwareRecipe { + // Name of the guest policy providing this config. + string source = 1; + + // A software recipe to configure on the VM instance. + SoftwareRecipe software_recipe = 2; + } + + // List of package configurations assigned to the VM instance. + repeated SourcedPackage packages = 1; + + // List of package repository configurations assigned to the VM instance. + repeated SourcedPackageRepository package_repositories = 2; + + // List of recipes assigned to the VM instance. + repeated SourcedSoftwareRecipe software_recipes = 3; +}