|
1 | 1 | # Mesh Configuration Protocol (MCP) |
2 | 2 |
|
3 | | -## Introduction |
| 3 | +MCP represents a now-deprecated configuration subscription API. |
| 4 | +[XDS](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) is now used. |
4 | 5 |
|
5 | | -This folder contains the proto buffers for the Mesh Configuration |
6 | | -Protocol (MCP). MCP is based on |
7 | | -[XDS](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_protocol) |
8 | | -and maintains conceptual alignment with it, despite the specific |
9 | | -service and proto definitions being different. |
10 | | - |
11 | | -## Overview |
12 | | - |
13 | | -MCP is a subscription-based configuration distribution API. The |
14 | | -configuration consumer (i.e. sink) requests updates for collections of |
15 | | -resources from a configuration producer (i.e. source). The source |
16 | | -pushes resource updates to the sink when resources are added, updated, |
17 | | -or deleted. The sink positively ACK's the resource update, if it was |
18 | | -accepted, and NACK's if it was rejected, e.g. because a resource was |
19 | | -invalid. The source may push additional update once the previous |
20 | | -update was ACK/NACK'd. The source should only have one outstanding |
21 | | -update (per-collection) in flight at a time. |
22 | | - |
23 | | -MCP is a pair of bidirectional streaming gRPC API services |
24 | | -(`ResourceSource` and `ResourceSink`). |
25 | | - |
26 | | -* The `ResourceSource` service is used when the resource source is the |
27 | | -server and the sink is a client. By default, Galley implements the |
28 | | -`ResourceSource` service and Pilot/Mixer connect as clients. |
29 | | - |
30 | | -* The `ResourceSink` service is used when the resource source is a |
31 | | -client and the sink is the server. Galley can be configured to |
32 | | -optionally "dial-out" to a remote configuration sink, e.g. Pilot is in |
33 | | -another cluster where it cannot, as a client, initiate |
34 | | -connection to Galley. In this scenario, Pilot would implement the |
35 | | -`ResourceSink` service and Galley would connect as a client. |
36 | | - |
37 | | -ResourceSource and ResourceSink are semantically equivalent with |
38 | | -regards to the message exchange. The only meaningful difference is who |
39 | | -initiates the connection and opens the grpc stream. |
40 | | - |
41 | | -## Data model |
42 | | - |
43 | | -MCP is the mechanism of transport whereby Pilot and Mixer can be |
44 | | -configured by a manager component. MCP defines a common per-resource |
45 | | -metadata format and resource specific contents is defined elsewhere |
46 | | -(e.g. <https://github.com/istio/api/tree/master/networking/v1beta1>). |
47 | | - |
48 | | -### Collections |
49 | | - |
50 | | -Resources of the same type are organized into named |
51 | | -collections. Istio API collection names are of the form |
52 | | -`istio/<area>/<version>/<api>` where `<area>`, `<version>`, and `<api>` |
53 | | -are defined by the [API style guidelines](../GUIDELINES.md). For |
54 | | -example, the collection name for VirtualService is |
55 | | -`istio/networking/v1beta1/virtualservices`. |
56 | | - |
57 | | -### Metadata |
58 | | - |
59 | | -## Connection establishment |
60 | | - |
61 | | -* `ResourceSource` service - The client is the resource sink. The |
62 | | -client dials the server and establishes a new gRPC stream. The client |
63 | | -sends RequestResources and receive Resources messages. |
64 | | - |
65 | | - |
66 | | - |
67 | | -* `ResourceSink` service - The client is the resource source. The |
68 | | -client dials the server and establishes a new gRPC stream. The server |
69 | | -sends RequestResources and receive Resources messages. |
70 | | - |
71 | | - |
72 | | - |
73 | | -## Configuration updates |
74 | | - |
75 | | -The following overview applies to both ResourceSink and ResourceSource |
76 | | -services, regardless of client/server roles. |
77 | | - |
78 | | -The resource update protocol is derived from Incremental xDS. The |
79 | | -protocol exchange is mostly the same except that resource hints have |
80 | | -been removed. Most of the text and diagrams below are copied from the |
81 | | -Incremental xDS docs and adjusted accordingly. |
82 | | - |
83 | | -In MCP, resources are first organized by collection. Within each |
84 | | -collection, resources are uniquely identifiable by their metadata |
85 | | -name. Individual resources are versioned to differentiate newer |
86 | | -versions of the same named resource. |
87 | | - |
88 | | -A `RequestResource` message can be sent in two situations: |
89 | | - |
90 | | -* Initial message in an MCP bidirectional change stream |
91 | | - |
92 | | -* As an ACK or NACK response to a previous `Resources` message. In |
93 | | -this case the `response_nonce` is set to the nonce value from the |
94 | | -`Resources` message. ACK/NACK is determined by the presence of |
95 | | -`error_detail` in the subsequent request. |
96 | | - |
97 | | -The initial `RequestResources` messages includes the collection |
98 | | -corresponding to the subscribed set of resources |
99 | | -(e.g. VirtualService), the node sink identifier, and nonce fields, and |
100 | | -initial_resource_version (more on that later). The source send a |
101 | | -`Resources` message when the requested resources are available. After |
102 | | -processing the `Resources` message , the sink sends a new |
103 | | -`RequestResources` message on the stream, specifying the last version |
104 | | -successfully applied and the nonce provided by the source. |
105 | | - |
106 | | -The nonce field is used to pair `RequestResources` and `Resources` |
107 | | -messages per collection. The source should only send one outstanding |
108 | | -`Resource` message at a time (per-collection) and wait for the sink to |
109 | | -ACK/NACK. Upon receiving an update, the sink is expected to send an |
110 | | -ACK/NACK relatively quickly after decoding, validating, and persisting |
111 | | -the update to its internal configuration store. |
112 | | - |
113 | | -The source should ignore requests with stale and unknown nonces that |
114 | | -do not match the nonce in the most recently sent `Resource` message. |
115 | | - |
116 | | -### Success examples |
117 | | - |
118 | | -The following example shows the sink receiving a sequence of changes |
119 | | -which are successfully ACK'd. |
120 | | - |
121 | | - |
122 | | - |
123 | | -The following example shows the same desired resource delivered with |
124 | | -incremental updates. This example assumes incremental is supported by |
125 | | -the source. When source does not support incremental updates, the |
126 | | -pushed `Resources` will always have incremental set to false, |
127 | | -regardless of whether the sink requested an incremental update. At any |
128 | | -time, the source can decide to push a full-state update, ignoring the |
129 | | -sink's request. Both sides must negotiate (i.e. agree) to use |
130 | | -incremental on a per request/response basis for an update to be sent |
131 | | -incrementally. |
132 | | - |
133 | | - |
134 | | - |
135 | | -### Error example |
136 | | - |
137 | | -The following example shows what happens when a change cannot be applied. |
138 | | - |
139 | | - |
140 | | - |
141 | | -The sink should only NACK in _exceptional_ cases. For example, if a set of |
142 | | -resources was invalid, malformed, or could not be decoded. NACK'd updates |
143 | | -should raise an alarm for subsequent investigation by a human. The source |
144 | | -should not resend the same set of resources that were previously NACK'd. |
145 | | -Canary pushes to dedicated sinks may also be used to verify correctness |
146 | | -(non-NACK) before pushing to a larger fleet of resource sinks. |
147 | | - |
148 | | -The nonce in MCP is used to match RequestResources and Resources. On |
149 | | -reconnect, the sinks may attempt to resume a session with the same |
150 | | -source by specifying the known resources version with |
151 | | -initial_resource_version for each collection. |
| 6 | +A few stubs of MCP remain in usage for backwards compatibility. |
0 commit comments