From 4ee728da074ae019c575b07efff7bf261ff4b971 Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Tue, 10 Jan 2017 06:15:54 -0800 Subject: [PATCH] Shuffle files around as agreed. Also includes minor comment updates and a few field renames, based on outstanding feedback. --- README.md | 8 +++--- istio/api/.gitignore | 1 - istio/config/.gitignore | 1 - mixer/{api => }/v1/attributes.proto | 8 +++--- mixer/{api => }/v1/check.proto | 0 .../v1/config/aspect/denyChecker_config.proto | 6 ++--- .../v1/config/aspect/listChecker_config.proto | 8 +++--- mixer/v1/config/aspect/quota_config.proto | 21 +++++++++++++++ .../config/v1 => mixer/v1/config}/cfg.proto | 4 +-- .../descriptor}/attribute_descriptor.proto | 10 +++---- .../descriptor}/log_entry_descriptor.proto | 12 ++++++--- .../descriptor}/metric_descriptor.proto | 11 +++----- .../monitored_resource_descriptor.proto | 6 ++--- .../descriptor}/principal_descriptor.proto | 0 .../config/descriptor}/quota_descriptor.proto | 26 +++++++++---------- mixer/{api => }/v1/quota.proto | 2 +- mixer/{api => }/v1/report.proto | 0 mixer/{api => }/v1/service.proto | 0 18 files changed, 70 insertions(+), 54 deletions(-) delete mode 100644 istio/api/.gitignore delete mode 100644 istio/config/.gitignore rename mixer/{api => }/v1/attributes.proto (94%) rename mixer/{api => }/v1/check.proto (100%) rename istio/config/v1/aspect/denyChecker/cfg.proto => mixer/v1/config/aspect/denyChecker_config.proto (84%) rename istio/config/v1/aspect/listChecker/cfg.proto => mixer/v1/config/aspect/listChecker_config.proto (87%) create mode 100644 mixer/v1/config/aspect/quota_config.proto rename {istio/config/v1 => mixer/v1/config}/cfg.proto (98%) rename mixer/{config/v1 => v1/config/descriptor}/attribute_descriptor.proto (97%) rename mixer/{config/v1 => v1/config/descriptor}/log_entry_descriptor.proto (70%) rename mixer/{config/v1 => v1/config/descriptor}/metric_descriptor.proto (88%) rename mixer/{config/v1 => v1/config/descriptor}/monitored_resource_descriptor.proto (96%) rename mixer/{config/v1 => v1/config/descriptor}/principal_descriptor.proto (100%) rename mixer/{config/v1 => v1/config/descriptor}/quota_descriptor.proto (87%) rename mixer/{api => }/v1/quota.proto (97%) rename mixer/{api => }/v1/report.proto (100%) rename mixer/{api => }/v1/service.proto (100%) diff --git a/README.md b/README.md index 7778b890..2d5ccdd0 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,13 @@ # Istio APIs and Common Configuration Definitions -This repo defines component-level APIs and common configuration formats for the Istio +This repository defines component-level APIs and common configuration formats for the Istio platform. These definitions are specified using the [protobuf](https://github.com/google/protobuf) syntax. All other Istio repositories can take a dependency on the api repository. This repository *will not* depend on any other repos -We may check-in generated .pb.go and .pb.cc files here. - ## Standard vocabulary -All components of an Istio installation operate on a shared vocabulary of attributes. -A standard vocabulary of attributes including it meaning is available in this repo. +All components of an Istio installation operate on a shared vocabulary of attributes, +as defined in this repo. diff --git a/istio/api/.gitignore b/istio/api/.gitignore deleted file mode 100644 index 75feca5b..00000000 --- a/istio/api/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.pb.* diff --git a/istio/config/.gitignore b/istio/config/.gitignore deleted file mode 100644 index 75feca5b..00000000 --- a/istio/config/.gitignore +++ /dev/null @@ -1 +0,0 @@ -*.pb.* diff --git a/mixer/api/v1/attributes.proto b/mixer/v1/attributes.proto similarity index 94% rename from mixer/api/v1/attributes.proto rename to mixer/v1/attributes.proto index eba094a0..27b672d0 100644 --- a/mixer/api/v1/attributes.proto +++ b/mixer/v1/attributes.proto @@ -18,7 +18,7 @@ package istio.mixer.v1; import "google/protobuf/timestamp.proto"; -// An instance of this is delivered to the mixer with every +// An instance of this message is delivered to the mixer with every // API call. // // The general idea is to leverage the stateful gRPC streams from the @@ -52,7 +52,7 @@ message Attributes { // This is intended to leverage the stateful gRPC stream from the // proxy to the mixer. This dictionary is sent over only when a // stream to the mixer is first established and when the proxy's - // config changes and different attributes may be produced. + // configuration changes and different attributes may be produced. // // Once a dictionary has been sent over, it stays in effect until // a new dictionary is sent to replace it. The first request sent on a @@ -60,7 +60,7 @@ message Attributes { // any attribute updates. // // Dictionaries are independent of the attribute context and are thus global - // for the current gRPC stream. + // to each gRPC stream. map dictionary = 1; // The attribute context against which to operate. @@ -76,7 +76,7 @@ message Attributes { // to prevent an explosion of contexts in the mixer's memory space. // // TODO: Consider removing support for this feature. The proxy can achieve - // the same thing using multiple gRPC streams. The benefit of using streams + // the same effect using multiple gRPC streams. The benefit of using streams // would be that the mixer would be in control of the maximum number of streams // it allows, whereas with the current model the proxy could overwhelm the // mixer by creating too many contexts. diff --git a/mixer/api/v1/check.proto b/mixer/v1/check.proto similarity index 100% rename from mixer/api/v1/check.proto rename to mixer/v1/check.proto diff --git a/istio/config/v1/aspect/denyChecker/cfg.proto b/mixer/v1/config/aspect/denyChecker_config.proto similarity index 84% rename from istio/config/v1/aspect/denyChecker/cfg.proto rename to mixer/v1/config/aspect/denyChecker_config.proto index e1ec6aea..ad3efcb0 100644 --- a/istio/config/v1/aspect/denyChecker/cfg.proto +++ b/mixer/v1/config/aspect/denyChecker_config.proto @@ -14,8 +14,8 @@ syntax = "proto3"; -package istio.config.v1.aspect.denyChecker; +package istio.mixer.v1.config.aspect; -// Config - User visible configuration of this aspect -message Config { +// Configures a deny checker aspect +message DenyCheckerConfig { } diff --git a/istio/config/v1/aspect/listChecker/cfg.proto b/mixer/v1/config/aspect/listChecker_config.proto similarity index 87% rename from istio/config/v1/aspect/listChecker/cfg.proto rename to mixer/v1/config/aspect/listChecker_config.proto index 93da893c..5071f34b 100644 --- a/istio/config/v1/aspect/listChecker/cfg.proto +++ b/mixer/v1/config/aspect/listChecker_config.proto @@ -14,12 +14,10 @@ syntax = "proto3"; -package istio.config.v1.aspect.listChecker; +package istio.mixer.v1.config.aspect; - -// Config - User visible configuration of this aspect -// Must be defined as a proto -message Config { +// Configures a list checker aspect +message ListCheckerConfig { // blacklist determines if this behaves like a blacklist // default is whitelist bool blacklist = 1; diff --git a/mixer/v1/config/aspect/quota_config.proto b/mixer/v1/config/aspect/quota_config.proto new file mode 100644 index 00000000..606f5f93 --- /dev/null +++ b/mixer/v1/config/aspect/quota_config.proto @@ -0,0 +1,21 @@ +// Copyright 2017 Google Inc. +// +// 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 istio.mixer.v1.config.aspect; + +// Configures a quota aspect. +message QuotaConfig { +} diff --git a/istio/config/v1/cfg.proto b/mixer/v1/config/cfg.proto similarity index 98% rename from istio/config/v1/cfg.proto rename to mixer/v1/config/cfg.proto index 19fcdd98..38b3b35a 100644 --- a/istio/config/v1/cfg.proto +++ b/mixer/v1/config/cfg.proto @@ -17,11 +17,11 @@ syntax = "proto3"; import "google/protobuf/struct.proto"; -package istio.config.v1; +package istio.mixer.v1.config; // Configures a set of services // following example configures metrics collection and ratelimit for -// all services +// all services //# service config //subject: "namespace:ns1" //revision: "1011" diff --git a/mixer/config/v1/attribute_descriptor.proto b/mixer/v1/config/descriptor/attribute_descriptor.proto similarity index 97% rename from mixer/config/v1/attribute_descriptor.proto rename to mixer/v1/config/descriptor/attribute_descriptor.proto index d47fc7e4..50a7e285 100644 --- a/mixer/config/v1/attribute_descriptor.proto +++ b/mixer/v1/config/descriptor/attribute_descriptor.proto @@ -14,7 +14,7 @@ syntax = "proto3"; -package istio.mixer.v1; +package istio.mixer.v1.config.descriptor; // An `AttributeDescriptor` describes the schema of an Istio attribute type. // @@ -70,11 +70,11 @@ message AttributeDescriptor { // name with a component-specific suffix such as request_count-my_component string name = 1; - // The type of data carried by attributes - ValueType value_type = 2; - // An optional human-readable description of the attribute's purpose. - string description = 3; + string description = 2; + + // The type of data carried by attributes + ValueType value_type = 3; // Types of supported attribute values. enum ValueType { diff --git a/mixer/config/v1/log_entry_descriptor.proto b/mixer/v1/config/descriptor/log_entry_descriptor.proto similarity index 70% rename from mixer/config/v1/log_entry_descriptor.proto rename to mixer/v1/config/descriptor/log_entry_descriptor.proto index c474849a..ee53a5d3 100644 --- a/mixer/config/v1/log_entry_descriptor.proto +++ b/mixer/v1/config/descriptor/log_entry_descriptor.proto @@ -21,9 +21,13 @@ message LogEntryDescriptor { // The name of this descriptor. string name = 1; - // The set of attributes that are necessary to describe a log entry of this type. - repeated string attributes = 2; + // An optional concise name for the log entry type, which can be displayed in user interfaces. + // Use sentence case without an ending period, for example "Request count". + string display_name = 2; - // The monitored resource to associated with log entries of this type. - string monitored_resource_descriptor = 3; + // An optional description of the log entry type, which can be used in documentation. + string description = 3; + + // The set of attributes that are necessary to describe a log entry of this type. + repeated string attributes = 4; } diff --git a/mixer/config/v1/metric_descriptor.proto b/mixer/v1/config/descriptor/metric_descriptor.proto similarity index 88% rename from mixer/config/v1/metric_descriptor.proto rename to mixer/v1/config/descriptor/metric_descriptor.proto index e1326ee8..daa5bd17 100644 --- a/mixer/config/v1/metric_descriptor.proto +++ b/mixer/v1/config/descriptor/metric_descriptor.proto @@ -30,20 +30,17 @@ message MetricDescriptor { // The set of attributes that are necessary to describe a specific value cell // for a metric of this type. - repeated string dimension_attributes = 3; - - // The monitored resource to associate with metrics of this type. - string monitored_resource_descriptor = 4; + repeated string attributes = 3; // Whether the metric records instantaneous values, changes to a value, etc. - MetricKind metric_kind = 5; + MetricKind metric_kind = 4; // An optional description of the metric, which can be used in documentation. - string description = 6; + string description = 5; // An optional concise name for the metric, which can be displayed in user interfaces. // Use sentence case without an ending period, for example "Request count". - string display_name = 7; + string display_name = 6; // The kind of measurement. It describes how the data is reported. enum MetricKind { diff --git a/mixer/config/v1/monitored_resource_descriptor.proto b/mixer/v1/config/descriptor/monitored_resource_descriptor.proto similarity index 96% rename from mixer/config/v1/monitored_resource_descriptor.proto rename to mixer/v1/config/descriptor/monitored_resource_descriptor.proto index 1b4f8a0b..80ff9801 100644 --- a/mixer/config/v1/monitored_resource_descriptor.proto +++ b/mixer/v1/config/descriptor/monitored_resource_descriptor.proto @@ -22,10 +22,10 @@ message MonitoredResourceDescriptor { // The name of this descriptor string name = 1; - // The set of attributes that are necessary to describe a specific monitored resource. - repeated string attributes = 3; - // An optional detailed description of the monitored resource descriptor that might // be used in documentation. string description = 2; + + // The set of attributes that are necessary to describe a specific instance of a monitored resource. + repeated string attributes = 3; } diff --git a/mixer/config/v1/principal_descriptor.proto b/mixer/v1/config/descriptor/principal_descriptor.proto similarity index 100% rename from mixer/config/v1/principal_descriptor.proto rename to mixer/v1/config/descriptor/principal_descriptor.proto diff --git a/mixer/config/v1/quota_descriptor.proto b/mixer/v1/config/descriptor/quota_descriptor.proto similarity index 87% rename from mixer/config/v1/quota_descriptor.proto rename to mixer/v1/config/descriptor/quota_descriptor.proto index cc74f261..98e72342 100644 --- a/mixer/config/v1/quota_descriptor.proto +++ b/mixer/v1/config/descriptor/quota_descriptor.proto @@ -14,7 +14,7 @@ syntax = "proto3"; -package istio.mixer.v1; +package istio.mixer.v1.config.descriptor; // Configuration state for a particular quota. // @@ -23,7 +23,7 @@ package istio.mixer.v1; // The descriptor below lets you define a quota and indicate the maximum // amount values of this quota are allowed to hold. // -// A given quota is described by a set of attribtues. These attributes represent +// A given quota is described by a set of attributes. These attributes represent // the different dimensions to associate with the quota. A given quota holds a // unique value for potentially any combination of these attributes. // @@ -34,20 +34,20 @@ message QuotaDescriptor { // The name of this descriptor. string name = 1; + // A optional concise name for the quota, which can be displayed in user interfaces. + // Use sentence case without an ending period, for example "Request count". + string display_name = 2; + + // An optional description of the quota, which can be used in documentation. + string description = 3; + // The name of the attribute that supplies the amount for a given // quota allocation or release operation. - string amount_attribute = 2; + string amount_attribute = 4; // The set of attributes that are necessary to describe a specific value cell // for a quota of this type. - repeated string dimension_attributes = 3; - - // An optional description of the quota, which can be used in documentation. - string description = 4; - - // A optional concise name for the quota, which can be displayed in user interfaces. - // Use sentence case without an ending period, for example "Request count". - string display_name = 5; + repeated string attributes = 5; // The default imposed maximum amount for values of this quota. int64 max_amount = 6; @@ -58,11 +58,11 @@ message QuotaDescriptor { // Whether the quota's current value is tracked precisely or not. // Precisely tracked quotas only allow a relatively modest level of // scaling, whereas imprecise quotas can support a nearly unbounded - // level of scaling at the cost of potentially having inaccuracies. + // level of scaling at the cost of potential accounting inaccuracies. bool precise = 8; enum QuotaKind { - // Quota values are always explicitly manipulated via the Quota method. + // Quota values are always explicitly manipulated via API calls. ALLOCATION_LIMIT = 0; // Quota limit expresses a maximum amount over a rolling time interval diff --git a/mixer/api/v1/quota.proto b/mixer/v1/quota.proto similarity index 97% rename from mixer/api/v1/quota.proto rename to mixer/v1/quota.proto index 6b850512..51f82ff8 100644 --- a/mixer/api/v1/quota.proto +++ b/mixer/v1/quota.proto @@ -30,7 +30,7 @@ message QuotaRequest { OperationKind kind = 3; // Used for deduplicating quota allocation/free calls in the case of - // failed RPCs are retries. This should be a UUID per call, where the same + // failed RPCs and retries. This should be a UUID per call, where the same // UUID is used for retries of the same quota allocation or release call. string deduplication_id = 4; diff --git a/mixer/api/v1/report.proto b/mixer/v1/report.proto similarity index 100% rename from mixer/api/v1/report.proto rename to mixer/v1/report.proto diff --git a/mixer/api/v1/service.proto b/mixer/v1/service.proto similarity index 100% rename from mixer/api/v1/service.proto rename to mixer/v1/service.proto