From 621b346de9851422f92fd898ba0d9134eaff8d3a Mon Sep 17 00:00:00 2001 From: alyssawilk Date: Thu, 30 Jan 2020 14:28:16 -0500 Subject: [PATCH] config: example config with runtime overrides of deprecated config (#9850) Signed-off-by: Alyssa Wilk --- CONTRIBUTING.md | 7 +- configs/using_deprecated_config.v2.yaml | 71 +++++++++++++++++++ .../root/configuration/operations/runtime.rst | 10 +-- docs/root/faq/configuration/deprecation.rst | 15 ++++ docs/root/faq/overview.rst | 1 + 5 files changed, 97 insertions(+), 7 deletions(-) create mode 100644 configs/using_deprecated_config.v2.yaml create mode 100644 docs/root/faq/configuration/deprecation.rst diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d9cbfede864f..3c9c9e39fefb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,13 +46,14 @@ versioning guidelines: * Unless the community and Envoy maintainer team agrees on an exception, during the first release cycle after a feature has been deprecated, use of that feature will cause a logged warning, and incrementing the - [runtime](https://www.envoyproxy.io/docs/envoy/latest/configuration/runtime#config-runtime) + [runtime](https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/runtime#statistics) `runtime.deprecated_feature_use` stat. During the second release cycle, use of the deprecated configuration will cause a configuration load failure, unless the feature in question is explicitly overridden in - [runtime](https://www.envoyproxy.io/docs/envoy/latest/configuration/runtime#config-runtime) - config. Finally, following the deprecation of the API major version where the field was first + [runtime](https://www.envoyproxy.io/docs/envoy/latest/configuration/operations/runtime#using-runtime-overrides-for-deprecated-features) + config ([example](configs/using_deprecated_config.v2.yaml)). Finally, following the deprecation + of the API major version where the field was first marked deprecated, the entire implementation code will be removed from the Envoy implementation. * This policy means that organizations deploying master should have some time to get ready for breaking changes at the next major API version. This is typically a window of at least 12 months diff --git a/configs/using_deprecated_config.v2.yaml b/configs/using_deprecated_config.v2.yaml new file mode 100644 index 000000000000..fb454ad29ba9 --- /dev/null +++ b/configs/using_deprecated_config.v2.yaml @@ -0,0 +1,71 @@ +admin: + access_log_path: /tmp/admin_access.log + address: + socket_address: + protocol: TCP + address: 127.0.0.1 + port_value: 9901 +static_resources: + listeners: + - name: listener_0 + address: + socket_address: + protocol: TCP + address: 0.0.0.0 + port_value: 10000 + filter_chains: + - filters: + - name: envoy.http_connection_manager + typed_config: + "@type": type.googleapis.com/envoy.config.filter.network.http_connection_manager.v2.HttpConnectionManager + stat_prefix: ingress_http + route_config: + name: local_route + virtual_hosts: + - name: local_service + domains: ["*"] + routes: + - match: + prefix: "/" + route: + host_rewrite: www.google.com + cluster: service_google + cors: + allow_origin: + - "test-origin-1" + http_filters: + - name: envoy.router + clusters: + - name: service_google + connect_timeout: 0.25s + type: LOGICAL_DNS + # Comment out the following line to test on v6 networks + dns_lookup_family: V4_ONLY + lb_policy: ROUND_ROBIN + load_assignment: + cluster_name: service_google + endpoints: + - lb_endpoints: + - endpoint: + address: + socket_address: + address: www.google.com + port_value: 443 + transport_socket: + name: envoy.transport_sockets.tls + typed_config: + "@type": type.googleapis.com/envoy.api.v2.auth.UpstreamTlsContext + sni: www.google.com +tracing: + http: + name: envoy.zipkin + config: + collector_cluster: service_google + collector_endpoint: /api/v1/spans + collector_endpoint_version: HTTP_JSON_V1 +layered_runtime: + layers: + - name: static_layer + static_layer: + envoy.deprecated_features:envoy.config.trace.v2.ZipkinConfig.HTTP_JSON_V1: true + envoy.deprecated_features:envoy.api.v2.route.CorsPolicy.allow_origin: true diff --git a/docs/root/configuration/operations/runtime.rst b/docs/root/configuration/operations/runtime.rst index 3d405269991f..97a7e17ab1f3 100644 --- a/docs/root/configuration/operations/runtime.rst +++ b/docs/root/configuration/operations/runtime.rst @@ -246,10 +246,12 @@ This disallowed mode can be overridden in runtime configuration by setting envoy.deprecated_features:full_fieldname or envoy.deprecated_features:full_enum_value to true. For example, for a deprecated field ``Foo.Bar.Eep`` set ``envoy.deprecated_features:Foo.bar.Eep`` to -``true``. Use of this override is **strongly discouraged**. -Fatal-by-default configuration indicates that the removal of the old code paths is imminent. It is -far better for both Envoy users and for Envoy contributors if any bugs or feature gaps with the new -code paths are flushed out ahead of time, rather than after the code is removed! +``true``. There is a production example using static runtime to allow both fail-by-default fields here: +:repo:`configs/using_deprecated_config.v2.yaml` +Use of these override is **strongly discouraged** so please use with caution and switch to the new fields +as soon as possible. Fatal-by-default configuration indicates that the removal of the old code paths is +imminent. It is far better for both Envoy users and for Envoy contributors if any bugs or feature gaps +with the new code paths are flushed out ahead of time, rather than after the code is removed! .. _runtime_stats: diff --git a/docs/root/faq/configuration/deprecation.rst b/docs/root/faq/configuration/deprecation.rst new file mode 100644 index 000000000000..c71ee63645a8 --- /dev/null +++ b/docs/root/faq/configuration/deprecation.rst @@ -0,0 +1,15 @@ +.. _faq_deprecation: + +How are configuration deprecations handled? +=========================================== + +As documented in the "Breaking change policy" in :repo:`CONTRIBUTING.md`, features can be marked +as deprecated at any point as long as there is a replacement available. Each deprecation is +annotated in the API proto itself and explained in detail in the +:ref:`Envoy documentation `. + +For the first 3 months following deprecation, use of deprecated fields will result in a logged +warning and incrementing the :ref:`deprecated_feature_use ` counter. +After that point, the field will be annotated as fatal-by-default and further use of the field +will will be treated as invalid configuration unless +:ref:`runtime overrides ` are employed to re-enable use. diff --git a/docs/root/faq/overview.rst b/docs/root/faq/overview.rst index b64a6769de24..9b6b9e6dc99e 100644 --- a/docs/root/faq/overview.rst +++ b/docs/root/faq/overview.rst @@ -33,6 +33,7 @@ Configuration configuration/zipkin_tracing configuration/flow_control configuration/timeouts + configuration/deprecation Load balancing --------------