Skip to content

Commit cf7f8a4

Browse files
Martin Taillefergeeknoid
Martin Taillefer
authored and
geeknoid
committed
Migrate mixer API and config to this repo.
This clearly separates mixer's API and configuration surface from the implementation. This is designed to make it possible to replace the mixer in a fully compatible way.
1 parent 81854bc commit cf7f8a4

12 files changed

+592
-16
lines changed

‎README.md

+7-16
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,15 @@
1-
# istioapi
2-
API, Config Schema Definitions and Standard Vocabulary definitions for the istio project
1+
# Istio APIs and Common Configuration Definitions
32

3+
This repo defines component-level APIs and common configuration formats for the Istio
4+
platform. These definitions are specified using the [protobuf](https://github.com/google/protobuf)
5+
syntax.
46

5-
Usually definitions are in the form on .proto files.
6-
In the context of config, Proto is used as a schema description language.
7-
8-
##
9-
All other repositories can depend on istioapi
10-
This repository *will not* depend on any other repos
7+
All other Istio repositories can take a dependency on the api
8+
repository. This repository *will not* depend on any other repos
119

12-
##
1310
We may check-in generated .pb.go and .pb.cc files here.
1411

15-
16-
## API definitions
17-
istio/api
18-
19-
## Schema definitions
20-
istio/config
21-
2212
## Standard vocabulary
13+
2314
All components of an Istio installation operate on a shared vocabulary of attributes.
2415
A standard vocabulary of attributes including it meaning is available in this repo.

‎mixer/api/v1/attributes.proto

+106
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
// Copyright 2016 Google Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package istio.mixer.v1;
18+
19+
import "google/protobuf/timestamp.proto";
20+
21+
// An instance of this is delivered to the mixer with every
22+
// API call.
23+
//
24+
// The general idea is to leverage the stateful gRPC streams from the
25+
// proxy to the mixer to keep to a minimum the 'attribute chatter'.
26+
// Only delta attributes are sent over, multiple concurrent attribute
27+
// contexts can be used to avoid thrashing, and attribute indices are used to
28+
// keep the wire protocol maximally efficient.
29+
//
30+
// Producing this message is the responsibility of the mixer's client
31+
// library which is linked into different proxy implementations.
32+
//
33+
// The processing order for this state in the mixer is:
34+
//
35+
// * Any new dictionary is applied
36+
//
37+
// * The requested attribute context is looked up. If no such context has been defined, a
38+
// new context is automatically created and initialized to the empty state. When a gRPC
39+
// stream is first created, there are no attribute contexts for the stream.
40+
//
41+
// * If reset_context is true, then the attribute context is reset to the
42+
// empty state.
43+
//
44+
// * All attribute changes are applied to the attribute context.
45+
//
46+
// * All deleted attributes are removed from the attribute context.
47+
//
48+
message Attributes {
49+
// A dictionary that provides a mapping of shorthand index values to
50+
// attribute names.
51+
//
52+
// This is intended to leverage the stateful gRPC stream from the
53+
// proxy to the mixer. This dictionary is sent over only when a
54+
// stream to the mixer is first established and when the proxy's
55+
// config changes and different attributes may be produced.
56+
//
57+
// Once a dictionary has been sent over, it stays in effect until
58+
// a new dictionary is sent to replace it. The first request sent on a
59+
// stream must include a dictionary, otherwise the mixer can't process
60+
// any attribute updates.
61+
//
62+
// Dictionaries are independent of the attribute context and are thus global
63+
// for the current gRPC stream.
64+
map<int32, string> dictionary = 1;
65+
66+
// The attribute context against which to operate.
67+
//
68+
// The mixer keeps different contexts live for any proxy gRPC stream. This
69+
// allows the proxy to maintain multiple concurrent 'bags of attributes'
70+
// within the mixer.
71+
//
72+
// If the proxy doesn't want to leverage multiple contexts, it just passes
73+
// 0 here for every request.
74+
//
75+
// The proxy is configured to use a maximum number of attribute contexts in order
76+
// to prevent an explosion of contexts in the mixer's memory space.
77+
//
78+
// TODO: Consider removing support for this feature. The proxy can achieve
79+
// the same thing using multiple gRPC streams. The benefit of using streams
80+
// would be that the mixer would be in control of the maximum number of streams
81+
// it allows, whereas with the current model the proxy could overwhelm the
82+
// mixer by creating too many contexts.
83+
int32 attribute_context = 2;
84+
85+
// When true, resets the current attribute context to the empty state before
86+
// applying any incoming attributes.
87+
//
88+
// Resetting contexts is useful to constrain the amount of resources used by
89+
// the mixer. The proxy needs to intelligently manage a pool of contexts.
90+
// It may be useful to reset a context when certain big events happen, such
91+
// as when an HTTP2 connection into the proxy terminates.
92+
bool reset_context = 3;
93+
94+
// Attributes being updated within the specified attribute context. These maps
95+
// add and/or overwrite the context's current set of attributes.
96+
map<int32, string> string_attributes = 4;
97+
map<int32, int64> int64_attributes = 5;
98+
map<int32, double> double_attributes = 6;
99+
map<int32, bool> bool_attributes = 7;
100+
map<int32, google.protobuf.Timestamp> timestamp_attributes = 8;
101+
map<int32, bytes> bytes_attributes = 9;
102+
103+
// Attributes that should be removed from the specified attribute context. Deleting
104+
// attributes which aren't currently in the attribute context is not considered an error.
105+
repeated int32 deleted_attributes = 10;
106+
}

‎mixer/api/v1/check.proto

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright 2016 Google Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package istio.mixer.v1;
18+
19+
import "google/rpc/status.proto";
20+
import "mixer/api/v1/attribute.proto";
21+
22+
// Used to verify preconditions before performing an action.
23+
message CheckRequest {
24+
// Index within the stream for this request, used to match to responses
25+
int64 request_index = 1;
26+
27+
// The attributes to use for this request
28+
Attributes attribute_update = 2;
29+
}
30+
31+
message CheckResponse {
32+
// Index of the request this response is associated with
33+
int64 request_index = 1;
34+
35+
// Indicates whether or not the preconditions succeeded
36+
google.rpc.Status result = 2;
37+
}

‎mixer/api/v1/quota.proto

+72
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
// Copyright 2016 Google Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package istio.mixer.v1;
18+
19+
import "google/rpc/status.proto";
20+
import "mixer/api/v1/attribute.proto";
21+
22+
message QuotaRequest {
23+
// Index within the stream for this request, used to match to responses
24+
int64 request_index = 1;
25+
26+
// The attributes to use for this request
27+
Attributes attribute_update = 2;
28+
29+
// what kind of quota operation to perform
30+
OperationKind kind = 3;
31+
32+
// Used for deduplicating quota allocation/free calls in the case of
33+
// failed RPCs are retries. This should be a UUID per call, where the same
34+
// UUID is used for retries of the same quota allocation or release call.
35+
string deduplication_id = 4;
36+
37+
enum OperationKind {
38+
QUOTA_MODE_UNSPECIFIED = 0;
39+
40+
// Allocate the specified amount, fail if insufficient resources available.
41+
ALLOC_NORMAL = 1;
42+
43+
// Allocate from 0 to the specified amount, never fails.
44+
ALLOC_BEST_EFFORT = 2;
45+
46+
// Release from 0 to the specified amount, never fails.
47+
RELEASE_BEST_EFFORT = 3;
48+
49+
// Return the current content of the quota value cell.
50+
QUERY = 4;
51+
}
52+
}
53+
54+
// Used to update quota values before and/or after performing an action.
55+
//
56+
// A common use case for quotas is to implement rate limits within a service.
57+
// Quotas can also be used to impose upper limits on the number of specific
58+
// resources exposed by a service to its consumers.
59+
message QuotaResponse {
60+
// Index of the request this response is associated with
61+
int64 request_index = 1;
62+
63+
// Results, one for each operation in the request.
64+
// This map is indexed by the quota_operation_id of the individual quota operations.
65+
oneof result {
66+
// The effective amount of quota
67+
uint64 effective_amount = 2;
68+
69+
// An error indication in case the quota operation failed
70+
google.rpc.Status error = 3;
71+
}
72+
}

‎mixer/api/v1/report.proto

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright 2016 Google Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package istio.mixer.v1;
18+
19+
import "google/rpc/status.proto";
20+
import "mixer/api/v1/attribute.proto";
21+
22+
// Used to report telemetry after performing an action.
23+
message ReportRequest {
24+
// Index within the stream for this request, used to match to responses
25+
int64 request_index = 1;
26+
27+
// The attributes to use for this request
28+
Attributes attribute_update = 2;
29+
}
30+
31+
message ReportResponse {
32+
// Index of the request this response is associated with
33+
int64 request_index = 1;
34+
35+
// Indicates whether the report was processed or not
36+
google.rpc.Status result = 2;
37+
}

‎mixer/api/v1/service.proto

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Copyright 2016 Google Inc.
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// http://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
syntax = "proto3";
16+
17+
package istio.mixer.v1;
18+
19+
import "api/mixer/v1/check.proto";
20+
import "api/mixer/v1/report.proto";
21+
import "api/mixer/v1/quota.proto";
22+
23+
// The Istio Mixer API
24+
service Mixer {
25+
// Checks preconditions before performing an operation.
26+
// The preconditions enforced depend on the set of supplied attributes
27+
// and the active configuration.
28+
rpc Check(stream CheckRequest) returns (stream CheckResponse) {}
29+
30+
// Reports telemetry, such as logs and metrics.
31+
// The reported information depends on the set of supplied attributes
32+
// and the active configuration.
33+
rpc Report(stream ReportRequest) returns (stream ReportResponse) {}
34+
35+
// Quota allocates and releases quota.
36+
rpc Quota(stream QuotaRequest) returns (stream QuotaResponse) {}
37+
}

0 commit comments

Comments
 (0)