Chiebot-Mirror
/
data-plane-api
mirror of https://github.com/envoyproxy/data-plane-api.git
8
0
Fork 0
Code Issues Projects Releases Wiki Activity

docs/constraints: bootstrap.proto. (#284)

Browse Source 
Signed-off-by: Harvey Tuch <htuch@google.com>
pull/299/head^2
htuch 7 years ago committed by Matt Klein
parent 011c8f5ec0
commit 65bb3f3717
25 changed files with 299 additions and 174 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 267
      api/bootstrap.proto
  2. 10
      api/cds.proto
  3. 9
      api/eds.proto
  4. 2
      api/filter/accesslog/accesslog.proto
  5. 2
      api/filter/network/http_connection_manager.proto
  6. 2
      api/filter/network/tcp_proxy.proto
  7. 2
      api/lds.proto
  8. 2
      api/protocol.proto
  9. 2
      docs/root/api-v1/admin.rst
  10. 6
      docs/root/api-v1/api.rst
  11. 2
      docs/root/api-v1/network_filters/http_conn_man.rst
  12. 28
      docs/root/api-v1/rate_limit.rst
  13. 34
      docs/root/api-v1/runtime.rst
  14. 2
      docs/root/api-v1/tracing.rst
  15. 2
      docs/root/configuration/configuration.rst
  16. 14
      docs/root/configuration/overview/v1_overview.rst
  17. 2
      docs/root/configuration/overview/v2_overview.rst
  18. 23
      docs/root/configuration/rate_limit.rst
  19. 29
      docs/root/configuration/runtime.rst
  20. 2
      docs/root/install/ref_configs.rst
  21. 3
      docs/root/intro/arch_overview/statistics.rst
  22. 8
      docs/root/intro/arch_overview/tracing.rst
  23. 2
      docs/root/intro/version_history.rst
  24. 7
      docs/root/operations/admin.rst
  25. 11
      tools/protodoc/protodoc.py

267
api/bootstrap.proto
Unescape View File

@ -1,7 +1,7 @@
// [#protodoc-title: Bootstrap]
// This proto is expected to be provided on disk or via the command-line to
// Envoy. It provides sufficient information for Envoy to fetch the rest of
// its configuration from either disk or management server(s).
// This proto is supplied via the :option:`-c` CLI flag and acts as the root
// of the Envoy v2 configuration. See the :ref:`v2 configuration overview
// <config_overview_v2_bootstrap>` for more detail.
syntax = "proto3";
@ -17,91 +17,125 @@ import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "google/protobuf/wrappers.proto";
import "validate/validate.proto";
// Configuration for the LightStep tracer.
message LightstepConfig {
// The cluster manager cluster that hosts the LightStep collectors.
string collector_cluster = 1;
// File containing the access token to the LightStep API.
string access_token_file = 2;
string collector_cluster = 1 [(validate.rules).string.min_len = 1];
// File containing the access token to the `LightStep
// <http://lightstep.com/>`_ API.
string access_token_file = 2 [(validate.rules).string.min_len = 1];
}
message ZipkinConfig {
// The cluster manager cluster that hosts the Zipkin collectors. Note that the
// Zipkin cluster must be defined under clusters in the cluster manager
// configuration section.
string collector_cluster = 1;
// Zipkin cluster must be defined in the :ref:`Bootstrap static cluster
// resources <envoy_api_field_Bootstrap.StaticResources.clusters>`.
string collector_cluster = 1 [(validate.rules).string.min_len = 1];
// The API endpoint of the Zipkin service where the spans will be sent. When
// using a standard Zipkin installation, the API endpoint is typically
// /api/v1/spans, which is the default value.
string collector_endpoint = 2;
string collector_endpoint = 2 [(validate.rules).string.min_len = 1];
}
// The :ref:`tracing <arch_overview_tracing>` configuration specifies global
// settings for the HTTP tracer used by Envoy. The configuration is defined by
// the :ref:`Bootstrap <envoy_api_msg_Bootstrap>` :ref:`tracing
// <envoy_api_field_Bootstrap.tracing>` field. Envoy may support other tracers
// in the future, but right now the HTTP tracer is the only one supported.
message Tracing {
// Provides configuration for the HTTP tracer.
message Http {
// The name of the HTTP trace driver to instantiate. The name must match a
// supported HTTP trace driver. "envoy.lightstep" and "envoy.zipkin" are built-in
// trace drivers.
string name = 1;
// supported HTTP trace driver. *envoy.lightstep* and *envoy.zipkin* are
// built-in trace drivers.
string name = 1 [(validate.rules).string.min_len = 1];
// Trace driver specific configuration which depends on the driver being
// instantiated. See the trace drivers for further documentation.
// instantiated. See the :ref:`LightstepConfig
// <envoy_api_msg_LightstepConfig>` and :ref:`ZipkinConfig
// <envoy_api_msg_ZipkinConfig>` trace drivers for examples.
google.protobuf.Struct config = 2;
}
// Provides configuration for the HTTP tracer.
Http http = 1;
}
// Administration interface :ref:`operations documentation
// <operations_admin_interface>`.
message Admin {
// The path to write the access log for the administration server. If no
// access log is desired specify ‘/dev/null’.
string access_log_path = 1;
string access_log_path = 1 [(validate.rules).string.min_len = 1];
// The cpu profiler output path for the administration server. If no profile
// path is specified, the default is ‘/var/log/envoy/envoy.prof’.
string profile_path = 2;
// The TCP address that the administration server will listen on.
Address address = 3;
Address address = 3 [(validate.rules).message.required = true];
}
// Cluster manager :ref:`architecture overview <arch_overview_cluster_manager>`.
message ClusterManager {
// Name of the local cluster (i.e., the cluster that owns the Envoy running
// this configuration). In order to enable zone aware routing this option must
// be set. If local_cluster_name is defined then clusters must contain a
// definition of a cluster with the same name.
// this configuration). In order to enable :ref:`zone aware routing
// <arch_overview_load_balancing_zone_aware_routing>` this option must be set.
// If *local_cluster_name* is defined then :ref:`clusters
// <config_cluster_manager_clusters>` must be defined in the :ref:`Bootstrap
// static cluster resources
// <envoy_api_field_Bootstrap.StaticResources.clusters>`. This is unrelated to
// the :option:`--service-cluster` option which does not `affect zone aware
// routing <https://github.com/envoyproxy/envoy/issues/774>`_.
string local_cluster_name = 1;
// Optional global configuration for outlier detection.
message OutlierDetection {
// Specifies the path to the outlier event log.
string event_log_path = 1;
}
// Optional global configuration for outlier detection.
OutlierDetection outlier_detection = 2;
// Optional configuration used to bind newly established upstream connections.
// This may be overridden on a per-cluster basis by upstream_bind_config in the cds_config.
BindConfig upstream_bind_config = 3;
// A management server endpoint to stream load stats to, as per
// StreamLoadStats in eds.proto. This must have api_type GRPC.
// A management server endpoint to stream load stats to via
// :ref:`StreamLoadStats <envoy_api_msg_LoadStatsRequest>`. This must have
// :ref:`api_type <envoy_api_field_ApiConfigSource.api_type>` :ref:`GRPC
// <envoy_api_enum_value_ApiConfigSource.ApiType.GRPC>`.
ApiConfigSource load_stats_config = 4;
}
// Stats proto for built-in "envoy.statsd" sink.
// Stats configuration proto schema for built-in *envoy.statsd* sink.
message StatsdSink {
oneof statsd_specifier {
// The UDP address of a running statsd compliant listener. If specified,
// statistics will be flushed to this address.
option (validate.required) = true;
// The UDP address of a running `statsd <https://github.com/etsy/statsd>`_
// compliant listener. If specified, statistics will be flushed to this
// address.
Address address = 1;
// The name of a cluster manager cluster that is running a TCP statsd
// compliant listener. If specified, Envoy will connect to this cluster to
// flush statistics.
// The name of a cluster that is running a TCP `statsd
// <https://github.com/etsy/statsd>`_ compliant listener. If specified,
// Envoy will connect to this cluster to flush statistics.
string tcp_cluster_name = 2;
}
}
// Configuration for pluggable stats sinks.
message StatsSink {
// The name of the stats sink to instantiate. The name must match a supported
// stats sink. "envoy.statsd" is a built-in sink suitable for emitting to
// statsd.
// stats sink. *envoy.statsd* is a built-in sink suitable for emitting to
// `statsd <https://github.com/etsy/statsd>`_.
string name = 1;
// Stats sink specific configuration which depends on the sink being
// instantiated. See the supported sinks for further documentation.
// instantiated. See :ref:`StatsdSink <envoy_api_msg_StatsdSink>` for an
// example.
google.protobuf.Struct config = 2;
}
@ -111,98 +145,133 @@ message StatsSink {
message TagSpecifier {
// Attaches an identifier to the tag values to identify the tag being in the
// sink. Envoy has a set of default names and regexes to extract dynamic
// portions of existing stats, which can be found in
// source/common/config/well_known_names.h in the Envoy repository. If a
// tag_name is provided in the config with an empty regex, Envoy will attempt
// to find that name in its set of defaults and use the accompanying regex.
// Note: if any default tags are specified twice, the config will be
// considered invalid.
// portions of existing stats, which can be found in `well_known_names.h
// <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
// in the Envoy repository. If a :ref:`tag_name
// <envoy_api_field_TagSpecifier.tag_name>` is provided in the config with an
// empty regex, Envoy will attempt to find that name in its set of defaults
// and use the accompanying regex.
//
// .. note::
//
// If any default tags are specified twice, the config will be considered
// invalid.
string tag_name = 1;
// The first capture group identifies the portion of the name to remove. The
// second capture group (which will normally be nested inside the first)
// will designate the value of the tag for the statistic. If no second
// capture group is provided, the first will also be used to set the value of
// the tag. All other capture groups will be ignored.
// second capture group (which will normally be nested inside the first) will
// designate the value of the tag for the statistic. If no second capture
// group is provided, the first will also be used to set the value of the tag.
// All other capture groups will be ignored.
//
// For example:
// Take for example, with a stat name ``cluster.foo_cluster.upstream_rq_timeout``
// and
//
// stat name: "cluster.foo_cluster.upstream_rq_timeout"
// .. code-block:: json
//
// tag name: "envoy.cluster_name" (one of many default stat regexes provided
// in Envoy)
// {
// "tag_name": "envoy.cluster_name",
// "regex": "^cluster\.((.+?)\.)"
// }
//
// regex: "^cluster\.((.+?)\.)"
// Note that the regex will remove ``foo_cluster.`` making the tag extracted
// name ``cluster.upstream_rq_timeout`` and the tag value for
// ``envoy.cluster_name`` will be ``foo_cluster`` (note: there will be no
// ``.`` character because of the second capture group).
//
// Notice the regex will remove "foo_cluster." making the tag extracted name
// "cluster.upstream_rq_timeout" and the tag value for "envoy.cluster_name"
// "foo_cluster" (note: no '.' character because of the second capture group).
// An example with two regexes and stat name
// ``http.connection_manager_1.user_agent.ios.downstream_cx_total``:
//
// An example with two regexes:
// .. code-block:: json
//
// First tag name: "envoy.http_user_agent"
// First regex: "^http(?=\.).*?\.user_agent\.((.+?)\.)\w+?$"
// Second tag name: "envoy.http_conn_manager_prefix"
// Second regex: "^http\.((.*?)\.)"
// Stat name: "http.connection_manager_1.user_agent.ios.downstream_cx_total"
// [
// {
// "tag_name": "envoy.http_user_agent",
// "regex": "^http(?=\.).*?\.user_agent\.((.+?)\.)\w+?$"
// },
// {
// "tag_name": "envoy.http_conn_manager_prefix",
// "regex": "^http\.((.*?)\.)"
// }
// ]
//
// The first regex will remove "ios." leaving the tag extracted name:
// "http.connection_manager_1.user_agent.downstream_cx_total".
// The tag "envoy.http_user_agent" will be added with tag value "ios".
// The first regex will remove ``ios.``, leaving the tag extracted name
// ``http.connection_manager_1.user_agent.downstream_cx_total``. The tag
// ``envoy.http_user_agent`` will be added with tag value ``ios``.
//
// The second regex will remove "connection_manager_1." from the tag extracted
// name produced by the first regex
// ("http.connection_manager_1.user_agent.downstream_cx_total"), leaving
// "http.user_agent.downstream_cx_total" as the tag extracted name. The tag
// "envoy.http_conn_manager_prefix" will be added with the tag value
// "connection_manager_1".
// The second regex will remove ``connection_manager_1.`` from the tag
// extracted name produced by the first regex
// ``http.connection_manager_1.user_agent.downstream_cx_total``, leaving
// ``http.user_agent.downstream_cx_total`` as the tag extracted name. The tag
// ``envoy.http_conn_manager_prefix`` will be added with the tag value
// ``connection_manager_1``.
string regex = 2;
}
// Statistics :ref:`architecture overview <arch_overview_statistics>`.
message StatsConfig {
// Each stat name is iteratively processed through these tag specifiers.
// When a tag is matched, the first capture group is removed from the name so
// later TagSpecifiers cannot match that same portion of the match.
// later :ref:`TagSpecifiers <envoy_api_msg_TagSpecifier>` cannot match that
// same portion of the match.
repeated TagSpecifier stats_tags = 1;
// Use all default tag regexes specified in Envoy. These can be combined with
// custom tags specified in stats_tags. They will be processed before the
// custom tags. Note: if any default tags are specified twice, the config will
// be considered invalid. See source/common/config/well_known_names.h for a
// a list of the default tags in Envoy. If not provided, the value is assumed
// to be true.
// custom tags specified in :ref:`stats_tags
// <envoy_api_field_StatsConfig.stats_tags>`. They will be processed before
// the custom tags.
//
// .. note::
//
// If any default tags are specified twice, the config will be considered
// invalid.
//
// See `well_known_names.h
// <https://github.com/envoyproxy/envoy/blob/master/source/common/config/well_known_names.h>`_
// for a list of the default tags in Envoy.
//
// If not provided, the value is assumed to be true.
google.protobuf.BoolValue use_all_default_tags = 2;
}
// Envoy process watchdog configuration. When configured, this monitors for
// nonresponsive threads and kills the process after the configured thresholds.
message Watchdog {
// The duration after which Envoy counts a nonresponsive thread in the
// “server.watchdog_miss” statistic. If not specified the default is 200ms.
// *server.watchdog_miss* statistic. If not specified the default is 200ms.
google.protobuf.Duration miss_timeout = 1;
// The duration after which Envoy counts a nonresponsive thread in the
// “server.watchdog_mega_miss” statistic. If not specified the default is
// *server.watchdog_mega_miss* statistic. If not specified the default is
// 1000ms.
google.protobuf.Duration megamiss_timeout = 2;
// If a watched thread has been nonresponsive for this duration, assume a
// programming error and kill the entire Envoy process. Set to 0 to disable
// kill behavior. If not specified the default is 0 (disabled).
google.protobuf.Duration kill_timeout = 3;
// If at least two watched threads have been nonresponsive for at least this
// duration assume a true deadlock and kill the entire Envoy process. Set to 0
// to disable this behavior. If not specified the default is 0 (disabled).
google.protobuf.Duration multikill_timeout = 4;
}
// Runtime :ref:`configuration overview <config_runtime>`.
message Runtime {
// The implementation assumes that the file system tree is accessed via a
// symbolic link. An atomic link swap is used when a new tree should be
// switched to. This parameter specifies the path to the symbolic link. Envoy
// will watch the location for changes and reload the file system tree when
// they happen.
string symlink_root = 1;
string symlink_root = 1 [(validate.rules).string.min_len = 1];
// Specifies the subdirectory to load within the root directory. This is
// useful if multiple systems share the same delivery mechanism. Envoy
// configuration elements can be contained in a dedicated subdirectory.
string subdirectory = 2;
string subdirectory = 2 [(validate.rules).string.min_len = 1];
// Specifies an optional subdirectory to load within the root directory. If
// specified and the directory exists, configuration values within this
// directory will override those found in the primary subdirectory. This is
@ -212,53 +281,73 @@ message Runtime {
string override_subdirectory = 3;
}
// Rate limit :ref:`configuration overview <config_rate_limit_service>`.
message RateLimitServiceConfig {
// Specifies the cluster manager cluster name that hosts the rate limit
// service. The client will connect to this cluster when it needs to make rate
// limit service requests.
string cluster_name = 1;
string cluster_name = 1 [(validate.rules).string.min_len = 1];
}
// Bootstrap :ref:`configuration overview <config_overview_v2_bootstrap>`.
message Bootstrap {
// Node identity to present to the management server and for instance
// identification purposes (e.g. in generated headers).
Node node = 1;
Node node = 1 [(validate.rules).message.required = true];
// Statically specified resources.
message StaticResources {
// Static :ref:`Listeners <envoy_api_msg_Listener>`. These listeners are
// available regardless of LDS configuration.
repeated Listener listeners = 1;
// If a network based configuration source is specified for cds_config, it's
// necessary to have some initial cluster definitions available to allow Envoy
// to know how to speak to the management server. These cluster definitions
// may not use EDS (i.e. they should be static IP or DNS-based).
// If a network based configuration source is specified for :ref:`cds_config
// <envoy_api_field_Bootstrap.DynamicResources.cds_config>`, it's necessary
// to have some initial cluster definitions available to allow Envoy to know
// how to speak to the management server. These cluster definitions may not
// use :ref:`EDS <arch_overview_dynamic_config_sds>` (i.e. they should be static
// IP or DNS-based).
repeated Cluster clusters = 2;
// [#not-implemented-hide:]
repeated Secret secrets = 3;
}
// Statically specified resources.
StaticResources static_resources = 2;
// xDS configuration sources.
message DynamicResources {
// All Listeners are provided by a single LDS configuration source.
// All :ref:`Listeners <envoy_api_msg_Listener>` are provided by a single
// :ref:`LDS <arch_overview_dynamic_config_lds>` configuration source.
ConfigSource lds_config = 1;
// All post-bootstrap Cluster definitions are provided by a single CDS
// All post-bootstrap :ref:`Cluster <envoy_api_msg_Cluster>` definitions are
// provided by a single :ref:`CDS <arch_overview_dynamic_config_cds>`
// configuration source.
ConfigSource cds_config = 2;
// A single ADS source may be optionally specified. This must have api_type GRPC.
// A single :ref:`ADS <config_overview_v2_ads>` source may be optionally
// specified. This must have :ref:`api_type
// <envoy_api_field_ApiConfigSource.api_type>` :ref:`GRPC
// <envoy_api_enum_value_ApiConfigSource.ApiType.GRPC>`. Only
// :ref:`ConfigSources <envoy_api_msg_ConfigSource>` that have
// the :ref:`ads <envoy_api_field_ConfigSource.ads>` field set will be
// streamed on the ADS channel.
ApiConfigSource ads_config = 3;
message DeprecatedV1 {
// This is the global SDS config when using v1 REST for CDS/EDS.
// This is the global :ref:`SDS <arch_overview_dynamic_config_sds>` config
// when using v1 REST for :ref:`CDS
// <arch_overview_dynamic_config_cds>`/:ref:`EDS
// <arch_overview_dynamic_config_sds>`.
ConfigSource sds_config = 1;
}
DeprecatedV1 deprecated_v1 = 4;
}
// xDS configuration sources.
DynamicResources dynamic_resources = 3;
// Configuration for the cluster manager which owns all upstream clusters
// within the server.
ClusterManager cluster_manager = 4;
ClusterManager cluster_manager = 4 [(validate.rules).message.required = true];
// Optional file system path to search for startup flag files.
string flags_path = 5;
@ -292,5 +381,5 @@ message Bootstrap {
Runtime runtime = 11;
// Configuration for the local administration HTTP server.
Admin admin = 12;
Admin admin = 12 [(validate.rules).message.required = true];
}

10
api/cds.proto
Unescape View File

@ -122,9 +122,9 @@ message Cluster {
ConfigSource eds_config = 1;
// Optional alternative to cluster name to present to EDS. This does not
// have the same restrictions as cluster name, i.e. it may be arbritary
// have the same restrictions as cluster name, i.e. it may be arbitrary
// length.
string service_name = 2 [(validate.rules).string.min_len = 1];
string service_name = 2;
}
// Configuration to use for EDS updates for the Cluster.
EdsClusterConfig eds_cluster_config = 3;
@ -330,13 +330,13 @@ message Cluster {
// The interval for removing stale hosts from a cluster type
// :ref:`ORIGINAL_DST<envoy_api_enum_value_Cluster.DiscoveryType.ORIGINAL_DST>`.
// Hosts are considered stale if they have not been used
// as upstream destinations during this interval. New hosts are added
// as upstream destinations during this interval. New hosts are added
// to original destination clusters on demand as new connections are
// redirected to Envoy, causing the number of hosts in the cluster to
// grow over time. Hosts that are not stale (they are actively used as
// grow over time. Hosts that are not stale (they are actively used as
// destinations) are kept in the cluster, which allows connections to
// them remain open, saving the latency that would otherwise be spent
// on opening new connections. If this setting is not specified, the
// on opening new connections. If this setting is not specified, the
// value defaults to 5000ms. For cluster types other than
// :ref:`ORIGINAL_DST<envoy_api_enum_value_Cluster.DiscoveryType.ORIGINAL_DST>`
// this setting is ignored.

9
api/eds.proto
Unescape View File

@ -125,11 +125,11 @@ message LocalityLbEndpoints {
// `this issue <https://github.com/envoyproxy/envoy/issues/1285>`_ is fixed.
google.protobuf.UInt32Value load_balancing_weight = 3 [(validate.rules).uint32 = {gte:1, lte:128}];
// Optional: the priority for this LocalityLbEndpoints. If unspecified this will
// Optional: the priority for this LocalityLbEndpoints. If unspecified this will
// default to the highest priority (0).
//
// Under usual circumstances, Envoy will only select endpoints for the highest
// priority (0). In the event all endpoints for a particular priority are
// priority (0). In the event all endpoints for a particular priority are
// unavailable/unhealthy, Envoy will fail over to selecting endpoints for the
// next highest priority group.
//
@ -239,7 +239,10 @@ message LoadStatsRequest {
// effective weight of a host is its load_balancing_weight multiplied by the
// load_balancing_weight of its Locality.
message ClusterLoadAssignment {
// Name of the cluster.
// Name of the cluster. This will be the :ref:`service_name
// <envoy_api_field_Cluster.EdsClusterConfig.service_name>` value if specified
// in the cluster :ref:`EdsClusterConfig
// <envoy_api_msg_Cluster.EdsClusterConfig>`.
string cluster_name = 1 [(validate.rules).string.min_len = 1];
// List of endpoints to load balance to.

2
api/filter/accesslog/accesslog.proto
Unescape View File

@ -65,7 +65,7 @@ message AccessLogCommon {
// selection.
//
// This can be used to associate IDs attached to the various configurations
// used to process this request with the access log entry. For example, a
// used to process this request with the access log entry. For example, a
// route created from a higher level forwarding rule with some ID can place
// that ID in this field and cross reference later. It can also be used to
// determine if a canary endpoint was used or not.

2
api/filter/network/http_connection_manager.proto
Unescape View File

@ -127,7 +127,7 @@ message HttpConnectionManager {
// Presence of the object defines whether the connection manager
// emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
// <config_tracing>`.
// <envoy_api_msg_Tracing>`.
Tracing tracing = 7;
// Additional HTTP/1 settings that are passed to the HTTP/1 codec.

2
api/filter/network/tcp_proxy.proto
Unescape View File

@ -98,6 +98,6 @@ message TcpProxy {
DeprecatedV1 deprecated_v1 = 6;
// The maximum number of unsuccessful connection attempts that will be made before
// giving up. If the parameter is not specified, 1 connection attempt will be made.
// giving up. If the parameter is not specified, 1 connection attempt will be made.
google.protobuf.UInt32Value max_connect_attempts = 7 [(validate.rules).uint32.gte = 1];
}

2
api/lds.proto
Unescape View File

@ -114,7 +114,7 @@ message FilterChain {
// A list of individual network filters that make up the filter chain for
// connections established with the listener. Order matters as the filters are
// processed sequentially as connection events happen. Note: If the filter
// processed sequentially as connection events happen. Note: If the filter
// list is empty, the connection will close by default.
repeated Filter filters = 3;

2
api/protocol.proto
Unescape View File

@ -41,7 +41,7 @@ message Http2ProtocolOptions {
// window size now, so it's also the minimum.
// This field also acts as a soft limit on the number of bytes Envoy will buffer per-stream in the
// HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to
// HTTP/2 codec buffers. Once the buffer reaches this pointer, watermark callbacks will fire to
// stop the flow of data to the codec buffers.
google.protobuf.UInt32Value initial_stream_window_size = 3;

2
docs/root/configuration/overview/admin.rst → docs/root/api-v1/admin.rst
Unescape View File

@ -1,4 +1,4 @@
.. _config_admin:
.. _config_admin_v1:
Administration interface
========================

6
docs/root/api-v1/api.rst
Unescape View File

@ -9,4 +9,8 @@ v1 API reference
network_filters/network_filters
route_config/route_config
http_filters/http_filters
cluster_manager/cluster_manager
cluster_manager/cluster_manager
admin
rate_limit
runtime
tracing

2
docs/root/api-v1/network_filters/http_conn_man.rst
Unescape View File

@ -88,7 +88,7 @@ add_user_agent
:ref:`tracing <config_http_conn_man_tracing>`
*(optional, object)* Presence of the object defines whether the connection manager
emits :ref:`tracing <arch_overview_tracing>` data to the :ref:`configured tracing provider
<config_tracing>`.
<config_tracing_v1>`.
.. _config_http_conn_man_http1_settings:

28
docs/root/api-v1/rate_limit.rst
Unescape View File

@ -0,0 +1,28 @@
.. _config_rate_limit_service_v1:
Rate limit service
==================
Rate limit :ref:`configuration overview <config_rate_limit_service>`.
.. code-block:: json
{
"type": "grpc_service",
"config": {
"cluster_name": "..."
}
}
type
*(required, string)* Specifies the type of rate limit service to call. Currently the only
supported option is *grpc_service* which specifies Lyft's global rate limit service and
associated IDL.
config
*(required, object)* Specifies type specific configuration for the rate limit service.
cluster_name
*(required, string)* Specifies the cluster manager cluster name that hosts the rate limit
service. The client will connect to this cluster when it needs to make rate limit service
requests.

34
docs/root/api-v1/runtime.rst
Unescape View File

@ -0,0 +1,34 @@
.. _config_runtime_v1:
Runtime
=======
Runtime :ref:`configuration overview <config_runtime>`.
.. code-block:: json
{
"symlink_root": "...",
"subdirectory": "...",
"override_subdirectory": "..."
}
symlink_root
*(required, string)* The implementation assumes that the file system tree is accessed via a
symbolic link. An atomic link swap is used when a new tree should be switched to. This
parameter specifies the path to the symbolic link. Envoy will watch the location for changes
and reload the file system tree when they happen.
subdirectory
*(required, string)* Specifies the subdirectory to load within the root directory. This is useful
if multiple systems share the same delivery mechanism. Envoy configuration elements can be
contained in a dedicated subdirectory.
.. _config_runtime_override_subdirectory:
override_subdirectory
*(optional, string)* Specifies an optional subdirectory to load within the root directory. If
specified and the directory exists, configuration values within this directory will override those
found in the primary subdirectory. This is useful when Envoy is deployed across many different
types of servers. Sometimes it is useful to have a per service cluster directory for runtime
configuration. See below for exactly how the override directory is used.

2
docs/root/configuration/overview/tracing.rst → docs/root/api-v1/tracing.rst
Unescape View File

@ -1,4 +1,4 @@
.. _config_tracing:
.. _config_tracing_v1:
Tracing
=======

2
docs/root/configuration/configuration.rst
Unescape View File

@ -15,4 +15,6 @@ Configuration reference
http_filters/http_filters
cluster_manager/cluster_manager
access_log
rate_limit
runtime
tools/router_check

14
docs/root/configuration/overview/v1_overview.rst
Unescape View File

@ -45,7 +45,7 @@ name (which should be a string) is called *true*, it should be written in the co
*(optional, object)* Configuration for the Listener Discovery Service (LDS). If not specified
only static listeners are loaded.
:ref:`admin <config_admin>`
:ref:`admin <config_admin_v1>`
*(required, object)* Configuration for the :ref:`local administration HTTP server
<operations_admin_interface>`.
@ -97,7 +97,7 @@ watchdog_multikill_timeout_ms
milliseconds assume a true deadlock and kill the entire Envoy process. Set to 0 to disable this
behavior. If not specified the default is 0 (disabled).
:ref:`tracing <config_tracing>`
:ref:`tracing <config_tracing_v1>`
*(optional, object)* Configuration for an external :ref:`tracing <arch_overview_tracing>`
provider. If not specified, no tracing will be performed.
@ -106,15 +106,7 @@ watchdog_multikill_timeout_ms
<arch_overview_rate_limit>` provider. If not specified, any calls to the rate limit service will
immediately return success.
:ref:`runtime <config_runtime>`
:ref:`runtime <config_runtime_v1>`
*(optional, object)* Configuration for the :ref:`runtime configuration <arch_overview_runtime>`
provider. If not specified, a "null" provider will be used which will result in all defaults being
used.
.. toctree::
:hidden:
admin
tracing
rate_limit
runtime

2
docs/root/configuration/overview/v2_overview.rst
Unescape View File

@ -443,6 +443,8 @@ is set in the :ref:`rds
<envoy_api_field_filter.network.HttpConnectionManager.rds>` field of the :ref:`HttpConnectionManager
<envoy_api_msg_filter.network.HttpConnectionManager>` config.
.. _config_overview_v2_ads:
Aggregated Discovery Service
----------------------------

23
docs/root/configuration/overview/rate_limit.rst → docs/root/configuration/rate_limit.rst
Unescape View File

@ -7,27 +7,8 @@ The :ref:`rate limit service <arch_overview_rate_limit>` configuration specifies
limit service Envoy should talk to when it needs to make global rate limit decisions. If no rate
limit service is configured, a "null" service will be used which will always return OK if called.
.. code-block:: json
{
"type": "grpc_service",
"config": {
"cluster_name": "..."
}
}
type
*(required, string)* Specifies the type of rate limit service to call. Currently the only
supported option is *grpc_service* which specifies Lyft's global rate limit service and
associated IDL.
config
*(required, object)* Specifies type specific configuration for the rate limit service.
cluster_name
*(required, string)* Specifies the cluster manager cluster name that hosts the rate limit
service. The client will connect to this cluster when it needs to make rate limit service
requests.
* :ref:`v1 API reference <config_rate_limit_service_v1>`
* :ref:`v2 API reference <envoy_api_msg_RateLimitServiceConfig>`
gRPC service IDL
----------------

29
docs/root/configuration/overview/runtime.rst → docs/root/configuration/runtime.rst
Unescape View File

@ -7,33 +7,8 @@ The :ref:`runtime configuration <arch_overview_runtime>` specifies the location
system tree that contains re-loadable configuration elements. If runtime is not configured, a "null"
provider is used which has the effect of using all defaults built into the code.
.. code-block:: json
{
"symlink_root": "...",
"subdirectory": "...",
"override_subdirectory": "..."
}
symlink_root
*(required, string)* The implementation assumes that the file system tree is accessed via a
symbolic link. An atomic link swap is used when a new tree should be switched to. This
parameter specifies the path to the symbolic link. Envoy will watch the location for changes
and reload the file system tree when they happen.
subdirectory
*(required, string)* Specifies the subdirectory to load within the root directory. This is useful
if multiple systems share the same delivery mechanism. Envoy configuration elements can be
contained in a dedicated subdirectory.
.. _config_runtime_override_subdirectory:
override_subdirectory
*(optional, string)* Specifies an optional subdirectory to load within the root directory. If
specified and the directory exists, configuration values within this directory will override those
found in the primary subdirectory. This is useful when Envoy is deployed across many different
types of servers. Sometimes it is useful to have a per service cluster directory for runtime
configuration. See below for exactly how the override directory is used.
* :ref:`v1 API reference <config_runtime_v1>`
* :ref:`v2 API reference <envoy_api_msg_Runtime>`
File system layout
------------------

2
docs/root/install/ref_configs.rst
Unescape View File

@ -48,7 +48,7 @@ A few notes about the example configurations:
templates for different instances of this.
* Tracing is configured for `LightStep <http://lightstep.com/>`_. To
disable this or enable `Zipkin <http://zipkin.io>` tracing, delete or
change the :ref:`tracing configuration <config_tracing>` accordingly.
change the :ref:`tracing configuration <config_tracing_v1>` accordingly.
* The configuration demonstrates the use of a :ref:`global rate limiting service
<arch_overview_rate_limit>`. To disable this delete the :ref:`rate limit configuration
<config_rate_limit_service>`.

3
docs/root/intro/arch_overview/statistics.rst
Unescape View File

@ -22,4 +22,5 @@ batched and periodically flushed to improve performance. Histograms are written
received. Note: what were previously referred to as timers have become histograms as the only
difference between the two representations was the units.
Statistics :ref:`configuration <config_overview_v1>`.
* :ref:`v1 API reference <config_overview_v1>`.
* :ref:`v2 API reference <envoy_api_field_Bootstrap.stats_sinks>`.

8
docs/root/intro/arch_overview/tracing.rst
Unescape View File

@ -99,7 +99,9 @@ the route. The name can also be overridden using the
Envoy automatically sends spans to tracing collectors. Depending on the tracing collector,
multiple spans are stitched together using common information such as the globally unique
request ID :ref:`config_http_conn_man_headers_x-request-id` (LightStep) or
the trace ID :ref:`configuration <config_tracing>` (Zipkin).
the trace ID configuration (Zipkin). See
See tracing :ref:`configuration <config_tracing>` for more information on how to setup tracing in
Envoy.
* :ref:`v1 API reference <config_tracing_v1>`
* :ref:`v2 API reference <envoy_api_msg_Tracing>`
for more information on how to setup tracing in Envoy.

2
docs/root/intro/version_history.rst
Unescape View File

@ -102,7 +102,7 @@ Version history
do not have `$maxTimeMS` set.
* The :ref:`MongoDB filter <config_network_filters_mongo_proxy>` now emits logs that are fully valid
JSON.
* The CPU profiler output path is now :ref:`configurable <config_admin>`.
* The CPU profiler output path is now :ref:`configurable <config_admin_v1>`.
* A :ref:`watchdog system <config_overview_v1>` has been added that can kill the server if a deadlock
is detected.
* A :ref:`route table checking tool <install_tools_route_table_check_tool>` has been added that can

7
docs/root/operations/admin.rst
Unescape View File

@ -3,8 +3,11 @@
Administration interface
========================
Envoy exposes a :ref:`local administration interface <config_admin>` that can be used to query and
modify different aspects of the server.
Envoy exposes a local administration interface that can be used to query and
modify different aspects of the server:
* :ref:`v1 API reference <config_admin_v1>`
* :ref:`v2 API reference <envoy_api_msg_Admin>`
.. http:get:: /

11
tools/protodoc/protodoc.py
Unescape View File

@ -53,6 +53,11 @@ VALID_ANNOTATIONS = set([
PROTO_STATUS_ANNOTATION,
])
# These can propagate from file scope to message/enum scope (and be overriden).
INHERITED_ANNOTATIONS = set([
PROTO_STATUS_ANNOTATION,
])
# Template for data-plane-api URLs.
# TODO(htuch): Add the ability to build a permalink by feeding a hash
# to the tool or inferring from local tree (only really make sense in CI).
@ -89,7 +94,11 @@ def ExtractAnnotations(s, inherited_annotations=None, type_name='file'):
Returns:
Pair of string with with annotations stripped and annotation map.
"""
annotations = inherited_annotations or {}
annotations = {
k: v
for k, v in (inherited_annotations or {}).items()
if k in INHERITED_ANNOTATIONS
}
stripped_lines = []
for line in s.split('\n'):
groups = re.findall(ANNOTATION_REGEX, line)

Write Preview
Loading…
Cancel
Save