Skip to content

docs: clarify xds docs with warming information #6236

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
htuch merged 4 commits into from
Mar 12, 2019
Merged

docs: clarify xds docs with warming information #6236

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0624a09
update xds docs with warming
ramaraochavali Mar 10, 2019
2e71cde
format and minor correction
ramaraochavali Mar 10, 2019
cd8ce60
review comments
ramaraochavali Mar 10, 2019
a5fc137
review comments
ramaraochavali Mar 12, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 17 additions & 1 deletion api/XDS_PROTOCOL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -151,7 +151,9 @@ For EDS/RDS, the management server does not need to supply every requested
resource and may also supply additional, unrequested resources. `resource_names`
is only a hint. Envoy will silently ignore any superfluous resources. When a
requested resource is missing in a RDS or EDS update, Envoy will retain the last
known value for this resource. The management server may be able to infer all
known value for this resource except in the case where the `Cluster` or `Listener`
is being warmed. See [Resource warming](#resource-warming) section below on the expectations
during warming. The management server may be able to infer all
the required EDS/RDS resources from the `node` identification in the
`DiscoveryRequest`, in which case this hint may be discarded. An empty EDS/RDS
`DiscoveryResponse` is effectively a nop from the perspective of the respective
Expand Down Expand Up @@ -209,6 +211,20 @@ multiple `DiscoveryRequests` at a version until a new version is ready.
An implication of the above resource update sequencing is that Envoy does not
expect a `DiscoveryResponse` for every `DiscoveryRequest` it issues.

### Resource warming

[`Clusters`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/cluster_manager.html#cluster-warming)
and [`Listeners`](https://www.envoyproxy.io/docs/envoy/latest/configuration/listeners/lds#config-listeners-lds)
go through `warming` before they can serve requests. This process happens both during
[`Envoy initialization`](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/init.html#initialization)
and when the `Cluster` or `Listener` is updated. Warming of `Cluster` is completed only when a
`ClusterLoadAssignment` response is supplied by management server. Similarly warming of `Listener`

@venilnoronha venilnoronha Mar 10, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: s/Similarly/Similarly,

is completed only when a `RouteConfiguration` is suppled by management server if the listener

@venilnoronha venilnoronha Mar 10, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: remove extra space after `RouteConfiguration`

refers to an RDS configuration. Management Server is expected to provide the EDS/RDS updates during

@venilnoronha venilnoronha Mar 10, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: s/Server/server

warming. If management server does not provide EDS/RDS information, Envoy will not initialize
it self during initialization phase and the updates sent via CDS/LDS will not take effect till

@venilnoronha venilnoronha Mar 10, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

s/it self/itself

EDS/RDS responses are supplied.

#### Eventual consistency considerations

Since Envoy's xDS APIs are eventually consistent, traffic may drop briefly
Expand Down