|
| 1 | +# Migrating from xDS v2 to v3 |
| 2 | + |
| 3 | +To faciliate migrating from the v2 xDS APIs to v3, this repo supports both the |
| 4 | +v2 and v3 gRPC transports, with each transport supporting type URL rewriting of |
| 5 | +DiscoveryResponse to whatever version the client requests with |
| 6 | +api_resource_version. |
| 7 | + |
| 8 | +The migration requires care - for example, using v3-only fields too soon or trying to use |
| 9 | +deprecated v2 fields too late can cause Envoy to reject or improperly apply config. |
| 10 | + |
| 11 | +### Recommended Sequence |
| 12 | + |
| 13 | +This section assumes you have sufficient control over Envoy sidecar versions that you do |
| 14 | +not need to run v2 and v3 simultaneously for a long migration period. |
| 15 | + |
| 16 | +1. Make sure your oldest Envoy client supports final v2 message versions. |
| 17 | +2. |
| 18 | + 1. Ensure your control plane is not using any deprecated v2 fields. |
| 19 | + Deprecated v2 fields will cause errors when they are translated to v3 |
| 20 | + (because deprecated v2 fields are dropped in v3). |
| 21 | + 2. Configure a V3DiscoveryServer alongside the V2DiscoveryServer in your |
| 22 | + control plane. You can (and should) use the same (v2) Cache implementation |
| 23 | + in both servers. |
| 24 | +3. Deploy all Envoy clients to switch to both the v3 transport_api_version and |
| 25 | + resource_api_version in each respective xDS configs. As this happens, the V3DiscoveryServer |
| 26 | + will be translating your v2 resources to v3 automatically, and the V2DiscoveryServer will |
| 27 | + stop being used. |
| 28 | +4. |
| 29 | + 1. Rewrite your control plane code to use v3 resources, which means using |
| 30 | + V3SimpleCache (if you use SimpleCache). You may now start using v3-only |
| 31 | + message fields if you choose. |
| 32 | + 2. Drop the V2DiscoveryServer. |
| 33 | + |
| 34 | +### Alternative |
| 35 | + |
| 36 | +Another possible path to the one above is to switch to generating v3 in the |
| 37 | +control plane first (e.g. by using V3SimpleCache) and then deploying Envoy |
| 38 | +clients to use v3 transport and resource versions. |
| 39 | + |
| 40 | +This approach requires care to not use new V3-only fields until the client side |
| 41 | +upgrade is complete (or at least understand the consequences of doing so). |
0 commit comments