admin: complete /config_dump

This completes initial implementation of the /config_dump admin endpoint,
allowing for detailed display of the currently loaded Envoy configuration,
including versions of each resource.

Fixes #2421
Fixes #2172

Signed-off-by: Matt Klein <[email protected]>

api/docs/BUILD

@@ -12,6 +12,7 @@ package_group(
 proto_library(
     name = "protos",
     deps = [
+        "//envoy/admin/v2alpha:config_dump",
         "//envoy/api/v2:cds",
         "//envoy/api/v2:discovery",
         "//envoy/api/v2:eds",

api/envoy/admin/v2alpha/config_dump.proto

@@ -13,18 +13,15 @@ import "gogoproto/gogo.proto";
 
 // [#protodoc-title: ConfigDump]
 
-// The /config_dump admin endpoint uses this wrapper message to maintain and serve arbitrary
-// configuration information from any component in Envoy.
-// TODO(jsedgwick) In the future, we may want to formalize this further with an RPC for config_dump,
-// and perhaps even with an RPC per config type. That strategy across all endpoints will allow for
-// more flexibility w.r.t. protocol, serialization, parameters, etc.
+// The :ref:`/config_dump <operations_admin_interface_config_dump>` admin endpoint uses this wrapper
+// message to maintain and serve arbitrary configuration information from any component in Envoy.
 message ConfigDump {
-  // This map is serialized and dumped in its entirety at the /config_dump endpoint.
+  // This map is serialized and dumped in its entirety at the
+  // :ref:`/config_dump <operations_admin_interface_config_dump>` endpoint.
   //
   // Keys should be a short descriptor of the config object they map to. For example, Envoy's HTTP
-  // routing subsystem might use "routes" as the key for its config, for which it uses the message
-  // RouteConfigDump as defined below. In the future, the key will also be used to filter the output
-  // of the /config_dump endpoint.
+  // routing subsystem uses "routes" as the key for its config, for which it uses the message
+  // :ref:`RoutesConfigDump <envoy_api_msg_admin.v2alpha.RoutesConfigDump>` as defined below.
   map<string, google.protobuf.Any> configs = 1 [(gogoproto.nullable) = false];
 }
 
@@ -40,15 +37,17 @@ message BootstrapConfigDump {
 // configuration information can be used to recreate an Envoy configuration by populating all
 // listeners as static listeners or by returning them in a LDS response.
 message ListenersConfigDump {
-  // This is the *version_info* in the last processed LDS discovery response. If there
-  // are only static bootstrap listeners, this field will be "".
+  // This is the :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` in the
+  // last processed LDS discovery response. If there are only static bootstrap listeners, this field
+  // will be "".
   string version_info = 1;
 
   // Describes a dynamically loaded cluster via the LDS API.
   message DynamicListener {
     // This is the per-resource version information. This version is currently taken from the
-    // *version_info* field at the time that the listener was loaded. In the future, discrete
-    // per-listener versions may be supported by the API.
+    // :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` field at the time
+    // that the listener was loaded. In the future, discrete per-listener versions may be supported
+    // by the API.
     string version_info = 1;
 
     // The listener config.
@@ -79,15 +78,17 @@ message ListenersConfigDump {
 // configuration information can be used to recreate an Envoy configuration by populating all
 // clusters as static clusters or by returning them in a CDS response.
 message ClustersConfigDump {
-  // This is the *version_info* in the last processed CDS discovery response. If there
-  // are only static bootstrap clusters, this field will be "".
+  // This is the :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` in the
+  // last processed CDS discovery response. If there are only static bootstrap clusters, this field
+  // will be "".
   string version_info = 1;
 
   // Describes a dynamically loaded cluster via the CDS API.
   message DynamicCluster {
     // This is the per-resource version information. This version is currently taken from the
-    // *version_info* field at the time that the cluster was loaded. In the future, discrete
-    // per-cluster versions may be supported by the API.
+    // :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` field at the time
+    // that the cluster was loaded. In the future, discrete per-cluster versions may be supported by
+    // the API.
     string version_info = 1;
 
     // The cluster config.
@@ -116,7 +117,8 @@ message ClustersConfigDump {
 message RoutesConfigDump {
   message DynamicRouteConfig {
     // This is the per-resource version information. This version is currently taken from the
-    // *version_info* field at the time that the route configuration was loaded.
+    // :ref:`version_info <envoy_api_field_DiscoveryResponse.version_info>` field at the time that
+    // the route configuration was loaded.
     string version_info = 1;
 
     // The route config.

api/envoy/config/filter/http/ip_tagging/v2/ip_tagging.proto

@@ -9,6 +9,9 @@ import "google/protobuf/wrappers.proto";
 
 import "validate/validate.proto";
 
+// [#protodoc-title: IP tagging]
+// IP tagging :ref:`configuration overview <config_http_filters_ip_tagging>`.
+
 message IPTagging {
 
   // The type of requests the filter should apply to. The supported types

docs/build.sh

@@ -49,6 +49,7 @@ bazel --batch build ${BAZEL_BUILD_OPTIONS} @envoy_api//docs:protos --aspects \
 # These are the protos we want to put in docs, this list will grow.
 # TODO(htuch): Factor this out of this script.
 PROTO_RST="
+  /envoy/admin/v2alpha/config_dump/envoy/admin/v2alpha/config_dump.proto.rst
   /envoy/api/v2/core/address/envoy/api/v2/core/address.proto.rst
   /envoy/api/v2/core/base/envoy/api/v2/core/base.proto.rst
   /envoy/api/v2/core/config_source/envoy/api/v2/core/config_source.proto.rst

docs/root/api-v2/admin/admin.rst

@@ -0,0 +1,8 @@
+Admin
+========
+
+.. toctree::
+  :glob:
+  :maxdepth: 2
+
+  ../admin/v2alpha/config_dump.proto

docs/root/api-v2/api.rst

@@ -14,5 +14,6 @@ v2 API reference
   config/filter/filter
   config/health_checker/health_checker
   config/transport_socket/transport_socket
+  admin/admin
   common_messages/common_messages
   types/types

docs/root/intro/version_history.rst

@@ -9,7 +9,8 @@ Version history
 * access log: added DYNAMIC_METADATA :ref:`access log formatter <config_access_log_format>`.
 * access log: added :ref:`HeaderFilter <envoy_api_msg_config.filter.accesslog.v2.HeaderFilter>`
   to filter logs based on request headers
-* admin: added :http:get:`/config_dump` for dumping current configs
+* admin: added :http:get:`/config_dump` for dumping the current configuration and associated xDS
+  version information (if applicable).
 * admin: added :http:get:`/stats/prometheus` as an alternative endpoint for getting stats in prometheus format.
 * admin: added :ref:`/runtime_modify endpoint <operations_admin_interface_runtime_modify>` to add or change runtime values
 * admin: mutations must be sent as POSTs, rather than GETs. Mutations include:

docs/root/operations/admin.rst

@@ -115,9 +115,8 @@ modify different aspects of the server:
 .. http:get:: /config_dump
 
   Dump currently loaded configuration from various Envoy components as JSON-serialized proto
-  messages. Currently, only route configs are available but more are on the way. See
-  :api:`envoy/admin/v2/config_dump.proto` for more information. That proto is in draft state and is
-  subject to change.
+  messages. See the :ref:`response definition <envoy_api_msg_admin.v2alpha.ConfigDump>` for more
+  information.
 
 .. http:post:: /cpuprofiler
 
@@ -182,9 +181,9 @@ The fields are:
 .. http:get:: /stats
 
   Outputs all statistics on demand. This command is very useful for local debugging.
-  Histograms will output the computed quantiles i.e P0,P25,P50,P75,P90,P99,P99.9 and P100. 
-  The output for each quantile will be in the form of (interval,cumulative) where interval value 
-  represents the summary since last flush interval and cumulative value represents the 
+  Histograms will output the computed quantiles i.e P0,P25,P50,P75,P90,P99,P99.9 and P100.
+  The output for each quantile will be in the form of (interval,cumulative) where interval value
+  represents the summary since last flush interval and cumulative value represents the
   summary since the start of envoy instance.
   See :ref:`here <operations_stats>` for more information.
 

include/envoy/server/listener_manager.h

@@ -13,13 +13,34 @@
 namespace Envoy {
 namespace Server {
 
+/**
+ * Interface for an LDS API provider.
+ */
+class LdsApi {
+public:
+  virtual ~LdsApi() {}
+
+  /**
+   * @return the last received version by the xDS API for LDS.
+   */
+  virtual std::string versionInfo() const PURE;
+};
+
+typedef std::unique_ptr<LdsApi> LdsApiPtr;
+
 /**
  * Factory for creating listener components.
  */
 class ListenerComponentFactory {
 public:
   virtual ~ListenerComponentFactory() {}
 
+  /**
+   * @return an LDS API provider.
+   * @param lds_config supplies the management server configuration.
+   */
+  virtual LdsApiPtr createLdsApi(const envoy::api::v2::core::ConfigSource& lds_config) PURE;
+
   /**
    * Creates a socket.
    * @param address supplies the socket's address.
@@ -78,14 +99,23 @@ class ListenerManager {
    * will be gracefully drained once the new listener is ready to take traffic (e.g. when RDS has
    * been initialized).
    * @param config supplies the configuration proto.
+   * @param version_info supplies the xDS version of the listener.
    * @param modifiable supplies whether the added listener can be updated or removed. If the
    *        listener is not modifiable, future calls to this function or removeListener() on behalf
    *        of this listener will return false.
    * @return TRUE if a listener was added or FALSE if the listener was not updated because it is
    *         a duplicate of the existing listener. This routine will throw an EnvoyException if
    *         there is a fundamental error preventing the listener from being added or updated.
    */
-  virtual bool addOrUpdateListener(const envoy::api::v2::Listener& config, bool modifiable) PURE;
+  virtual bool addOrUpdateListener(const envoy::api::v2::Listener& config,
+                                   const std::string& version_info, bool modifiable) PURE;
+
+  /**
+   * Instruct the listener manager to create an LDS API provider. This is a separate operation
+   * during server initialization because the listener manager is created prior to several core
+   * pieces of the server existing.
+   */
+  virtual void createLdsApi(const envoy::api::v2::core::ConfigSource& lds_config) PURE;
 
   /**
    * @return std::vector<std::reference_wrapper<Network::ListenerConfig>> a list of the currently

include/envoy/upstream/BUILD

@@ -22,6 +22,7 @@ envoy_cc_library(
         "//include/envoy/http:conn_pool_interface",
         "//include/envoy/local_info:local_info_interface",
         "//include/envoy/runtime:runtime_interface",
+        "//include/envoy/server:admin_interface",
         "@envoy_api//envoy/api/v2:cds_cc",
         "@envoy_api//envoy/config/bootstrap/v2:bootstrap_cc",
     ],

include/envoy/upstream/cluster_manager.h

@@ -15,6 +15,7 @@
 #include "envoy/http/conn_pool.h"
 #include "envoy/local_info/local_info.h"
 #include "envoy/runtime/runtime.h"
+#include "envoy/server/admin.h"
 #include "envoy/upstream/load_balancer.h"
 #include "envoy/upstream/thread_local_cluster.h"
 #include "envoy/upstream/upstream.h"
@@ -70,9 +71,12 @@ class ClusterManager {
    *    Nothing is done if the hash matches the previously running configuration.
    * 2) Statically defined clusters (those present when Envoy starts) can not be updated via API.
    *
+   * @param cluster supplies the cluster configuration.
+   * @param version_info supplies the xDS version of the cluster.
    * @return true if the action results in an add/update of a cluster.
    */
-  virtual bool addOrUpdateCluster(const envoy::api::v2::Cluster& cluster) PURE;
+  virtual bool addOrUpdateCluster(const envoy::api::v2::Cluster& cluster,
+                                  const std::string& version_info) PURE;
 
   /**
    * Set a callback that will be invoked when all owned clusters have been initialized.
@@ -228,7 +232,7 @@ class ClusterManagerFactory {
   clusterManagerFromProto(const envoy::config::bootstrap::v2::Bootstrap& bootstrap,
                           Stats::Store& stats, ThreadLocal::Instance& tls, Runtime::Loader& runtime,
                           Runtime::RandomGenerator& random, const LocalInfo::LocalInfo& local_info,
-                          AccessLog::AccessLogManager& log_manager) PURE;
+                          AccessLog::AccessLogManager& log_manager, Server::Admin& admin) PURE;
 
   /**
    * Allocate an HTTP connection pool for the host. Pools are separated by 'priority',

source/common/upstream/BUILD

@@ -82,6 +82,7 @@ envoy_cc_library(
         "//source/common/protobuf:utility_lib",
         "//source/common/router:shadow_writer_lib",
         "//source/common/upstream:upstream_lib",
+        "@envoy_api//envoy/admin/v2alpha:config_dump_cc",
         "@envoy_api//envoy/api/v2/core:base_cc",
     ],
 )

source/common/upstream/cds_api_impl.cc

@@ -55,7 +55,7 @@ void CdsApiImpl::onConfigUpdate(const ResourceVector& resources, const std::stri
   for (auto& cluster : resources) {
     const std::string cluster_name = cluster.name();
     clusters_to_remove.erase(cluster_name);
-    if (cm_.addOrUpdateCluster(cluster)) {
+    if (cm_.addOrUpdateCluster(cluster, version_info)) {
       ENVOY_LOG(debug, "cds: add/update cluster '{}'", cluster_name);
     }
   }