GRPC C++  1.39.1
xds_client.h
Go to the documentation of this file.
1 //
2 // Copyright 2019 gRPC authors.
3 //
4 // Licensed under the Apache License, Version 2.0 (the "License");
5 // you may not use this file except in compliance with the License.
6 // You may obtain a copy of the License at
7 //
8 // http://www.apache.org/licenses/LICENSE-2.0
9 //
10 // Unless required by applicable law or agreed to in writing, software
11 // distributed under the License is distributed on an "AS IS" BASIS,
12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 // See the License for the specific language governing permissions and
14 // limitations under the License.
15 //
16 
17 #ifndef GRPC_CORE_EXT_XDS_XDS_CLIENT_H
18 #define GRPC_CORE_EXT_XDS_XDS_CLIENT_H
19 
21 
22 #include <set>
23 #include <vector>
24 
25 #include "absl/strings/string_view.h"
26 #include "absl/types/optional.h"
27 
38 
39 namespace grpc_core {
40 
43 
44 class XdsClient : public DualRefCounted<XdsClient> {
45  public:
46  // Listener data watcher interface. Implemented by callers.
48  public:
49  virtual ~ListenerWatcherInterface() = default;
50  virtual void OnListenerChanged(XdsApi::LdsUpdate listener) = 0;
51  virtual void OnError(grpc_error_handle error) = 0;
52  virtual void OnResourceDoesNotExist() = 0;
53  };
54 
55  // RouteConfiguration data watcher interface. Implemented by callers.
57  public:
58  virtual ~RouteConfigWatcherInterface() = default;
59  virtual void OnRouteConfigChanged(XdsApi::RdsUpdate route_config) = 0;
60  virtual void OnError(grpc_error_handle error) = 0;
61  virtual void OnResourceDoesNotExist() = 0;
62  };
63 
64  // Cluster data watcher interface. Implemented by callers.
66  public:
67  virtual ~ClusterWatcherInterface() = default;
68  virtual void OnClusterChanged(XdsApi::CdsUpdate cluster_data) = 0;
69  virtual void OnError(grpc_error_handle error) = 0;
70  virtual void OnResourceDoesNotExist() = 0;
71  };
72 
73  // Endpoint data watcher interface. Implemented by callers.
75  public:
76  virtual ~EndpointWatcherInterface() = default;
78  virtual void OnError(grpc_error_handle error) = 0;
79  virtual void OnResourceDoesNotExist() = 0;
80  };
81 
82  // Factory function to get or create the global XdsClient instance.
83  // If *error is not GRPC_ERROR_NONE upon return, then there was
84  // an error initializing the client.
87 
88  // Most callers should not instantiate directly. Use GetOrCreate() instead.
89  XdsClient(std::unique_ptr<XdsBootstrap> bootstrap,
90  const grpc_channel_args* args);
91  ~XdsClient() override;
92 
93  const XdsBootstrap& bootstrap() const {
94  // bootstrap_ is guaranteed to be non-null since XdsClient::GetOrCreate()
95  // would return a null object if bootstrap_ was null.
96  return *bootstrap_;
97  }
98 
100  return *certificate_provider_store_;
101  }
102 
103  grpc_pollset_set* interested_parties() const { return interested_parties_; }
104 
105  // TODO(roth): When we add federation, there will be multiple channels
106  // inside the XdsClient, and the set of channels may change over time,
107  // but not every channel may use every one of the child channels, so
108  // this API will need to change. At minumum, we will need to hold a
109  // ref to the parent channelz node so that we can update its list of
110  // children as the set of xDS channels changes. However, we may also
111  // want to make this a bit more selective such that only those
112  // channels on which a given parent channel is actually requesting
113  // resources will actually be marked as its children.
114  void AddChannelzLinkage(channelz::ChannelNode* parent_channelz_node);
115  void RemoveChannelzLinkage(channelz::ChannelNode* parent_channelz_node);
116 
117  void Orphan() override;
118 
119  // Start and cancel listener data watch for a listener.
120  // The XdsClient takes ownership of the watcher, but the caller may
121  // keep a raw pointer to the watcher, which may be used only for
122  // cancellation. (Because the caller does not own the watcher, the
123  // pointer must not be used for any other purpose.)
124  // If the caller is going to start a new watch after cancelling the
125  // old one, it should set delay_unsubscription to true.
126  void WatchListenerData(absl::string_view listener_name,
127  std::unique_ptr<ListenerWatcherInterface> watcher);
128  void CancelListenerDataWatch(absl::string_view listener_name,
129  ListenerWatcherInterface* watcher,
130  bool delay_unsubscription = false);
131 
132  // Start and cancel route config data watch for a listener.
133  // The XdsClient takes ownership of the watcher, but the caller may
134  // keep a raw pointer to the watcher, which may be used only for
135  // cancellation. (Because the caller does not own the watcher, the
136  // pointer must not be used for any other purpose.)
137  // If the caller is going to start a new watch after cancelling the
138  // old one, it should set delay_unsubscription to true.
140  absl::string_view route_config_name,
141  std::unique_ptr<RouteConfigWatcherInterface> watcher);
142  void CancelRouteConfigDataWatch(absl::string_view route_config_name,
143  RouteConfigWatcherInterface* watcher,
144  bool delay_unsubscription = false);
145 
146  // Start and cancel cluster data watch for a cluster.
147  // The XdsClient takes ownership of the watcher, but the caller may
148  // keep a raw pointer to the watcher, which may be used only for
149  // cancellation. (Because the caller does not own the watcher, the
150  // pointer must not be used for any other purpose.)
151  // If the caller is going to start a new watch after cancelling the
152  // old one, it should set delay_unsubscription to true.
153  void WatchClusterData(absl::string_view cluster_name,
154  std::unique_ptr<ClusterWatcherInterface> watcher);
155  void CancelClusterDataWatch(absl::string_view cluster_name,
156  ClusterWatcherInterface* watcher,
157  bool delay_unsubscription = false);
158 
159  // Start and cancel endpoint data watch for a cluster.
160  // The XdsClient takes ownership of the watcher, but the caller may
161  // keep a raw pointer to the watcher, which may be used only for
162  // cancellation. (Because the caller does not own the watcher, the
163  // pointer must not be used for any other purpose.)
164  // If the caller is going to start a new watch after cancelling the
165  // old one, it should set delay_unsubscription to true.
166  void WatchEndpointData(absl::string_view eds_service_name,
167  std::unique_ptr<EndpointWatcherInterface> watcher);
168  void CancelEndpointDataWatch(absl::string_view eds_service_name,
169  EndpointWatcherInterface* watcher,
170  bool delay_unsubscription = false);
171 
172  // Adds and removes drop stats for cluster_name and eds_service_name.
174  absl::string_view lrs_server, absl::string_view cluster_name,
175  absl::string_view eds_service_name);
176  void RemoveClusterDropStats(absl::string_view /*lrs_server*/,
177  absl::string_view cluster_name,
178  absl::string_view eds_service_name,
179  XdsClusterDropStats* cluster_drop_stats);
180 
181  // Adds and removes locality stats for cluster_name and eds_service_name
182  // for the specified locality.
184  absl::string_view lrs_server, absl::string_view cluster_name,
185  absl::string_view eds_service_name,
188  absl::string_view /*lrs_server*/, absl::string_view cluster_name,
189  absl::string_view eds_service_name,
190  const RefCountedPtr<XdsLocalityName>& locality,
191  XdsClusterLocalityStats* cluster_locality_stats);
192 
193  // Resets connection backoff state.
194  void ResetBackoff();
195 
196  // Dumps the active xDS config in JSON format.
197  // Individual xDS resource is encoded as envoy.admin.v3.*ConfigDump. Returns
198  // envoy.service.status.v3.ClientConfig which also includes the config
199  // status (e.g., CLIENT_REQUESTED, CLIENT_ACKED, CLIENT_NACKED).
200  //
201  // Expected to be invoked by wrapper languages in their CSDS service
202  // implementation.
203  std::string DumpClientConfigBinary();
204 
205  // Helpers for encoding the XdsClient object in channel args.
206  grpc_arg MakeChannelArg() const;
208  const grpc_channel_args& args);
209 
210  private:
211  // Contains a channel to the xds server and all the data related to the
212  // channel. Holds a ref to the xds client object.
213  //
214  // Currently, there is only one ChannelState object per XdsClient
215  // object, and it has essentially the same lifetime. But in the
216  // future, when we add federation support, a single XdsClient may have
217  // multiple underlying channels to talk to different xDS servers.
218  class ChannelState : public InternallyRefCounted<ChannelState> {
219  public:
220  template <typename T>
221  class RetryableCall;
222 
223  class AdsCallState;
224  class LrsCallState;
225 
226  ChannelState(WeakRefCountedPtr<XdsClient> xds_client,
227  const XdsBootstrap::XdsServer& server);
228  ~ChannelState() override;
229 
230  void Orphan() override;
231 
232  grpc_channel* channel() const { return channel_; }
233  XdsClient* xds_client() const { return xds_client_.get(); }
234  AdsCallState* ads_calld() const;
235  LrsCallState* lrs_calld() const;
236 
237  void MaybeStartLrsCall();
238  void StopLrsCall();
239 
240  bool HasAdsCall() const;
241  bool HasActiveAdsCall() const;
242 
243  void StartConnectivityWatchLocked();
244  void CancelConnectivityWatchLocked();
245 
246  void SubscribeLocked(const std::string& type_url, const std::string& name)
247  ABSL_EXCLUSIVE_LOCKS_REQUIRED(&XdsClient::mu_);
248  void UnsubscribeLocked(const std::string& type_url, const std::string& name,
249  bool delay_unsubscription)
250  ABSL_EXCLUSIVE_LOCKS_REQUIRED(&XdsClient::mu_);
251 
252  private:
253  class StateWatcher;
254 
255  // The owning xds client.
256  WeakRefCountedPtr<XdsClient> xds_client_;
257 
258  const XdsBootstrap::XdsServer& server_;
259 
260  // The channel and its status.
261  grpc_channel* channel_;
262  bool shutting_down_ = false;
263  StateWatcher* watcher_ = nullptr;
264 
265  // The retryable XDS calls.
266  OrphanablePtr<RetryableCall<AdsCallState>> ads_calld_;
267  OrphanablePtr<RetryableCall<LrsCallState>> lrs_calld_;
268  };
269 
270  struct ListenerState {
271  std::map<ListenerWatcherInterface*,
272  std::unique_ptr<ListenerWatcherInterface>>
273  watchers;
274  // The latest data seen from LDS.
275  absl::optional<XdsApi::LdsUpdate> update;
276  XdsApi::ResourceMetadata meta;
277  };
278 
279  struct RouteConfigState {
280  std::map<RouteConfigWatcherInterface*,
281  std::unique_ptr<RouteConfigWatcherInterface>>
282  watchers;
283  // The latest data seen from RDS.
284  absl::optional<XdsApi::RdsUpdate> update;
285  XdsApi::ResourceMetadata meta;
286  };
287 
288  struct ClusterState {
289  std::map<ClusterWatcherInterface*, std::unique_ptr<ClusterWatcherInterface>>
290  watchers;
291  // The latest data seen from CDS.
292  absl::optional<XdsApi::CdsUpdate> update;
293  XdsApi::ResourceMetadata meta;
294  };
295 
296  struct EndpointState {
297  std::map<EndpointWatcherInterface*,
298  std::unique_ptr<EndpointWatcherInterface>>
299  watchers;
300  // The latest data seen from EDS.
301  absl::optional<XdsApi::EdsUpdate> update;
302  XdsApi::ResourceMetadata meta;
303  };
304 
305  struct LoadReportState {
306  struct LocalityState {
309  };
310 
311  XdsClusterDropStats* drop_stats = nullptr;
312  XdsClusterDropStats::Snapshot deleted_drop_stats;
313  std::map<RefCountedPtr<XdsLocalityName>, LocalityState,
315  locality_stats;
316  grpc_millis last_report_time = ExecCtx::Get()->Now();
317  };
318 
319  // Sends an error notification to all watchers.
320  void NotifyOnErrorLocked(grpc_error_handle error)
321  ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
322 
323  XdsApi::ClusterLoadReportMap BuildLoadReportSnapshotLocked(
324  bool send_all_clusters, const std::set<std::string>& clusters)
325  ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
326 
327  void UpdateResourceMetadataWithFailedParseResultLocked(
328  grpc_millis update_time, const XdsApi::AdsParseResult& result)
329  ABSL_EXCLUSIVE_LOCKS_REQUIRED(mu_);
330 
331  std::unique_ptr<XdsBootstrap> bootstrap_;
332  grpc_channel_args* args_;
333  const grpc_millis request_timeout_;
334  grpc_pollset_set* interested_parties_;
335  OrphanablePtr<CertificateProviderStore> certificate_provider_store_;
336  XdsApi api_;
337 
338  Mutex mu_;
339 
340  // The channel for communicating with the xds server.
341  OrphanablePtr<ChannelState> chand_ ABSL_GUARDED_BY(mu_);
342 
343  // One entry for each watched LDS resource.
344  std::map<std::string /*listener_name*/, ListenerState> listener_map_
345  ABSL_GUARDED_BY(mu_);
346  // One entry for each watched RDS resource.
347  std::map<std::string /*route_config_name*/, RouteConfigState>
348  route_config_map_ ABSL_GUARDED_BY(mu_);
349  // One entry for each watched CDS resource.
350  std::map<std::string /*cluster_name*/, ClusterState> cluster_map_
351  ABSL_GUARDED_BY(mu_);
352  // One entry for each watched EDS resource.
353  std::map<std::string /*eds_service_name*/, EndpointState> endpoint_map_
354  ABSL_GUARDED_BY(mu_);
355 
356  // Load report data.
357  std::map<
358  std::pair<std::string /*cluster_name*/, std::string /*eds_service_name*/>,
359  LoadReportState>
360  load_report_map_ ABSL_GUARDED_BY(mu_);
361 
362  // Stores the most recent accepted resource version for each resource type.
363  std::map<std::string /*type*/, std::string /*version*/> resource_version_map_
364  ABSL_GUARDED_BY(mu_);
365 
366  bool shutting_down_ ABSL_GUARDED_BY(mu_) = false;
367 };
368 
369 namespace internal {
372 // Sets bootstrap config to be used when no env var is set.
373 // Does not take ownership of config.
374 void SetXdsFallbackBootstrapConfig(const char* config);
375 } // namespace internal
376 
377 } // namespace grpc_core
378 
379 #endif // GRPC_CORE_EXT_XDS_XDS_CLIENT_H
absl::optional< XdsApi::CdsUpdate > update
Definition: cds.cc:114
ClusterWatcher * watcher
Definition: cds.cc:112
Definition: certificate_provider_store.h:38
Definition: dual_ref_counted.h:52
static ExecCtx * Get()
Gets pointer to current exec_ctx.
Definition: exec_ctx.h:222
grpc_millis Now()
Returns the stored current time relative to start if valid, otherwise refreshes the stored time,...
Definition: exec_ctx.cc:176
Definition: orphanable.h:76
Definition: sync.h:59
Definition: ref_counted_ptr.h:35
Definition: trace.h:61
Definition: ref_counted_ptr.h:186
Definition: xds_api.h:52
std::map< std::pair< std::string, std::string >, ClusterLoadReport > ClusterLoadReportMap
Definition: xds_api.h:550
Definition: xds_bootstrap.h:50
virtual void OnClusterChanged(XdsApi::CdsUpdate cluster_data)=0
virtual void OnError(grpc_error_handle error)=0
virtual void OnError(grpc_error_handle error)=0
virtual void OnEndpointChanged(XdsApi::EdsUpdate update)=0
virtual void OnListenerChanged(XdsApi::LdsUpdate listener)=0
virtual void OnError(grpc_error_handle error)=0
virtual void OnError(grpc_error_handle error)=0
virtual void OnRouteConfigChanged(XdsApi::RdsUpdate route_config)=0
Definition: xds_client.h:44
void WatchRouteConfigData(absl::string_view route_config_name, std::unique_ptr< RouteConfigWatcherInterface > watcher)
Definition: xds_client.cc:1907
void Orphan() override
Definition: xds_client.cc:1843
RefCountedPtr< XdsClusterLocalityStats > AddClusterLocalityStats(absl::string_view lrs_server, absl::string_view cluster_name, absl::string_view eds_service_name, RefCountedPtr< XdsLocalityName > locality)
Definition: xds_client.cc:2078
RefCountedPtr< XdsClusterDropStats > AddClusterDropStats(absl::string_view lrs_server, absl::string_view cluster_name, absl::string_view eds_service_name)
Definition: xds_client.cc:2024
void CancelClusterDataWatch(absl::string_view cluster_name, ClusterWatcherInterface *watcher, bool delay_unsubscription=false)
Definition: xds_client.cc:1968
void CancelEndpointDataWatch(absl::string_view eds_service_name, EndpointWatcherInterface *watcher, bool delay_unsubscription=false)
Definition: xds_client.cc:2006
void WatchEndpointData(absl::string_view eds_service_name, std::unique_ptr< EndpointWatcherInterface > watcher)
Definition: xds_client.cc:1986
static RefCountedPtr< XdsClient > GetFromChannelArgs(const grpc_channel_args &args)
Definition: xds_client.cc:2494
void AddChannelzLinkage(channelz::ChannelNode *parent_channelz_node)
Definition: xds_client.cc:1823
void RemoveChannelzLinkage(channelz::ChannelNode *parent_channelz_node)
Definition: xds_client.cc:1833
std::string DumpClientConfigBinary()
Definition: xds_client.cc:2293
void CancelListenerDataWatch(absl::string_view listener_name, ListenerWatcherInterface *watcher, bool delay_unsubscription=false)
Definition: xds_client.cc:1889
~XdsClient() override
Definition: xds_client.cc:1815
void WatchListenerData(absl::string_view listener_name, std::unique_ptr< ListenerWatcherInterface > watcher)
Definition: xds_client.cc:1869
grpc_arg MakeChannelArg() const
Definition: xds_client.cc:2488
grpc_pollset_set * interested_parties() const
Definition: xds_client.h:103
XdsClient(std::unique_ptr< XdsBootstrap > bootstrap, const grpc_channel_args *args)
Definition: xds_client.cc:1795
static RefCountedPtr< XdsClient > GetOrCreate(const grpc_channel_args *args, grpc_error_handle *error)
Definition: xds_client.cc:2396
const XdsBootstrap & bootstrap() const
Definition: xds_client.h:93
void ResetBackoff()
Definition: xds_client.cc:2139
void WatchClusterData(absl::string_view cluster_name, std::unique_ptr< ClusterWatcherInterface > watcher)
Definition: xds_client.cc:1948
void RemoveClusterDropStats(absl::string_view, absl::string_view cluster_name, absl::string_view eds_service_name, XdsClusterDropStats *cluster_drop_stats)
Definition: xds_client.cc:2058
CertificateProviderStore & certificate_provider_store()
Definition: xds_client.h:99
void RemoveClusterLocalityStats(absl::string_view, absl::string_view cluster_name, absl::string_view eds_service_name, const RefCountedPtr< XdsLocalityName > &locality, XdsClusterLocalityStats *cluster_locality_stats)
Definition: xds_client.cc:2115
void CancelRouteConfigDataWatch(absl::string_view route_config_name, RouteConfigWatcherInterface *watcher, bool delay_unsubscription=false)
Definition: xds_client.cc:1929
Definition: xds_client_stats.h:102
Definition: xds_client_stats.h:156
Definition: channelz.h:174
int64_t grpc_millis
Definition: exec_ctx.h:37
grpc_error_handle error
Definition: lame_client.cc:54
void UnsetGlobalXdsClientForTest()
Definition: xds_client.cc:2449
void SetXdsChannelArgsForTest(grpc_channel_args *args)
Definition: xds_client.cc:2444
void SetXdsFallbackBootstrapConfig(const char *config)
Definition: xds_client.cc:2454
Round Robin Policy.
Definition: backend_metric.cc:26
TraceFlag grpc_xds_client_refcount_trace(false, "xds_client_refcount")
Definition: xds_client.h:42
TraceFlag grpc_xds_client_trace(false, "xds_client")
Definition: xds_client.h:41
std::unique_ptr< T, Deleter > OrphanablePtr
Definition: orphanable.h:67
struct grpc_pollset_set grpc_pollset_set
Definition: pollset_set.h:31
RefCountedPtr< LoadBalancingPolicy::Config > config
Definition: priority.cc:60
A single argument...
Definition: grpc_types.h:103
An array of arguments that can be passed around.
Definition: grpc_types.h:132
Definition: channel.h:105
Definition: xds_api.h:619
Definition: xds_api.h:395
Definition: xds_api.h:451
Definition: xds_api.h:238
Definition: xds_api.h:149
Definition: xds_bootstrap.h:61
XdsClusterLocalityStats::Snapshot deleted_locality_stats
Definition: xds_client.h:308
XdsClusterLocalityStats * locality_stats
Definition: xds_client.h:307
Definition: xds_client_stats.h:107
Definition: xds_client_stats.h:174
Definition: xds_client_stats.h:46
Definition: error_internal.h:41
std::string eds_service_name
Definition: xds_cluster_resolver.cc:74
std::string cluster_name
Definition: xds_cluster_resolver.cc:66