config: example config with runtime overrides of deprecated config (e…

…nvoyproxy#9850)

Signed-off-by: Alyssa Wilk <alyssar@chromium.org>

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

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

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:
 

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 <deprecated>`.
+
+For the first 3 months following deprecation, use of deprecated fields will result in a logged
+warning and incrementing the :ref:`deprecated_feature_use <runtime_stats>` 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 <config_runtime_deprecation>` are employed to re-enable use.

docs/root/faq/overview.rst

@@ -33,6 +33,7 @@ Configuration
   configuration/zipkin_tracing
   configuration/flow_control
   configuration/timeouts
+  configuration/deprecation
 
 Load balancing
 --------------