releaseNotes.yml

# -*- fill-column: 100 -*-

# This file should be placed in the folder for the version of the
# product that's meant to be documented. A `/release-notes` page will
# be automatically generated and populated at build time.
#
# Note that an entry needs to be added to the `doc-links.yml` file in
# order to surface the release notes in the table of contents.
#
# The YAML in this file should contain:
#
# changelog: An (optional) URL to the CHANGELOG for the product.
# items: An array of releases with the following attributes:
#     - version: The (optional) version number of the release, if applicable.
#     - date: The date of the release in the format YYYY-MM-DD.
#     - notes: An array of noteworthy changes included in the release, each having the following attributes:
#         - type: The type of change, one of `bugfix`, `feature`, `security` or `change`.
#         - title: A short title of the noteworthy change.
#         - body: >-
#             Two or three sentences describing the change and why it
#             is noteworthy.  This is HTML, not plain text or
#             markdown.  It is handy to use YAML's ">-" feature to
#             allow line-wrapping.
#         - image: >-
#             The URL of an image that visually represents the
#             noteworthy change.  This path is relative to the
#             `release-notes` directory; if this file is
#             `FOO/releaseNotes.yml`, then the image paths are
#             relative to `FOO/release-notes/`.
#         - docs: The path to the documentation page where additional information can be found.
#         - href: A path from the root to a resource on the getambassador website, takes precedence over a docs link.

changelog: https://github.com/datawire/edge-stack/blob/$branch$/CHANGELOG.md
items:
  - version: 3.8.2
    date: '2023-10-11'
    notes:
      - title: Upgrade Envoy
        type: security
        body: >-
          This release includes security patches to the current Envoy proxy version to address CVE 2023-44487 and includes a fix to determine if a client is making too many requests with premature resets. The connection is disconnected if more than 50 percent of resets are considered premature. Another fix is also included which exposes a runtime setting to control the limit on the number of HTTP requests processed from a single connection in a single I/O cycle to mitigate CPU starvation.
        docs: topics/running/running/

      - title: Upgrade Golang to 1.20.10
        type: security
        body: >-
          Upgrading to the latest release of Golang as part of our general dependency upgrade process. This update resolves CVE-2023-39323 and CVE-2023-39325.
        docs: https://go.dev/doc/devel/release#go1.20.minor

  - version: 3.8.1
    date: '2023-09-18'
    notes:
      - title: Upgrade Golang to 1.20.8
        type: security
        body: >-
          Upgrading to the latest release of Golang as part of our general dependency upgrade process. This includes security fixes for CVE-2023-39318, CVE-2023-39319.
        docs: https://go.dev/doc/devel/release#go1.20.minor

  - version: 3.8.0
    date: '2023-08-29'
    notes:
      - title: Ambassador Edge Stack will fail to run if a valid license is not present
        type: change
        body: >-
          $productName$ will now require a valid non-expired license to run the product. If a valid license is not present or your clusters are not connected to and showing licensed in Ambassador Cloud, then $productName$ will refuse to startup. If you already have an enterprise license then you do not need to do anything so long as it is properly applied and not expired. Please view the <a href="/docs/edge-stack/latest/topics/using/licenses">license documentation</a> page for more information on your license.
          If you do not have an enterprise license for $productName$ then you can visit <a href="https://www.getambassador.io/docs/edge-stack/latest/tutorials/getting-started">the quickstart guide</a> to get setup with a free community license by signing into Ambassador Cloud and connecting your installation.
        docs: tutorials/getting-started/
      - title: Account for matchLabels when associating mappings with the same prefix to different Hosts
        type: bugfix
        body: >-
          As of v2.2.2, if two mappings were associated with different Hosts through host
          <code>mappingSelector</code> labels but share the same prefix, the labels were not taken into
          account which would cause one Mapping to be correctly routed but the other not.

          This change fixes this issue so that Mappings sharing the same prefix but associated
          with different Hosts will be correctly routed.
        docs: https://github.com/emissary-ingress/emissary/issues/4170
      - title: Duplication of values when using multiple Headers/QueryParameters in Mappings
        type: bugfix
        body: >-
          In previous versions, if multiple Headers/QueryParameters were used in a <code>v3alpha1</code> mapping,
          these values would duplicate and cause all the Headers/QueryParameters to have the same value.
          This is no longer the case and the expected values for unique Headers/QueryParameters will apply.

          This issue was only present in <code>v3alpha1</code> Mappings. For users who may have this issue, please
          be sure to re-apply any <code>v3alpha1</code> Mappings in order to update the stored <code>v2</code> Mapping and resolve the
          issue.
        docs: topics/using/headers/headers
      - title: Ambassador Agent no longer collects Envoy metrics
        type: change
        body: >-
          When the Ambassador agent is being used, it will no longer attempt to collect and report Envoy metrics.
          In previous versions, $productName$ would always create an Envoy stats sink for the agent as long as the AMBASSADOR_GRPC_METRICS_SINK
          environment variable was provided. This environment variable was hardcoded on the release manifests and has now been removed
          and an Envoy stats sink for the agent is no longer created.
        docs: topics/running/environment#ambassador_grpc_metrics_sink
  - version: 3.7.2
    date: '2023-07-25'
    notes:
      - title: Upgrade to Envoy 1.26.4
        type: security
        body: >-
          This upgrades $productName$ to be built on Envoy v1.26.4 which includes a fixes for CVE-2023-35942, CVE-2023-35943, CVE-2023-35944.
        docs: https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26

      - title: Shipped Helm chart v8.7.2
        type: change
        body: >-
          - Update default image to $productName$ v3.7.2. <br/>
        docs: https://github.com/datawire/edge-stack/blob/rel/v3.7.2/charts/edge-stack/CHANGELOG.md

  - version: 3.7.1
    date: '2023-07-13'
    notes:
      - title: Upgrade to Envoy 1.26.3
        type: security
        body: >-
          This upgrades $productName$ to be built on Envoy v1.26.3 which includes a fix for <a href="https://github.com/envoyproxy/envoy/security/advisories/GHSA-jfxv-29pc-x22r">CVE-2023-35945</a>.
        docs: https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26

  - version: 3.7.0
    date: '2023-06-20'
    notes:
      - title: Configurable Web Application Firewalls
        type: feature
        body: >-
          $productName$ now provides configurable Web Application Firewalls (WAFs) that can be used to add additional security to your services by blocking dangerous requests. They can be configured globally or route by route. We have also published a ready to use set of rules to get you started and protected against the OWASP Top 10
          vulnerabilities and adheres to PCI 6.6 requirements.
          The published rule set will be updated and maintained regularly.
        docs: howtos/web-application-firewalls/

      - title: Upgrade to Envoy 1.26.1
        type: feature
        body: >-
          This upgrades $productName$ to be built on Envoy v1.26.1 which provides security, performance and feature enhancements. You can read more about them here: <a href="https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26">Envoy Proxy 1.26.1 Release Notes</a>
        docs: https://www.envoyproxy.io/docs/envoy/v1.26.1/version_history/v1.26/v1.26

      - title: ExternalFilter - Add support for configuring TLS Settings
        type: feature
        body: >-
          The <code>ExternalFilter</code> now supports configuring a CA certificate and/or client certificate via the new <code>tlsConfig</code> attribute. This allows $productName$ to communicate with the configured AuthService using custom TLS certificates signed by a different CA. It also allows the ExternalFilter to originate mTLS and have $productName$ present mTLS client certificates to the AuthService. Custom TLS certificates are provided as Kubernetes Secrets.
        docs: topics/using/filters/external/#configuring-tls-settings

  - version: 3.6.0
    date: '2023-04-17'
    notes:
      - title: Deprecation of insteadOfRedirect.filters argument in FilterPolicy
        type: change
        body: >-
          The <code> insteadOfRedirect.filters </code> field within the OAuth2 path-specific arguments has been deprecated and it will be fully removed in a future version of $productName$. Similiar behavior can
          be accomplished using <code>onDeny=continue</code> and chaining a
          fallback Filter to run.
        docs: topics/using/filters/oauth2#oauth2-path-specific-arguments

      - title: Upgrade to Envoy 1.25.4
        type: feature
        body: >-
          This upgrades $productName$ to be built on Envoy v1.25.4 which provides security, performance and feature enhancements. You can read more about them here: <a href="https://www.envoyproxy.io/docs/envoy/v1.25.4/version_history/v1.25/v1.25">Envoy Proxy 1.25.4 Release Notes</a>
        docs: https://www.envoyproxy.io/docs/envoy/v1.25.4/version_history/v1.25/v1.25

      - title: Shipped Helm chart v8.6.0
        type: change
        body: >-
          - Update default image to $productName$ v3.6.0. <br/>

          - Add support for setting <code>nodeSelector</code>, <code>tolerations</code> and <code>affinity</code> on the Ambassador Agent. Thanks to <a href="https://github.com/ppanyukov">Philip Panyukov</a>. <br/>

          - Use autoscaling API version based on Kubernetes version. Thanks to <a href="https://github.com/eevdev">Elvind Valderhaug</a>. <br/>

          - Upgrade <code>KubernetesEndpointResolver</code> & <code>ConsulResolver</code> apiVersions to <code>getambassador.io/v3alpha1</code>

        docs: https://github.com/emissary-ingress/emissary/blob/master/charts/emissary-ingress/CHANGELOG.md

  - version: 3.5.2
    date: '2023-04-05'
    notes:
      - title: Upgrade to Envoy 1.24.5
        type: security
        body: >-
          This upgrades $productName$ to be built on Envoy v1.24.5. This update includes various security patches including CVE-2023-27487, CVE-2023-27491, CVE-2023-27492, CVE-2023-27493, CVE-2023-27488, and CVE-2023-27496. It also contains the dependency update for c-ares which was patched on top.<br/><br/>

          One notable item is that upstream header names and values are now validated according to RFC 7230, section 3.2. Users utilizing external filters should check whether their external service is forwarding headers containing forbidden characters
      - title: Upgrade to Golang 1.20.3
        type: security
        body: >-
          Upgrading to the latest release of Golang as part of our general dependency upgrade process. This includes security fixes for CVE-2023-24537, CVE-2023-24538, CVE-2023-24534, CVE-2023-24536.

  - version: 3.5.1
    date: '2023-02-24'
    notes:
      - title: Fix regression with ExternalFilter parsing port incorrectly
        type: bugfix
        body: >-
          A regression with parsing the <code>authService</code> field of the ExternalFilter has been fixed. This would cause the ExternalFilter to fail without sending a request to the service causing a 403 response.

      - title: Shipped Helm chart v8.5.1
        type: bugfix
        body: >-
          Fix regression where the <code>Module</code> resource fails validation when setting the <code>ambassador_id</code> after upgrading to <code>getambassador.io/v3alpha1</code>.<br/><br/>

          Thanks to <a href="https://github.com/pie-r">Pier</a>.

        docs: https://github.com/datawire/edge-stack

  - version: 3.5.0
    date: '2023-02-15'
    notes:
      - title: Upgraded to golang 1.20.1
        type: security
        body: >-
          Upgraded to the latest release of Golang as part of our general dependency upgrade process. This includes
          security fixes for CVE-2022-41725, CVE-2022-41723.

      - title: TracingService support for native OpenTelemetry driver
        type: feature
        body: >-
          In Envoy 1.24, experimental support for a native OpenTelemetry tracing driver was introduced that allows exporting spans in the otlp format. Many observability platforms accept that format and is the recommended replacement for the LightStep driver. $productName$ now supports setting the <code>TracingService.spec.driver=opentelemetry</code> to export traces in the otlp format.<br/><br/>

          Thanks to <a href="https://github.com/psalaberria002">Paul</a> for helping us get this tested and over the finish line!

      - title: Switch to a non-blocking readiness check
        type: feature
        body: >-
          The <code>/ready</code> endpoint used by $productName$ was using the Envoy admin port (8001 by default).This generates a problem during config reloads with large configs as the admin thread is blocking so the /ready endpoint can be very slow to answer (in the order of several seconds, even more).<br/><br/>

          $productName$ will now use a specific envoy listener that can answer /ready calls from an Envoy worker thread so the endpoint is always fast and it does not suffer from single threaded admin thread slowness on config reloads and other slow endpoints handled by the admin thread.<br/><br/>

          Configure the listener port using <code>AMBASSADOR_READY_PORT</code> and enable access log using <code>AMBASSADOR_READY_LOG</code> environment variables.

        docs: https://www.getambassador.io/docs/edge-stack/latest/topics/running/environment/

      - title: Fix envoy config generated when including port in Host.hostname
        type: bugfix
        body: >-
          When wanting to expose traffic to clients on ports other than 80/443, users will set a port in the Host.hostname (eg.<code>Host.hostname=example.com:8500</code>). The config generated allowed matching on the :authority header. This worked in v1.Y series due to the way $productName$ was generating Envoy configuration under a single wild-card virtual_host and matching on :authority.<br/><br/>

          In v2.Y/v3.Y+, the way $productName$ generates Envoy configuration changed to address memory pressure and improve route lookup speed in Envoy. However, when including a port in the hostname, an incorrect configuration was generated with an sni match including the port. This caused incoming request to never match causing a 404 Not Found.This has been fixed and the correct envoy configuration is
          being generated which restores existing behavior.

      - title: Fix GRPC TLS support with ExternalFilter
        type: bugfix
        body: >-
          Configuring an <code>ExternalFilter</code> to communicate using gRPC with TLS would fail due to $productName$ trying to connect via cleartext. This has been fixed so that setting <code>ExternalFilter.spec.tls=true</code> $productName$ will talk to the external filter using TLS. <br/><br/>

          If using self-signed certs see <a href="https://www.getambassador.io/docs/edge-stack/latest/topics/using/filters#installing-self-signed-certificates">installing self-signed certificates</a> on how to include it into the $productName$ deployment.

      - title: Add support for resolving port names in Ingress resource
        type: change
        body: >-
          Previously, specifying backend ports by name in Ingress was not supported and would result in defaulting to port 80. This allows $productName$ to now resolve port names for backend services. If the port number cannot be resolved by the name (e.g named port in the Service doesn't exist) then it will continue to default back
          to port 80. <br/><br/>

          Thanks to <a href="https://github.com/antonu17">Anton Ustyuzhanin</a>!.
        github:
          - title: '#4809'
            link: https://github.com/emissary-ingress/emissary/pull/4809

      - title: Upgraded to Python 3.10
        type: change
        body: >-
          Upgraded to Python 3.10 as part of continued investment in keeping dependencies updated.

      - title: Upgraded base image to alpine-3.17
        type: change
        body: >-
          Upgraded base image to alpine-3.17 as part of continued investment in keeping dependencies updated.

      - title: Shipped Helm chart v8.5.0
        type: change
        body: >-
          - Update default image to $productName$ v3.5.0.<br/>

          - Add support for configuring <code>startupProbes</code> on the $productName$ deployment.<br/>

          - Allow setting pod and container security settings on the Ambassador Agent.<br/>

          - Added new securityContext fields to the Redis and Agent helm charts, allowing users to further manage privilege and access control settings which can be used for tools such as PodSecurityPolicy.<br/>

          - Added deprecation notice in the values.yaml file for  <code>podSecurityPolicy</code> value because support has been removed in Kubernetes 1.25.

        docs: https://github.com/datawire/edge-stack

  - version: 3.4.1
    date: '2023-02-07'
    notes:
      - title: Upgrade to Envoy 1.24.2
        type: security
        body: >-
          This upgrades $productName$ to be built on Envoy v1.24.2. This update addresses the folowing notable items:<br/><br/>

          - Updates boringssl to address High CVE-2023-0286<br/>
          - Updates c-ares dependency to address issue with cname wildcard dns resolution for upstream clusters<br/><br/>

          Users that are using $productName$ with Certificate Revocation List and allow external users to provide input should upgrade to ensure they are not vulnerable to CVE-2023-0286.

  - version: 3.4.0
    date: '2023-01-03'
    notes:
      - title: Upgrade to Envoy 1.24.1
        type: feature
        body: >-
          This upgrades $productName$ to be built on Envoy v1.24.1. Two notable changes were introduced:<br/><br/>

          First, the team at LightStep and the Envoy Maintainers have decided to no longer support the native <b>LightStep</b> tracing driver in favor of using the Open Telemetry driver. The code for the native Enovy LightStep driver has been removed from the Envoy code base. This means $productName$ will no longer support LightStep in the <code>TracingService</code>. The recommended upgrade path is to leverage a supported Tracing driver such as <code>Zipkin</code> and use the <a href="https://opentelemetry.io/docs/collector/">Open Telemetry Collector</a> to collect and forward Observabity data to LightStep. A guide for this can be found here: <a href="howtos/tracing-lightstep/">Distributed Tracing with Open Telemetry and LightStep</a>.<br/><br/>

          Second, a bug was fixed in Envoy 1.24 that changes how the upstream clusters distributed tracing <code>span</code> is named. Prior to Envoy 1.24 it would always set the span name to the <code>cluster.name</code>. The expected behavior from Envoy was that if provided an <code>alt_stat_name</code> then use it else fallback to <code>cluster.name</code>.

        docs: https://www.envoyproxy.io/docs/envoy/latest/version_history/v1.24/v1.24

      - title: Re-add support for getambassador.io/v1
        type: feature
        body: >-
          Support for the <code>getambassador.io/v1</code> apiVersion has been re-introduced, in order to facilitate smoother migrations from $productName$ 1.y.  Previously, in order to make migrations possible, an "unserved" <code>v1</code> version was declared to Kubernetes, but was unsupported by $productName$.  That unserved <code>v1</code> could
          cause an excess of errors to be logged by the Kubernetes Nodes (regardless of whether the installation was migrated from 1.y or was a fresh 2.y install).

          It is still recommeded that `v3alpha1` be used but fully supporting <code>v1</code> again should resolve these errors.
        docs: https://github.com/emissary-ingress/emissary/pull/4055

      - title: Add support for active health checking configuration.
        type: feature
        body: >-
          It is now possible to configure active healhchecking for upstreams within a <code>Mapping</code>. If the upstream fails its configured health check then Envoy will mark the upstream as unhealthy and no longer send traffic to that upstream. Single pods within a group may can be marked as unhealthy. The healthy pods will continue to receive
          traffic normally while the unhealthy pods will not receive any traffic until they recover by passing the health check.
        docs: howtos/active-health-checking/

      - title: Add environment variables to the healthcheck server.
        type: feature
        body: >-
          The healthcheck server's bind address, bind port and IP family can now be configured using environment variables:<br/><br/>

          <code>AMBASSADOR_HEALTHCHECK_BIND_ADDRESS</code>: The address to bind the healthcheck server to.<br/><br/>

          <code>AMBASSADOR_HEALTHCHECK_BIND_PORT</code>: The port to bind the healthcheck server to.<br/><br/>

          <code>AMBASSADOR_HEALTHCHECK_IP_FAMILY</code>: The IP family to use for the healthcheck server.<br/><br/>

          This allows the healthcheck server to be configured to use IPv6-only k8s environments. (Thanks to <a href="https://github.com/TimonOmsk">Dmitry Golushko</a>!).

      - title: Added metrics for External Filters to the /metrics endpoint
        type: feature
        body: >-
          $productName$ now tracks metrics for External Filters which includes responses approved/denied, the response codes returned as well as configuration and connection errors.
        docs: topics/using/filters/external/#metrics

      - title: Allow setting the OAuth2 client's session max idle time
        type: feature
        body: >-
          When using the OAuth2 Filter, $productName$ creates a new session when submitting requests to the upstream backend server and sets a cookie containing the sessionID. This session has a limited lifetime before it expires or is extended, prompting the user to log back in.

          This session idle length can now be controlled under a new field in the OAuth2 Filter, <code>clientSessionMaxIdle</code>, which controls how long the session will be active without activity before it is expired.
        docs: topics/using/filters/oauth2

      - title: Updated redis client to improve performance with Redis
        type: change
        body: >-
          We have updated the client library used to communicate with Redis. The new client provides support for better connection handling and sharing and improved overall performance. As part of our update to
          the new driver we reduced chattiness with Redis by taking advantage
          of Pipelinig and Scripting features of Redis.

          This means the <code>AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED</code> flag is now a no-op and can be safely removed.

      - title: Adopt stand alone Ambassador Agent
        type: change
        body: >-
          Previously, the Agent used for communicating with Ambassador Cloud was bundled into $productName$. This tied it to the same release schedule as $productName$ and made it difficult to iterate on its feature set. It has now been extracted into its own repository and has its own release process and schedule.
        docs: https://github.com/datawire/ambassador-agent

      - title: Fix Filters not properly caching large jwks responses
        type: bugfix
        body: >-
          In some cases, a <code>Filter</code> would fail to properly cache the response from the jwks endpoint due to the response being too large to cache. This would hurt performance and cause $productName$ to be rate-limited by the iDP. This has been fixed to accomodate iDP's that are configured to support multiple key sets thus returning a response that is larger than the typical default response from most iDP's.

  - version: 3.3.1
    date: '2022-12-08'
    notes:
      - title: Update Golang to 1.19.4
        type: security
        body: >-
          Updated Golang to latest 1.19.4 patch release which contained two CVEs: CVE-2022-41720, CVE-2022-41717.

          CVE-2022-41720 only affects Windows and $productName$ only ships on Linux. CVE-2022-41717 affects HTTP/2 servers that are exposed to external clients. By default, $productName$ exposes the endpoints for DevPortal, Authentication Service, and RateLimitService via Envoy. Envoy enforces a limit on request header size which mitigates the vulnerability.

  - version: 3.3.0
    date: '2022-11-02'
    notes:
      - title: Update Golang to 1.19.2
        type: security
        body: >-
          Updated Golang to 1.19.2 to address the CVEs: CVE-2022-2879, CVE-2022-2880, CVE-2022-41715.

      - title: Update golang.org/x/net
        type: security
        body: >-
          Updated golang.org/x/net to address the CVE: CVE-2022-27664.

      - title: Update golang.org/x/text
        type: security
        body: >-
          Updated golang.org/x/text to address the CVE: CVE-2022-32149.

      - title: Update JWT library
        type: security
        body: >-
          Updated our JWT library from https://github.com/dgrijalva/jwt-go to https://github.com/golang-jwt/jwt in order to address spurious complaints about CVE-2020-26160. Edge Stack has never been affected by CVE-2020-26160.

      - title: Fix regression in http to https redirects with AuthService
        type: bugfix
        body: >-
          By default $productName$ adds routes for http to https redirection. When
          an AuthService is applied in v2.Y of $productName$, Envoy would skip the
          ext_authz call for non-tls http request and would perform the https
          redirect. In Envoy 1.20+ the behavior has changed where Envoy will
          always call the ext_authz filter and must be disabled on a per route
          basis.
          This new behavior change introduced a regression in v3.0 of
          $productName$ when it was upgraded to Envoy 1.22. The http to https
          redirection no longer works when an AuthService was applied. This fix
          restores the previous behavior by disabling the ext_authz call on the
          https redirect routes.
        github:
          - title: '#4620'
            link: https://github.com/emissary-ingress/emissary/issues/4620

      - title: Fix regression in host_redirects with AuthService
        type: bugfix
        body: >-
          When an AuthService is applied in v2.Y of $productName$,
          Envoy would skip the ext_authz call for all redirect routes and
          would perform the redirect. In Envoy 1.20+ the behavior has changed
          where Envoy will always call the ext_authz filter so it must be
          disabled on a per route basis.
          This new behavior change introduced a regression in v3.0 of
          $productName$ when it was upgraded to Envoy 1.22. The host_redirect
          would call an AuthService prior to redirect if applied. This fix
          restores the previous behavior by disabling the ext_authz call on the
          host_redirect routes.
        github:
          - title: '#4640'
            link: https://github.com/emissary-ingress/emissary/issues/4640

      - title: Propagate trace headers to http external filter
        type: change
        body: >-
          Previously, tracing headers were not propagated to an ExternalFilter configured with <code>proto: http</code>. Now, adding supported tracing headers (b3, etc...) to the <code>spec.allowed_request_headers</code> will propagate them to the configured service.
        docs: topics/using/filters/external/#tracing-header-propagation
        github:
          - title: '#3078'
            link: https://github.com/datawire/apro/issues/3078

  - version: 3.2.0
    date: '2022-09-27'
    notes:
      - title: Update Golang to 1.19.1
        type: security
        body: >-
          Updated Golang to 1.19.1 to address the CVEs: CVE-2022-27664, CVE-2022-32190.

      - title: Add Post Logout Redirect URI support for Oauth2 Filter
        type: feature
        body: >-
          You may now define (on supported IDPs) a <code>postLogoutRedirectURI</code> to your <code>Oauth2</code> filter.
          This will allow you to redirect to a specific URI upon logging out. However, in order to achieve this you must
          define your IDP logout URL to <code>https:{{host}}/.ambassador/oauth2/post-logout-redirect</code>. Upon logout
          $productName$ will redirect to the custom URI which will then redirect to the URI you have defined in <code>postLogoutRedirectURI</code>.
        docs: topics/using/filters/oauth2

      - title: Add support for Host resources using secrets from different namespaces
        type: feature
        body: >-
          Previously the <code>Host</code> resource could only use secrets that are in the namespace as the
          Host. The <code>tlsSecret</code> field in the Host has a new subfield <code>namespace</code> that will allow
          the use of secrets from different namespaces.
        docs: topics/running/tls/#bring-your-own-certificate

      - title: Allow bypassing of EDS for manual endpoint insertion
        type: feature
        body: >-
          Set <code>AMBASSADOR_EDS_BYPASS</code> to <code>true</code> to bypass EDS handling of endpoints and have endpoints be
          inserted to clusters manually. This can help resolve with <code>503 UH</code> caused by certification rotation relating to
          a delay between EDS + CDS. The default is <code>false</code>.
        docs: topics/running/environment/#ambassador_eds_bypass

      - title: Add support for config change batch window before reconfiguring Envoy
        type: feature
        body: >-
          The <code>AMBASSADOR_RECONFIG_MAX_DELAY</code> env var can be optionally set to batch changes for the specified
          non-negative window period in seconds before doing an Envoy reconfiguration. Default is "1" if not set

      - title: Allow setting custom_tags for traces
        type: feature
        body: >-
          It is now possible to set <code>custom_tags</code> in the
          <code>TracingService</code>. Trace tags can be set based on
          literal values, environment variables, or request headers. The existing <code>tag_headers</code> field is now deperacated. If both <code>tag_headers</code> and <code>custom_tags</code> are set then <code>tag_headers</code> will be ignored.
          (Thanks to <a href="https://github.com/psalaberria002">Paul</a>!)
        docs: topics/running/services/tracing-service/

      - title: Add failure_mode_deny option to the RateLimitService
        type: feature
        body: >-
          By default, when Envoy is unable to communicate with the configured
          RateLimitService then it will allow traffic through. The
          <code>RateLimitService</code> resource now exposes the
          <a href="https://www.envoyproxy.io/docs/envoy/v1.23.0/configuration/http/http_filters/rate_limit_filter">failure_mode_deny</a>
          option. Set <code>failure_mode_deny: true</code>, then Envoy will
          deny traffic when it is unable to communicate to the RateLimitService
          returning a 500.

      - title: Change to behavior for associating Hosts with Mappings and Listeners with Hosts
        type: change
        body: >-
          Changes to label matching will change how <code>Hosts</code> are associated with <code>Mappings</code> and how <code>Listeners</code> are associated with <code>Hosts</code>. There was a bug with label
          selectors that was causing resources that configure a <code>selector</code> to be incorrectly associated with more resources than intended.
          If any single label from the selector was matched then the resources would be associated.
          Now it has been updated to correctly only associate these resources if <b>all</b> labels required by
          their selector are present. This brings the <code>mappingSelector</code>/<code>selector</code> fields in-line with how label selectors are used
          in Kubernetes. To avoid unexpected behavior after the upgrade, add all labels that <code>Hosts</code>/<code>Listeners</code> have in their
          <code>mappingSelector</code>/<code>selector</code> to <code>Mappings</code>/<code>Hosts</code> you want to associate with them. You can opt-out of the new behavior
          by setting the environment variable <code>DISABLE_STRICT_LABEL_SELECTORS</code> to <code>"true"</code> (default: <code>"false"</code>).
          (Thanks to <a href="https://github.com/f-herceg">Filip Herceg</a> and <a href="https://github.com/dynajoe">Joe Andaverde</a>!).
        docs: topics/running/environment/#disable_strict_label_selectors

      - title: Envoy upgraded to 1.23.0
        type: change
        body: >-
          The envoy version included in $productName$ has been upgraded from 1.22 to that latest release of 1.23.0. This provides $productName$ with the latest security patches, performances enhancments,and features offered by the envoy proxy.
        docs: https://www.envoyproxy.io/docs/envoy/latest/version_history/v1.23/v1.23.0

      - title: Properly convert FilterPolicy and ExternalFilter between CRD versions
        type: bugfix
        body: >-
          Previously, $productName$ would incorrectly include empty fields when converting a FilterPolicy or ExternalFilter between versions. This would cause undesired state to be persisted in k8s which would lead to validation issues when trying to kubectl apply the custom resource. This fixes these issues to ensure the correct data is being persisted and roundtripped properly between CRD versions.

      - title: Correctly manage cluster names when service names are very long
        type: bugfix
        body: >-
          Distinct services with names that are the same in the first forty characters will no longer be incorrectly mapped to the same cluster.
        github:
          - title: '#4354'
            link: https://github.com/emissary-ingress/emissary/issues/4354

      - title: Properly populate alt_stats_name for Tracing, Auth and RateLimit Services
        type: bugfix
        body: >-
          Previously, setting the <code>stats_name</code> for the <code>TracingService</code>, <code>RateLimitService</code>
          or the <code>AuthService</code> would have no affect because it was not being properly passed to the Envoy cluster
          config. This has been fixed and the <code>alt_stats_name</code> field in the cluster config is now set correctly.
          (Thanks to <a href="https://github.com/psalaberria002">Paul</a>!).

      - title: Diagnostics stats properly handles parsing envoy metrics with colons
        type: bugfix
        body: >-
          If a <code>Host</code> or <code>TLSContext</code> contained a hostname with a <code>:</code> when using the
          diagnostics endpoints <code>ambassador/v0/diagd</code> then an error would be thrown due to the parsing logic not
          being able to handle the extra colon. This has been fixed and $productName$ will not throw an error when parsing
          envoy metrics for the diagnostics user interface.

      - title: TCPMappings use correct SNI configuration
        type: bugfix
        body: >-
          $productName$ 2.0.0 introduced a bug where a <code>TCPMapping</code> that uses SNI,
          instead of using the hostname glob in the <code>TCPMapping</code>, uses the hostname glob
          in the <code>Host</code> that the TLS termination configuration comes from.

      - title: TCPMappings configure TLS termination without a Host resource
        type: bugfix
        body: >-
          $productName$ 2.0.0 introduced a bug where a <code>TCPMapping</code> that terminates TLS
          must have a corresponding <code>Host</code> that it can take the TLS configuration from.
          This was semi-intentional, but didn't make much sense.  You can now use a
          <code>TLSContext</code> without a <code>Host</code>as in $productName$ 1.y releases, or a
          <code>Host</code> with or without a <code>TLSContext</code> as in prior 2.y releases.

      - title: TCPMappings and HTTP Hosts can coexist on Listeners that terminate TLS
        type: bugfix
        body: >-
          Prior releases of $productName$ had the arbitrary limitation that a
          <code>TCPMapping</code> cannot be used on the same port that HTTP is served on, even if
          TLS+SNI would make this possible.  $productName$ now allows <code>TCPMappings</code> to be
          used on the same <code>Listener</code> port as HTTP <code>Hosts</code>, as long as that
          <code>Listener</code> terminates TLS.

  - version: 3.1.0
    date: '2022-08-01'
    notes:
      - title: Add new Filter to support authenticating APIKey's
        type: feature
        body: >-
          A new <code>Filter</code> has been added to support validating APIKey's on incoming requests.The new <code>APIKeyFilter</code> when applied with a <code>FilterPolicy</code> will check to
          see if the incoming requests has a valid API Key in the request header. $productName$ uses Kubernetes <code>Secret</code>'s to lookup valid keys for authorizing requests.
        docs: topics/using/filters/apikeys
      - title: Add support to watch for secrets with APIKey's
        type: feature
        body: >-
          Emissary-ingress has been taught to watch for APIKey secrets when $productName$ is running and
          makes them available to be used with the new <code>APIKeyFilter</code>.
      - title: A new experimental Redis driver for use with the OAuth2 Filter
        type: feature
        body: >-
          A new opt-in feature flag has been added that allows $productName$ to use a new Redis driver when storing state between requests for the OAuth2 Filter. The new driver has better connection pool handling, shares connections and supports the Redis RESP3 protocol.

          Set <code>AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED=true</code> to enable the experimental feature. Most of the standard Redis configuration fields (e.g.<code>REDIS_*</code>) can be used with the driver.
          However, due to the drivers better connection handling the new driver no longer supports setting <code>REDIS_SURGE_LIMIT_INTERVAL</code>, <code>REDIS_SURGE_LIMIT_AFTER</code>, <code>REDIS_SURGE_POOL_SIZE</code>, <code>REDIS_SURGE_POOL_DRAIN_INTERVAL</code> and these will be ignored.

          Note: Other $productName$ features such as the <code>RateLimitService</code> will continue to use the current
          Redis driver and in future releases we plan to roll out the new driver for those features as well.
      - title: Add support for injecting a valid synthetic RateLimitService
        type: change
        body: >-
          If $productName$ is running then Emissary-ingress ensures that only a single RateLimitService is active. If a user doesn't provide one or provides an invalid one then a synthetic RateLimitService will be
          injected. If the <code>protocol_version</code> field is not set or set to an invalid value then it will automatically get upgraded <code>protocol_version: v3</code>.

          This matches the existing behavior that was introduced in $productName$ v3.0.0 for the <code>AuthService</code>. For new installs a valid <code>RateLimitService</code> will be added but this
          change ensures a smooth upgrade from $productName$ to v2.3.Z to v3.Y for users who use the manifest in a GitOps scenario.
      - title: Add Agent support for OpenAPI 2 contracts
        type: feature
        body: >-
          The agent is now able to parse api contracts using swagger 2, and to convert them to OpenAPI 3, making them available for use in the dev portal.
      - title: Default YAML enables the diagnostics interface from non-local clients on the admin service port
        type: change
        body: >-
          In the standard published <code>.yaml</code> files, the <code>Module</code> resource enables serving remote client requests to the <code>:8877/ambassador/v0/diag/</code> endpoint.The associated Helm chart release also now enables it by default.
      - title: Add additional pprof endpoints
        type: change
        body: >-
          Add pprof endpoints serving additional profiles including CPU profiles (<code>/debug/pprof/profile</code>) and tracing (<code>/debug/pprof/trace</code>). Also add additional endpoints serving the command line running (<code>/debug/pprof/cmdline</code>) and program counters (<code>/debug/pprof/symbol</code>) for the sake of completeness.
      - title: Correct cookies for mixed HTTP/HTTPS OAuth2 origins
        type: bugfix
        body: >-
          When an <code>OAuth2</code> filter sets cookies for a <code>protectedOrigin</code>, it should set a cookie's "Secure" flag to true for <code>https://</code> origins and false for <code>http://</code> origins.  However, for filters with multiple origins, it set the cookie's flag based on the first origin listen in the Filter, rather than the origin that the cookie is actually for.
      - title: Correctly handle refresh tokens for OAuth2 filters with multiple origins
        type: bugfix
        body: >-
          When an <code>OAuth2</code> filter with multiple <code>protectedOrigins</code> needs to adjust the cookies for an active login (which only happens when using a refresh token), it
          would erroneously redirect the web browser to the last origin listed, rather than returning to the original URL.  This has been fixed.
      - title: Correctly handle CORS and CORs preflight request within the OAuth2 Fitler known endpoints
        type: bugfix
        body: >-
          Previously, the <code>OAuth2</code> filter's known endpoints <code>/.ambassador/oauth2/logout</code> and <code>/.ambassador/oauth2/multicookie</code> did not understand CORS or CORS preflight request
          which would cause the browser to reject the request. This has now been fixed and these endpoints will attach the appropriate CORS headers to the response.
      - title: Fix regression in the agent for the metrics transfer.
        type: bugfix
        body: >-
          A regression was introduced in 2.3.0 causing the agent to miss some of the metrics coming from emissary ingress before sending them to Ambassador cloud. This issue has been resolved to ensure that all the nodes composing the emissary ingress cluster are reporting properly.
      - title: Handle long cluster names for injected acme-challenge route.
        type: bugfix
        body: >-
          Previously, we would inject an upstream route for acme-challenge that was targeting the localhost auth service cluster. This route is injected to make Envoy configuration happy and the AuthService
          that is shipped with $productName$ will handle it properly. However, if the cluster name is longer than 60 characters due to a long namespace, etc... then $productName$ will truncate it and make
          sure it is unique. When this happens the name of the cluster assigned to the acme-challenge route would get out-of-sync and would introduce invalid Envoy configuration.

          To avoid this $productName$ will now inject a route that returns a direct <code>404</code> response rather than pointing at an arbitrary cluster. This matches existing behavior and is a transparent
          change to the user.

      - title: Update Golang to 1.17.12
        type: security
        body: >-
          Updated Golang to 1.17.12 to address the CVEs: CVE-2022-23806, CVE-2022-28327, CVE-2022-24675,
          CVE-2022-24921, CVE-2022-23772.

      - title: Update Curl to 7.80.0-r2
        type: security
        body: >-
          Updated Curl to 7.80.0-r2 to address the CVEs: CVE-2022-32207, CVE-2022-27782, CVE-2022-27781,
          CVE-2022-27780.

      - title: Update openSSL-dev to 1.1.1q-r0
        type: security
        body: >-
          Updated openSSL-dev to 1.1.1q-r0 to address CVE-2022-2097.

      - title: Update ncurses to 1.1.1q-r0
        type: security
        body: >-
          Updated ncurses to 1.1.1q-r0 to address CVE-2022-29458

      - title: Upgrade jwt-go
        type: security
        body: >-
          Upgrade jwt-go to latest commit to resolve CVE-2020-26160.

  - version: 3.0.0
    date: '2022-06-28'
    notes:
      - title: Upgrade to Envoy 1.22
        type: change
        body: >-
          $productName$ has been upgraded to Envoy 1.22 which provides security, performance and feature enhancements. You can read more about them here: <a href="https://www.envoyproxy.io/docs/envoy/v1.22.0/version_history/current">Envoy Proxy 1.22.0 Release Notes</a>

          This is a major jump in Envoy versions from the current of 1.17 in EdgeStack 2.X. Most of the changes are under the hood and allow  $productName$ to adopt new features in the future. However, one major change that will effect users is the removal of V2 Transport Protocol support. You can find a transition guide here:  <a href=""></a>

      - title: Envoy V2 xDS Transport Protocol Support Removed
        type: change
        body: >-
          Envoy removed support for V2 xDS Transport Protocol which means $productName$ now only supports the Envoy V3 xDS Transport Protocol.

          User should first upgrade to $productName$ 2.3 prior to ensure that the <code>LogService</code>s and External <code>Filter</code>s are working properly by setting <code>protocol_version: "v3"</code>.

          If <code>protocol_version</code> is not specified in 3.Y, the default  value of <code>v2</code> will cause an error to be posted and a static response will be returned. Therefore, you must set it to <code>protocol_version: v3</code>. If upgrading from a previous version, you will want  to set it to <code>v3</code> and ensure it is working before upgrading to Emissary-ingress 3.Y. The default value for <code>protocol_version</code> remains <code>v2</code> in the <code>getambassador.io/v3alpha1</code> CRD specifications to avoid making breaking changes outside of a CRD version change. Future versions of CRD's will deprecate it.
        docs: topics/using/filters/external

      - title: Initial HTTP/3 Downstream Support
        type: feature
        body: >-
          With the upgrade to Envoy, $productName$ is now able to provide downstream support for HTTP/3. The initial implementation supports exposing http/3 endpoints on port `443`. Future version of $productName$ will seek to provide additional configuration to support more scenarios.

          HTTP/3 uses the Quic protocol over UDP. Changes to your cloud provider provisioned Load Balancer will be required to support UDP traffic if using HTTP/3. External Load Balancers must serve traffic on port <code>443</code> because the <code>alt-svc</code> header is not configurable in the initial release of the feature.
        docs: topics/running/http3

  - version: 2.5.1
    date: '2022-12-08'
    notes:
      - title: Update Golang to 1.19.4
        type: security
        body: >-
          Updated Golang to latest 1.19.4 patch release which contained two CVEs: CVE-2022-41720, CVE-2022-41717.

          CVE-2022-41720 only affects Windows and $productName$ only ships on Linux. CVE-2022-41717 affects HTTP/2 servers that are exposed to external clients. By default, $productName$ exposes the endpoints for DevPortal, Authentication Service, and RateLimitService via Envoy. Envoy enforces a limit on request header size which mitigates the vulnerability.

  - version: 2.5.0
    date: '2022-11-03'
    notes:
      - title: Propagate trace headers to http external filter
        type: change
        body: >-
          Previously, tracing headers were not propagated to an ExternalFilter configured with
          `proto: http`. Now, adding supported tracing headers (b3, etc...) to the
          `spec.allowed_request_headers` will propagate them to the configured service.
        github:
          - title: '#3078'
            link: https://github.com/datawire/apro/issues/3078

      - title: Diagnostics stats properly handles parsing envoy metrics with colons
        type: bugfix
        body: >-
          If a <code>Host</code> or <code>TLSContext</code> contained a hostname with a <code>:</code> then when using the
          diagnostics endpoints <code>ambassador/v0/diagd</code> then an error would be thrown due to the parsing logic not
          being able to handle the extra colon. This has been fixed and $productName$ will not throw an error when parsing
          envoy metrics for the diagnostics user interface.

      - title: Bump Golang to 1.19.2
        type: security
        body: >-
          Bump Go from 1.17.12 to 1.19.2. This is to keep the Go version current.

  - version: 2.4.2
    date: '2022-10-10'
    notes:
      - title: Diagnostics stats properly handles parsing envoy metrics with colons
        type: bugfix
        body: >-
          If a <code>Host</code> or <code>TLSContext</code> contained a hostname with a <code>:</code> then when using the diagnostics endpoints <code>ambassador/v0/diagd</code> then an error would be thrown due to the parsing logic not being able to handle the extra colon. This has been fixed and $productName$ will not throw an error when parsing envoy metrics for the diagnostics user interface.

      - title: Backport fixes for handling synthetic auth services
        type: bugfix
        body: >-
          The synthetic AuthService didn't correctly handle AmbassadorID, which was fixed in version 3.1 of $productName$.The fix has been backported to make sure the AuthService is handled correctly during upgrades.

  - version: 2.4.1
    date: '2022-09-27'
    notes:
      - title: Addressing release issue with 2.4.0
        type: bugfix
        body: >-
          During the $productName$ 2.4.0 release process there was an issue with the Emissary binary. This has been patched and resolved.

  - version: 2.4.0
    date: '2022-09-19'
    notes:
      - title: Add support for Host resources using secrets from different namespaces
        type: feature
        body: >-
          Previously the <code>Host</code> resource could only use secrets that are in the namespace as the
          Host. The <code>tlsSecret</code> field in the Host has a new subfield <code>namespace</code> that will allow
          the use of secrets from different namespaces.
        docs: topics/running/tls/#bring-your-own-certificate

      - title: Allow bypassing of EDS for manual endpoint insertion
        type: change
        body: >-
          Set <code>AMBASSADOR_EDS_BYPASS</code> to <code>true</code> to bypass EDS handling of endpoints and have endpoints be
          inserted to clusters manually. This can help resolve with <code>503 UH</code> caused by certification rotation relating to
          a delay between EDS + CDS. The default is <code>false</code>.
        docs: topics/running/environment/#ambassador_eds_bypass

      - title: Properly convert FilterPolicy and ExternalFilter between CRD versions
        type: bugfix
        body: >-
          Previously, $productName$ would incorrectly include empty fields when converting a FilterPolicy or ExternalFilter between versions. This would cause undesired state to be persisted in k8s which would lead to validation issues when trying to kubectl apply the custom resource. This fixes these issues to ensure the correct data is being persisted and roundtripped properly between CRD versions.

      - title: Properly populate alt_stats_name for Tracing, Auth and RateLimit Services
        type: bugfix
        body: >-
          Previously, setting the <code>stats_name</code> for the <code>TracingService</code>, <code>RateLimitService</code>
          or the <code>AuthService</code> would have no affect because it was not being properly passed to the Envoy cluster
          config. This has been fixed and the <code>alt_stats_name</code> field in the cluster config is now set correctly.
          (Thanks to <a href="https://github.com/psalaberria002">Paul</a>!)

      - title: Diagnostics stats properly handles parsing envoy metrics with colons
        type: bugfix
        body: >-
          If a <code>Host</code> or <code>TLSContext</code> contained a hostname with a <code>:</code> when using the
          diagnostics endpoints <code>ambassador/v0/diagd</code> then an error would be thrown due to the parsing logic not
          being able to handle the extra colon. This has been fixed and $productName$ will not throw an error when parsing
          envoy metrics for the diagnostics user interface.

      - title: TCPMappings use correct SNI configuration
        type: bugfix
        body: >-
          $productName$ 2.0.0 introduced a bug where a <code>TCPMapping</code> that uses SNI,
          instead of using the hostname glob in the <code>TCPMapping</code>, uses the hostname glob
          in the <code>Host</code> that the TLS termination configuration comes from.

      - title: TCPMappings configure TLS termination without a Host resource
        type: bugfix
        body: >-
          $productName$ 2.0.0 introduced a bug where a <code>TCPMapping</code> that terminates TLS
          must have a corresponding <code>Host</code> that it can take the TLS configuration from.
          This was semi-intentional, but didn't make much sense.  You can now use a
          <code>TLSContext</code> without a <code>Host</code>as in $productName$ 1.y releases, or a
          <code>Host</code> with or without a <code>TLSContext</code> as in prior 2.y releases.

      - title: TCPMappings and HTTP Hosts can coexist on Listeners that terminate TLS
        type: bugfix
        body: >-
          Prior releases of $productName$ had the arbitrary limitation that a
          <code>TCPMapping</code> cannot be used on the same port that HTTP is served on, even if
          TLS+SNI would make this possible.  $productName$ now allows <code>TCPMappings</code> to be
          used on the same <code>Listener</code> port as HTTP <code>Hosts</code>, as long as that
          <code>Listener</code> terminates TLS.

  - version: 2.3.2
    date: '2022-08-01'
    notes:
      - title: Correct cookies for mixed HTTP/HTTPS OAuth2 origins
        type: bugfix
        body: >-
          When an <code>OAuth2</code> filter sets cookies for a <code>protectedOrigin</code>, it
          should set a cookie's "Secure" flag to true for <code>https://</code> origins and false
          for <code>http://</code> origins.  However, for filters with multiple origins, it set the
          cookie's flag based on the first origin listen in the Filter, rather than the origin that
          the cookie is actually for.

      - title: Correctly handle refresh tokens for OAuth2 filters with multiple origins
        type: bugfix
        body: >-
          When an <code>OAuth2</code> filter with multiple <code>protectedOrigins</code> needs to
          adjust the cookies for an active login (which only happens when using a refresh token), it
          would erroneously redirect the web browser to the last origin listed, rather than
          returning to the original URL.  This has been fixed.

      - title: Correctly handle CORS and CORs preflight request within the OAuth2 Fitler known endpoints
        type: bugfix
        body: >-
          Previously, the <code>OAuth2</code> filter's known endpoints <code>/.ambassador/oauth2/logout</code>
          and <code>/.ambassador/oauth2/multicookie</code> did not understand CORS or CORS preflight request
          which would cause the browser to reject the request. This has now been fixed and these endpoints will
          attach the appropriate CORS headers to the response.

      - title: Fix regression in the agent for the metrics transfer.
        type: bugfix
        body: >-
          A regression was introduced in 2.3.0 causing the agent to miss some of the metrics coming from
          emissary ingress before sending them to Ambassador cloud. This issue has been resolved to ensure
          that all the nodes composing the emissary ingress cluster are reporting properly.

      - title: Update Golang to 1.17.12
        type: security
        body: >-
          Updated Golang to 1.17.12 to address the CVEs: CVE-2022-23806, CVE-2022-28327, CVE-2022-24675,
          CVE-2022-24921, CVE-2022-23772.

      - title: Update Curl to 7.80.0-r2
        type: security
        body: >-
          Updated Curl to 7.80.0-r2 to address the CVEs: CVE-2022-32207, CVE-2022-27782, CVE-2022-27781,
          CVE-2022-27780.

      - title: Update openSSL-dev to 1.1.1q-r0
        type: security
        body: >-
          Updated openSSL-dev to 1.1.1q-r0 to address CVE-2022-2097.

      - title: Update ncurses to 1.1.1q-r0
        type: security
        body: >-
          Updated ncurses to 1.1.1q-r0 to address CVE-2022-29458

      - title: Upgrade jwt-go
        type: security
        body: >-
          Upgrade jwt-go to latest commit to resolve CVE-2020-26160.

  - version: 2.3.1
    date: '2022-06-10'
    notes:
      - title: Fix regression in tracing service config
        type: bugfix
        body: >-
          A regression was introduced in 2.3.0 that leaked zipkin default config fields into the configuration
          for the other drivers (lightstep, etc...). This caused $productName$ to crash on startup. This issue has been resolved
          to ensure that the defaults are only applied when driver is <code>zipkin</code>
        docs: https://github.com/emissary-ingress/emissary/issues/4267

      - title: Envoy security updates
        type: security
        body: >-
          We have backported patches from the Envoy 1.19.5 security update to $productName$'s
          1.17-based Envoy, addressing CVE-2022-29224 and CVE-2022-29225. $productName$ is not
          affected by CVE-2022-29226, CVE-2022-29227, or CVE-2022-29228; as it <a
          href="https://github.com/emissary-ingress/emissary/issues/2846">does not support internal
          redirects</a>, and does not use Envoy's built-in OAuth2 filter.
        docs: https://groups.google.com/g/envoy-announce/c/8nP3Kn4jV7k

  - version: 2.3.0
    date: '2022-06-06'
    notes:
      - title: Remove unused packages
        type: security
        body: >-
          Completely remove <code>gdbm</code>, <code>pip</code>, <code>smtplib</code>, and <code>sqlite</code> packages, as they are unused.

      - title: CORS now happens before auth
        type: bugfix
        body: >-
          When CORS is specified (either in a <code>Mapping</code> or in the <code>Ambassador</code>
          <code>Module</code>), CORS processing will happen before authentication. This corrects a
          problem where XHR to authenticated endpoints would fail.

      - title: Correctly handle caching of Mappings with the same name in different namespaces
        type: bugfix
        body: >-
          In 2.x releases of $productName$ when there are multiple <code>Mapping</code>s that have the same
          <code>metadata.name</code> across multiple namespaces, their old config would not properly be removed
          from the cache when their config was updated. This resulted in an inability to update configuration
          for groups of <code>Mapping</code>s that share the same name until the $productName$ pods restarted.

      - title: Fix support for Zipkin API-v1 with Envoy xDS-v3
        type: bugfix
        body: >-
          It is now possible for a <code>TracingService</code> to specify
          <code>collector_endpoint_version: HTTP_JSON_V1</code> when using xDS v3 to configure Envoy
          (which has been the default since $productName$ 1.14.0).  The <code>HTTP_JSON_V1</code>
          value configures Envoy to speak to Zipkin using Zipkin's old API-v1, while the
          <code>HTTP_JSON</code> value configures Envoy to speak to Zipkin using Zipkin's new
          API-v2. In previous versions of $productName$ it was only possible to use
          <code>HTTP_JSON_V1</code> when explicitly setting the
          <code>AMBASSADOR_ENVOY_API_VERSION=V2</code> environment variable to force use of xDS v2
          to configure Envoy.
        docs: topics/running/services/tracing-service/

      - title: Added Support for transport protocol v3 in External Filters
        type: feature
        body: >-
          External Filters can now make use of the v3 transport protocol. In addtion to the support for the v3 transport protocol, the default <code>AuthService</code> installed with $productName$ will now only operate with transport protocol v3. In order to support existing External Filters using v2, $productName$ will automatically translate
          v2 to the new default of v3. Any External Filters will be assumed to be using transport protocol v2 and will use the automatic conversion to v3 unless the new <code>protocol_version</code> field on the External Filter is explicitly set to <code>v3</code>.
        docs: topics/using/filters/external

      - title: Allow setting propagation modes for Lightstep tracing
        type: feature
        body: >-
          It is now possible to set <code>propagation_modes</code> in the
          <code>TracingService</code> config when using lightstep as the driver.
          (Thanks to <a href="https://github.com/psalaberria002">Paul</a>!)
        docs: topics/running/services/tracing-service/
        github:
          - title: '#4179'
            link: https://github.com/emissary-ingress/emissary/pull/4179

      - title: Added Support for Certificate Revocation Lists
        type: feature
        body: >-
          $productName$ now supports <a href="https://www.envoyproxy.io/docs/envoy/v1.17.4/api-v3/extensions/transport_sockets/tls/v3/common.proto.html?highlight=crl">Envoy's Certificate Revocation lists.</a>
          This allows users to specify a list of certificates that $productName$ should reject even if the certificate itself is otherwise valid.
        docs: topics/running/tls

      - title: Added support for the LogService v3 transport protocol
        type: feature
        body: >-
          Previously, a <code>LogService</code> would always have $productName$ communicate with the
          external log service using the <code>envoy.service.accesslog.v2.AccessLogService</code>
          API. It is now possible for the <code>LogService</code> to specify
          <code>protocol_version: v3</code> to use the newer
          <code>envoy.service.accesslog.v3.AccessLogService</code> API instead.  This functionality
          is not available if you set the <code>AMBASSADOR_ENVOY_API_VERSION=V2</code> environment
          variable.
        docs: topics/running/services/log-service/

      - title: Improved performance processing OAuth2 Filters
        type: change
        body: >-
          When each OAuth2 Filter that references a Kubernetes secret is loaded, $productName$ previously needed to communicate with the API server to request and validate that secret before loading the next Filter. To improve performance, $productName$ will now load and validate all secrets required by OAuth2 Filters at once prior to loading the filters.

      - title: Deprecated v2 transport protocol for External Filters and AuthServices
        type: change
        body: >-
          A future release of $productName$ will remove support for the now deprecated v2 transport protocol in both AuthServices as well as External Filters. Migrating Existing External Filters from v2 to v3
          is simple and and example can be found on the External Filter page. This change only impacts gRPC External Filters. HTTP External Filters are unaffected by this change.
        docs: topics/using/filters/external

  - version: 2.2.2
    date: '2022-02-25'
    notes:
      - title: TLS Secret validation is now opt-in
        type: change
        body: >-
          You may now choose to enable TLS Secret validation by setting the
          <code>AMBASSADOR_FORCE_SECRET_VALIDATION=true</code> environment variable. The default configuration does not
          enforce secret validation.
        docs: topics/running/tls#certificates-and-secrets

      - title: Correctly validate EC (Elliptic Curve) Private Keys
        type: bugfix
        body: >-
          Kubernetes Secrets that should contain an EC (Elliptic Curve) TLS Private Key are now properly validated.
        github:
          - title: '#4134'
            link: https://github.com/emissary-ingress/emissary/issues/4134
        docs: topics/running/tls#certificates-and-secrets

  - version: 2.2.1
    date: '2022-02-22'
    notes:
      - title: Envoy V2 API deprecation
        type: change
        body: >-
          Support for the Envoy V2 API is deprecated as of $productName$ v2.1, and will be removed in $productName$
          v3.0. The <code>AMBASSADOR_ENVOY_API_VERSION</code> environment variable will be removed at the same
          time. Only the Envoy V3 API will be supported (this has been the default since $productName$ v1.14.0).

      - title: Envoy security updates
        type: security
        body: >-
          Upgraded Envoy to address security vulnerabilities CVE-2021-43824, CVE-2021-43825, CVE-2021-43826,
          CVE-2022-21654, and CVE-2022-21655.
        docs: https://groups.google.com/g/envoy-announce/c/bIUgEDKHl4g
      - title: Correctly support canceling rollouts
        type: bugfix
        body: >-
          The Ambassador Agent now correctly supports requests to cancel a rollout.
        docs: ../../argo/latest/howtos/manage-rollouts-using-cloud

  - version: 2.2.0
    date: '2022-02-10'
    notes:
      - title: Envoy V2 API deprecation
        type: change
        body: >-
          Support for the Envoy V2 API is deprecated as of $productName$ v2.1, and will be removed in $productName$
          v3.0. The <code>AMBASSADOR_ENVOY_API_VERSION</code> environment variable will be removed at the same
          time. Only the Envoy V3 API will be supported (this has been the default since $productName$ v1.14.0).

      - title: Ambassador Edge Stack will watch for Cloud Connect Tokens
        type: change
        body: >-
          $productName$ will now watch for ConfigMap or Secret resources specified by the
          <code>AGENT_CONFIG_RESOURCE_NAME</code> environment variable in order to allow all
          components (and not only the Ambassador Agent) to authenticate requests to
          Ambassador Cloud.
        image: ./v2.2.0-cloud.png

      - title: Update Alpine and libraries
        type: security
        body: >-
          $productName$ has updated Alpine to 3.15, and Python and Go dependencies
          to their latest compatible versions, to incorporate numerous security patches.

      - title: Support a log-level metric
        type: feature
        body: >-
          $productName$ now supports the metric <code>ambassador_log_level{label="debug"}</code>
          which will be set to 1 if debug logging is enabled for the running Emissary
          instance, or to 0 if not. This can help to be sure that a running production
          instance was not actually left doing debugging logging, for example.
          (Thanks to <a href="https://github.com/jfrabaute">Fabrice</a>!)
        github:
          - title: '#3906'
            link: https://github.com/emissary-ingress/emissary/issues/3906
        docs: topics/running/statistics/8877-metrics/

      - title: Envoy configuration % escaping
        type: feature
        body: >-
          $productName$ is now leveraging a new Envoy Proxy patch that allows Envoy to accept escaped
          '%' characters in its configuration. This means that error_response_overrides and other
          custom user content can now contain '%' symbols escaped as '%%'.
        docs: topics/running/custom-error-responses
        github:
          - title: 'DW Envoy: 74'
            link: https://github.com/datawire/envoy/pull/74
          - title: 'Upstream Envoy: 19383'
            link: https://github.com/envoyproxy/envoy/pull/19383
        image: ./v2.2.0-percent-escape.png

      - title: Stream metrics from Envoy to Ambassador Cloud
        type: feature
        body: >-
          Support for streaming Envoy metrics about the clusters to Ambassador Cloud.
        github:
          - title: '#4053'
            link: https://github.com/emissary-ingress/emissary/pull/4053
        docs: https://github.com/emissary-ingress/emissary/pull/4053

      - title: Support received commands to pause, continue and abort a Rollout via Agent directives
        type: feature
        body: >-
          The Ambassador agent now receives commands to manipulate Rollouts (pause, continue, and
          abort are currently supported) via directives and executes them in the cluster. A report
          is sent to Ambassador Cloud including the command ID, whether it ran successfully, and
          an error message in case there was any.
        github:
          - title: '#4040'
            link: https://github.com/emissary-ingress/emissary/pull/4040
        docs: https://github.com/emissary-ingress/emissary/pull/4040

      - title: Validate certificates in TLS Secrets
        type: bugfix
        body: >-
          Kubernetes Secrets that should contain TLS certificates are now validated before being
          accepted for configuration. A Secret that contains an invalid TLS certificate will be logged
          as an invalid resource.
        github:
          - title: '#3821'
            link: https://github.com/emissary-ingress/emissary/issues/3821
        docs: ../topics/running/tls
        image: ./v2.2.0-tls-cert-validation.png

      - title: Devportal support for using API server definitions from OpenAPI docs
        type: feature
        body: >-
          You can now set <code>preserve_servers</code> in Ambassador Edge Stack's
          <code>DevPortal</code> resource to configure the DevPortal to use server definitions from
          the OpenAPI document when displaying connection information for services in the DevPortal.
        docs: topics/using/dev-portal/

  - version: 2.1.2
    date: '2022-01-25'
    notes:
      - title: Envoy V2 API deprecation
        type: change
        body: >-
          Support for the Envoy V2 API is deprecated as of $productName$ v2.1, and will be removed in $productName$
          v3.0. The <code>AMBASSADOR_ENVOY_API_VERSION</code> environment variable will be removed at the same
          time. Only the Envoy V3 API will be supported (this has been the default since $productName$ v1.14.0).

      - title: Docker BuildKit always used for builds
        type: change
        body: >-
          Docker BuildKit is enabled for all Emissary builds. Additionally, the Go
          build cache is fully enabled when building images, speeding up repeated builds.
        docs: https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/syntax.md

      - title: Fix OAuth2 Filter jwtAssertion
        type: bugfix
        body: >-
          In $productName$ 2.1.0 and 2.1.1, an OAuth2 Filter with
          <code>clientAuthentication.method=jwtAssertion</code> would not function correctly as it
          would fail to select the signing-method-appropriate function to parse the private key.
        docs: topics/using/filters/oauth2
        image: ./v2.1.2-filter-jwtassertion.png

      - title: Fix ifRequestHeader without a value
        type: bugfix
        body: >-
          In $productName$ 2.1.0 and 2.1.1, an <code>ifRequestHeader</code> selector (in a
          FilterPolicy, OAuth2 Filter <code>useSessionCookies</code>, or OAuth2 Filter
          <code>insteadOfRedirect</code>) without a <code>value</code> or <code>valueRegex</code>
          would erroneously behave as if <code>valueRegex='^$'</code>, rather than performing a
          simple presence check.
        docs: topics/using/filters/#filterpolicy-definition

      - title: Fix support for for v2 Mappings with CORS
        type: bugfix
        body: >-
          Ambassador Edge Stack 2.1.1 generated invalid Envoy configuration for
          <code>getambassador.io/v2</code> <code>Mappings</code> that set
          <code>spec.cors.origins</code> to a string rather than a list of strings; this has been
          fixed, and these <code>Mappings</code> should once again function correctly.
        docs: topics/using/cors/#the-cors-attribute
        image: ./v2.1.2-mapping-cors.png

      - title: Correctly handle canary Mapping weights when reconfiguring
        type: bugfix
        body: >-
          Changes to the <code>weight</code> of <code>Mapping</code> in a canary group
          will now always be correctly managed during reconfiguration; such changes could
          have been missed in earlier releases.
        docs: topics/using/canary/#the-weight-attribute

      - title: Correctly handle solitary Mappings with explicit weights
        type: bugfix
        body: >-
          A <code>Mapping</code> that is not part of a canary group, but that has a
          <code>weight</code> less than 100, will be correctly configured to receive all
          traffic as if the <code>weight</code> were 100.
        docs: topics/using/canary/#the-weight-attribute
        image: ./v2.1.2-mapping-less-weighted.png

      - title: Correctly handle empty rewrite in a Mapping
        type: bugfix
        body: >-
          Using <code>rewrite: ""</code> in a <code>Mapping</code> is correctly handled
          to mean "do not rewrite the path at all".
        docs: topics/using/rewrites
        image: ./v2.1.2-mapping-no-rewrite.png

      - title: Correctly use Mappings with host redirects
        type: bugfix
        body: >-
          Any <code>Mapping</code> that uses the <code>host_redirect</code> field is now properly discovered and used. Thanks
          to <a href="https://github.com/gferon">Gabriel Féron</a> for contributing this bugfix!
        github:
          - title: '#3709'
            link: https://github.com/emissary-ingress/emissary/issues/3709
        docs: https://github.com/emissary-ingress/emissary/issues/3709

      - title: Correctly handle DNS wildcards when associating Hosts and Mappings
        type: bugfix
        body: >-
          <code>Mapping</code>s with DNS wildcard <code>hostname</code> will now be correctly
          matched with <code>Host</code>s. Previously, the case where both the <code>Host</code>
          and the <code>Mapping</code> use DNS wildcards for their hostnames could sometimes
          not correctly match when they should have.
        docs: howtos/configure-communications/
        image: ./v2.1.2-host-mapping-matching.png

      - title: Fix overriding global settings for adding or removing headers
        type: bugfix
        body: >-
          If the <code>ambassador</code> <code>Module</code> sets a global default for
          <code>add_request_headers</code>, <code>add_response_headers</code>,
          <code>remove_request_headers</code>, or <code>remove_response_headers</code>, it is often
          desirable to be able to turn off that setting locally for a specific <code>Mapping</code>.
          For several releases this has not been possible for <code>Mappings</code> that are native
          Kubernetes resources (as opposed to annotations), as an empty value ("mask the global
          default") was erroneously considered to be equivalent to unset ("inherit the global
          default").  This is now fixed.
        docs: topics/using/defaults/

      - title: Fix empty error_response_override bodies
        type: bugfix
        body: >-
          It is now possible to set a <code>Mapping</code>
          <code>spec.error_response_overrides</code> <code>body.text_format</code> to an empty
          string or <code>body.json_format</code> to an empty dict.  Previously, this was possible
          for annotations but not for native Kubernetes resources.
        docs: topics/running/custom-error-responses/

      - title: Annotation conversion and validation
        type: bugfix
        body: >-
          Resources that exist as <code>getambassador.io/config</code> annotations rather than as
          native Kubernetes resources are now validated and internally converted to v3alpha1 and,
          the same as native Kubernetes resources.
        image: ./v2.1.2-annotations.png

      - title: Validation error reporting
        type: bugfix
        body: >-
          Resource validation errors are now reported more consistently; it was the case that in
          some situations a validation error would not be reported.

  - version: 2.1.1
    date: '2022-01-14'
    notes:
      - title: Not recommended; upgrade to 2.1.2 instead
        type: change
        isHeadline: true
        body: >-
          <i>Ambassador Edge Stack 2.1.1 is not recommended; upgrade to 2.1.2 instead.</i>

      - title: Envoy V2 API deprecation
        type: change
        body: >-
          Support for the Envoy V2 API is deprecated as of $productName$ v2.1, and will be removed in $productName$
          v3.0. The <code>AMBASSADOR_ENVOY_API_VERSION</code> environment variable will be removed at the same
          time. Only the Envoy V3 API will be supported (this has been the default since $productName$ v1.14.0).

      - title: Fix discovery of Filters, FilterPolicies, and RateLimits
        type: bugfix
        body: >-
          In Edge Stack 2.1.0, it erroneously ignored <code>Filters</code>,
          <code>FilterPolicies</code>, and <code>RateLimits</code> that were created as
          <code>v3alpha1</code> (but correctly paid attention to them if they were created as
          <code>v2</code> or older).  This is fixed; it will now correctly pay attention to both API
          versions.
        github:
          - title: '#3982'
            link: https://github.com/emissary-ingress/emissary/issues/3982

  - version: 2.1.0
    date: '2021-12-16'
    notes:
      - title: Not recommended; upgrade to 2.1.2 instead
        type: change
        isHeadline: true
        body: >-
          <i>Ambassador Edge Stack 2.1.0 is not recommended; upgrade to 2.1.2 instead.</i>

      - title: Envoy V2 API deprecation
        type: change
        body: >-
          Support for the Envoy V2 API is deprecated as of $productName$ v2.1, and will be removed in $productName$
          v3.0. The <code>AMBASSADOR_ENVOY_API_VERSION</code> environment variable will be removed at the same
          time. Only the Envoy V3 API will be supported (this has been the default since $productName$ v1.14.0).

      - title: Smoother migrations with support for getambassador.io/v2 CRDs
        type: feature
        body: >-
          $productName$ supports <code>getambassador.io/v2</code> CRDs, to simplify migration from $productName$
          1.X. <b>Note:</b> it is important to read the <a href="../topics/install/migration-matrix">migration
          documentation</a> before starting migration.
        docs: topics/install/migration-matrix
        image: ./v2.1.0-smoother-migration.png

      - title: Ambassador Edge Stack CRDs are fully validated
        type: change
        body: >-
          The $productName$ CRDs (<code>Filter</code>, <code>FilterPolicy</code>, and <code>RateLimit</code>)
          will now be validated for correct syntax by Kubernetes itself. This means that <code>kubectl apply</code>
          will reject invalid CRDs before they are actually applied, preventing them from causing errors.
        image: ./v2.1.0-edge-stack-validation.png

      - title: Correctly handle all changing canary configurations
        type: bugfix
        body: >-
          The incremental reconfiguration cache could miss some updates when multiple
          <code>Mapping</code>s had the same <code>prefix</code> ("canary"ing multiple
          <code>Mapping</code>s together). This has been corrected, so that all such
          updates correctly take effect.
        github:
          - title: '#3945'
            link: https://github.com/emissary-ingress/emissary/issues/3945
        docs: https://github.com/emissary-ingress/emissary/issues/3945
        image: ./v2.1.0-canary.png

      - title: Secrets used for ACME private keys will not log errors
        type: bugfix
        body: >-
          When using Kubernetes Secrets to store ACME private keys (as the Edge Stack
          ACME client does), an error would always be logged about the Secret not being
          present, even though it was present, and everything was working correctly.
          This error is no longer logged.

      - title: When using gzip, upstreams will no longer receive encoded data
        type: bugfix
        body: >-
          When using gzip compression, upstream services will no longer receive compressed
          data. This bug was introduced in 1.14.0. The fix restores the default behavior of
          not sending compressed data to upstream services.
        github:
          - title: '#3818'
            link: https://github.com/emissary-ingress/emissary/issues/3818
        docs: https://github.com/emissary-ingress/emissary/issues/3818
        image: ./v2.1.0-gzip-enabled.png

      - title: Update to busybox 1.34.1
        type: security
        body: >-
          Update to busybox 1.34.1 to resolve CVE-2021-28831, CVE-2021-42378,
          CVE-2021-42379, CVE-2021-42380, CVE-2021-42381, CVE-2021-42382, CVE-2021-42383,
          CVE-2021-42384, CVE-2021-42385, and CVE-2021-42386.

      - title: Update Python dependencies
        type: security
        body: >-
          Update Python dependencies to resolve CVE-2020-28493 (jinja2), CVE-2021-28363
          (urllib3), and CVE-2021-33503 (urllib3).

      - title: Remove test-only code from the built image
        type: security
        body: >-
          Previous built images included some Python packages used only for test. These
          have now been removed, resolving CVE-2020-29651.

  - version: 2.0.5
    date: '20211109'
    notes:
      - title: More aggressive HTTP cache behavior
        type: change
        body: >-
          When Ambassador Edge Stack makes a cacheable internal request (such as fetching the JWKS
          endpoint for a <code>JWT</code> <code>Filter</code>), if a cache-miss occurs but a request
          for that resource is already in-flight, then instead of performing a second request in
          parallel, it will now wait for the first request to finish and (if the response is
          cacheable) use that response.  If the response turns out to be non-cacheable, then it will
          proceed to make the second request.  This avoids the situation where if a cache entry
          expires during a moment with high number of concurrent requests, then Edge Stack creates a
          deluge of concurrent requests to the resource when one aught to have sufficed; this allows
          the result to be returned more quickly while putting less load on the remote resource.
          However, if the response turns out to be non-cacheable, then this does effectively
          serialize requests, increasing the latency for concurrent requests.
        image: ./v2.0.5-cache-change.png

      - title: AuthService circuit breakers
        type: feature
        body: >-
          It is now possible to set the <code>circuit_breakers</code> for <code>AuthServices</code>,
          exactly the same as for <code>Mappings</code> and <code>TCPMappings</code>. This makes it
          possible to configure your <code>AuthService</code> to be able to handle more than 1024
          concurrent requests.
        docs: topics/running/services/auth-service/
        image: ./v2.0.5-auth-circuit-breaker.png

      - title: More accurate durations in the logs
        type: bugfix
        body: >-
          When Ambassador Edge Stack completes an internal request (such as fetching the JWKS
          endpoint for a <code>JWT</code> <code>Filter</code>) it logs (at the <code>info</code> log
          level) how long the request took.  Previously, the duration logged was how long it took to
          receive the response header, and did not count the time it takes to receive the entire
          response body; now it properly times the entire thing.  Additionally, it now separately
          logs the "total duration" and the "networking duration", in order to make it possible to
          identify when a request was delayed waiting for other requests to finish.

      - title: Improved validity checking for error response overrides
        type: bugfix
        body: >-
          Any token delimited by '%' is now validated agains a whitelist of valid
          Envoy command operators. Any mapping containing an <code>error_response_overrides</code>
          section with invalid command operators will be discarded.
        docs: topics/running/custom-error-responses

      - title: mappingSelector is now correctly supported in the Host CRD
        type: bugfix
        body: >-
          The <code>Host</code> CRD now correctly supports the <code>mappingSelector</code>
          element, as documented. As a transition aid, <code>selector</code> is a synonym for
          <code>mappingSelector</code>; a future version of $productName$ will remove the
          <code>selector</code> element.
        github:
          - title: '#3902'
            link: https://github.com/emissary-ingress/emissary/issues/3902
        docs: https://github.com/emissary-ingress/emissary/issues/3902
        image: ./v2.0.5-mappingselector.png

  - version: 2.0.4
    date: '2021-10-19'
    notes:
      - title: General availability!
        type: feature
        body: >-
          We're pleased to introduce $productName$ 2.0.4 for general availability! The
          2.X family introduces a number of changes to allow $productName$ to more
          gracefully handle larger installations, reduce global configuration to better
          handle multitenant or multiorganizational installations, reduce memory footprint, and
          improve performance. We welcome feedback!! Join us on
          <a href="http://a8r.io/slack">Slack</a> and let us know what you think.
        isHeadline: true
        docs: about/changes-2.x
        image: ./edge-stack-GA.png

      - title: API version getambassador.io/v3alpha1
        type: change
        body: >-
          The <code>x.getambassador.io/v3alpha1</code> API version has become the
          <code>getambassador.io/v3alpha1</code> API version. The <code>Ambassador-</code>
          prefixes from <code>x.getambassador.io/v3alpha1</code> resources have been
          removed for ease of migration. <b>Note that <code>getambassador.io/v3alpha1</code>
          is the only supported API version for 2.0.4</b> &mdash; full support for
          <code>getambassador.io/v2</code> will arrive soon in a later 2.X version.
        docs: about/changes-2.x
        image: ./v2.0.4-v3alpha1.png

      - title: Support for Kubernetes 1.22
        type: feature
        body: >-
          The <code>getambassador.io/v3alpha1</code> API version and the published chart
          and manifests have been updated to support Kubernetes 1.22. Thanks to
          <a href="https://github.com/imoisharma">Mohit Sharma</a> for contributions to
          this feature!
        docs: about/changes-2.x
        image: ./v2.0.4-k8s-1.22.png

      - title: Mappings support configuring strict or logical DNS
        type: feature
        body: >-
          You can now set <code>dns_type</code> between <code>strict_dns</code> and
          <code>logical_dns</code> in a <code>Mapping</code> to configure the Service
          Discovery Type.
        docs: topics/using/mappings/#dns-configuration-for-mappings
        image: ./v2.0.4-mapping-dns-type.png

      - title: Mappings support controlling DNS refresh with DNS TTL
        type: feature
        body: >-
          You can now set <code>respect_dns_ttl</code> to <code>true</code> to force the
          DNS refresh rate for a <code>Mapping</code> to be set to the record's TTL
          obtained from DNS resolution.
        docs: topics/using/mappings/#dns-configuration-for-mappings

      - title: Support configuring upstream buffer sizes
        type: feature
        body: >-
          You can now set <code>buffer_limit_bytes</code> in the <code>ambassador</code>
          <code>Module</code> to to change the size of the upstream read and write buffers.
          The default is 1MiB.
        docs: topics/running/ambassador/#modify-default-buffer-size

      - title: Version number reported correctly
        type: bugfix
        body: >-
          The release now shows its actual released version number, rather than
          the internal development version number.
        github:
          - title: '#3854'
            link: https://github.com/emissary-ingress/emissary/issues/3854
        docs: https://github.com/emissary-ingress/emissary/issues/3854
        image: ./v2.0.4-version.png

      - title: Large configurations work correctly with Ambassador Cloud
        type: bugfix
        body: >-
          Large configurations no longer cause $productName$ to be unable
          to communicate with Ambassador Cloud.
        github:
          - title: '#3593'
            link: https://github.com/emissary-ingress/emissary/issues/3593
        docs: https://github.com/emissary-ingress/emissary/issues/3593

      - title: Listeners correctly support l7Depth
        type: bugfix
        body: >-
          The <code>l7Depth</code> element of the <code>Listener</code> CRD is
          properly supported.
        docs: topics/running/listener#l7depth
        image: ./v2.0.4-l7depth.png

  - version: 2.0.3-ea
    date: '2021-09-16'
    notes:
      - title: Developer Preview!
        body: We're pleased to introduce $productName$ 2.0.3 as a <b>developer preview</b>. The 2.X family introduces a number of changes to allow $productName$ to more gracefully handle larger installations, reduce global configuration to better handle multitenant or multiorganizational installations, reduce memory footprint, and improve performance. We welcome feedback!! Join us on <a href="http://a8r.io/slack">Slack</a> and let us know what you think.
        type: change
        isHeadline: true
        docs: about/changes-2.x

      - title: AES_LOG_LEVEL more widely effective
        body: The environment variable <code>AES_LOG_LEVEL</code> now also sets the log level for the <code>diagd</code> logger.
        type: feature
        docs: topics/running/running/
        github:
          - title: '#3686'
            link: https://github.com/emissary-ingress/emissary/issues/3686
          - title: '#3666'
            link: https://github.com/emissary-ingress/emissary/issues/3666

      - title: AmbassadorMapping supports setting the DNS type
        body: You can now set <code>dns_type</code> in the <code>AmbassadorMapping</code> to configure how Envoy will use the DNS for the service.
        type: feature
        docs: topics/using/mappings/#using-dns_type

      - title: Building Emissary no longer requires setting DOCKER_BUILDKIT
        body: It is no longer necessary to set <code>DOCKER_BUILDKIT=0</code> when building Emissary. A future change will fully support BuildKit.
        type: bugfix
        docs: https://github.com/emissary-ingress/emissary/issues/3707
        github:
          - title: '#3707'
            link: https://github.com/emissary-ingress/emissary/issues/3707

  - version: 2.0.2-ea
    date: '2021-08-24'
    notes:
      - title: Developer Preview!
        body: We're pleased to introduce $productName$ 2.0.2 as a <b>developer preview</b>. The 2.X family introduces a number of changes to allow $productName$ to more gracefully handle larger installations, reduce global configuration to better handle multitenant or multiorganizational installations, reduce memory footprint, and improve performance. We welcome feedback!! Join us on <a href="http://a8r.io/slack">Slack</a> and let us know what you think.
        type: change
        isHeadline: true
        docs: about/changes-2.x

      - title: Envoy security updates
        type: bugfix
        body: 'Upgraded envoy to 1.17.4 to address security vulnerabilities CVE-2021-32777, CVE-2021-32778, CVE-2021-32779, and CVE-2021-32781.'
        docs: https://groups.google.com/g/envoy-announce/c/5xBpsEZZDfE?pli=1

      - title: Expose Envoy's allow_chunked_length HTTPProtocolOption
        type: feature
        body: 'You can now set <code>allow_chunked_length</code> in the Ambassador Module to configure the same value in Envoy.'
        docs: topics/running/ambassador/#content-length-headers

      - title: Envoy-configuration snapshots saved
        type: change
        body: Envoy-configuration snapshots get saved (as <code>ambex-#.json</code>) in <code>/ambassador/snapshots</code>. The number of snapshots is controlled by the <code>AMBASSADOR_AMBEX_SNAPSHOT_COUNT</code> environment variable; set it to 0 to disable. The default is 30.
        docs: topics/running/running/

  - version: 2.0.1-ea
    date: '2021-08-12'
    notes:
      - title: Developer Preview!
        body: We're pleased to introduce $productName$ 2.0.1 as a <b>developer preview</b>. The 2.X family introduces a number of changes to allow $productName$ to more gracefully handle larger installations, reduce global configuration to better handle multitenant or multiorganizational installations, reduce memory footprint, and improve performance. We welcome feedback!! Join us on <a href="http://a8r.io/slack">Slack</a> and let us know what you think.
        type: change
        isHeadline: true
        docs: about/changes-2.x

      - title: Improved Ambassador Cloud visibility
        type: feature
        body: Ambassador Agent reports sidecar process information and <code>AmbassadorMapping</code> OpenAPI documentation to Ambassador Cloud to provide more visibility into services and clusters.
        docs: /docs/cloud/latest/service-catalog/quick-start/

      - title: Configurable per-AmbassadorListener statistics prefix
        body: The optional <code>stats_prefix</code> element of the <code>AmbassadorListener</code> CRD now determines the prefix of HTTP statistics emitted for a specific <code>AmbassadorListener</code>.
        type: feature
        docs: topics/running/listener

      - title: Configurable statistics names
        body: The optional <code>stats_name</code> element of <code>AmbassadorMapping</code>, <code>AmbassadorTCPMapping</code>, <code>AuthService</code>, <code>LogService</code>, <code>RateLimitService</code>, and <code>TracingService</code> now sets the name under which cluster statistics will be logged. The default is the <code>service</code>, with non-alphanumeric characters replaced by underscores.
        type: feature
        docs: topics/running/statistics

      - title: Configurable Dev Portal fetch timeout
        type: bugfix
        body: The <code>AmbassadorMapping</code> resource can now specify <code>docs.timeout_ms</code> to set the timeout when the Dev Portal is fetching API specifications.
        docs: topics/using/dev-portal/

      - title: Dev Portal search strips HTML tags
        type: bugfix
        body: The Dev Portal will now strip HTML tags when displaying search results, showing just the actual content of the search result.
        docs: topics/using/dev-portal/

      - title: Updated klog to reduce log noise
        type: bugfix
        body: We have updated to <code>k8s.io/klog/v2</code> to track upstream and to quiet unnecessary log output.
        docs: https://github.com/emissary-ingress/emissary/issues/3603

      - title: Subsecond time resolution in logs
        type: change
        body: Logs now include subsecond time resolutions, rather than just seconds.
        docs: https://github.com/emissary-ingress/emissary/pull/3650

      - title: Configurable Envoy-configuration rate limiting
        type: change
        body: Set <code>AMBASSADOR_AMBEX_NO_RATELIMIT</code> to <code>true</code> to completely disable ratelimiting Envoy reconfiguration under memory pressure. This can help performance with the endpoint or Consul resolvers, but could make OOMkills more likely with large configurations. The default is <code>false</code>, meaning that the rate limiter is active.
        docs: topics/concepts/rate-limiting-at-the-edge/

      - title: Improved Consul certificate rotation visibility
        type: change
        body: Consul certificate-rotation logging now includes the fingerprints and validity timestamps of certificates being rotated.
        docs: howtos/consul/#consul-connector-and-encrypted-tls

      - title: Add configurable cache for OIDC replies to the JWT Filter
        type: feature
        body: >-
          The <code>maxStale</code> field is now supported in in the JWT Filter to configure how long $productname$ should cache OIDC responses for similar to the existing <code>maxStale</code> field in the OAuth2 Filter.
        docs: topics/using/filters/jwt

  - version: 2.0.0-ea
    date: '2021-06-24'
    notes:
      - title: Developer Preview!
        body: We're pleased to introduce $productName$ 2.0.0 as a <b>developer preview</b>. The 2.X family introduces a number of changes to allow $productName$ to more gracefully handle larger installations, reduce global configuration to better handle multitenant or multiorganizational installations, reduce memory footprint, and improve performance. We welcome feedback!! Join us on <a href="http://a8r.io/slack">Slack</a> and let us know what you think.
        type: change
        docs: about/changes-2.x
        isHeadline: true

      - title: Configuration API v3alpha1
        body: >-
          $productName$ 2.0.0 introduces API version <code>x.getambassador.io/v3alpha1</code> for
          configuration changes that are not backwards compatible with the 1.X family.  API versions
          <code>getambassador.io/v0</code>, <code>getambassador.io/v1</code>, and
          <code>getambassador.io/v2</code> are deprecated.  Further details are available in the <a
          href="../about/changes-2.x/#1-configuration-api-version-getambassadoriov3alpha1">Major Changes
          in 2.X</a> document.
        type: feature
        docs: about/changes-2.x/#1-configuration-api-version-getambassadoriov3alpha1
        image: ./edge-stack-2.0.0-v3alpha1.png

      - title: The AmbassadorListener Resource
        body: The new <code>AmbassadorListener</code> CRD defines where and how to listen for requests from the network, and which <code>AmbassadorHost</code> definitions should be used to process those requests. Note that the <code>AmbassadorListener</code> CRD is <b>mandatory</b> and consolidates <i>all</i> port configuration; see the <a href="../topics/running/listener"><code>AmbassadorListener</code> documentation</a> for more details.
        type: feature
        docs: topics/running/listener
        image: ./edge-stack-2.0.0-listener.png

      - title: AmbassadorMapping hostname DNS glob support
        body: >-
          Where <code>AmbassadorMapping</code>'s <code>host</code> field is either an exact match or (with <code>host_regex</code> set) a regex,
          the new <code>hostname</code> element is always a DNS glob. Use <code>hostname</code> instead of <code>host</code> for best results.
        docs: about/changes-2.x/#ambassadorhost-and-ambassadormapping-association
        type: feature

      - title: Memory usage improvements for installations with many AmbassadorHosts
        body: The behavior of the Ambassador module <code>prune_unreachable_routes</code> field is now automatic, which should reduce Envoy memory requirements for installations with many <code>AmbassadorHost</code>s
        docs: topics/running/ambassador/#prune-unreachable-routes
        image: ./edge-stack-2.0.0-prune_routes.png
        type: feature

      - title: Independent Host actions supported
        body: Each <code>AmbassadorHost</code> can specify its <code>requestPolicy.insecure.action</code> independently of any other <code>AmbassadorHost</code>, allowing for HTTP routing as flexible as HTTPS routing.
        docs: topics/running/host-crd/#secure-and-insecure-requests
        github:
          - title: '#2888'
            link: https://github.com/datawire/ambassador/issues/2888
        image: ./edge-stack-2.0.0-insecure_action_hosts.png
        type: bugfix

      - title: Correctly set Ingress resource status in all cases
        body: $productName$ 2.0.0 fixes a regression in detecting the Ambassador Kubernetes service that could cause the wrong IP or hostname to be used in Ingress statuses -- thanks, <a href="https://github.com/impl">Noah Fontes</a>!
        docs: topics/running/ingress-controller
        type: bugfix
        image: ./edge-stack-2.0.0-ingressstatus.png

      - title: Stricter mTLS enforcement
        body: $productName$ 2.0.0 fixes a bug where mTLS could use the wrong configuration when SNI and the <code>:authority</code> header didn't match
        type: bugfix

      - title: Port configuration outside AmbassadorListener has been moved to AmbassadorListener
        body: The <code>TLSContext</code> <code>redirect_cleartext_from</code> and <code>AmbassadorHost</code> <code>requestPolicy.insecure.additionalPort</code> elements are no longer supported. Use a <code>AmbassadorListener</code> for this functionality instead.
        type: change
        docs: about/changes-2.x/#tlscontext-redirect_cleartext_from-and-host-insecureadditionalport

      - title: PROXY protocol configuration has been moved to AmbassadorListener
        body: The <code>use_proxy_protocol</code> element of the Ambassador <code>Module</code> is no longer supported, as it is now part of the <code>AmbassadorListener</code> resource (and can be set per-<code>AmbassadorListener</code> rather than globally).
        type: change
        docs: about/changes-2.x/#proxy-protocol-configuration

      - title: Stricter rules for AmbassadorHost/AmbassadorMapping association
        body: An <code>AmbassadorMapping</code> will only be matched with an <code>AmbassadorHost</code> if the <code>AmbassadorMapping</code>'s <code>host</code> or the <code>AmbassadorHost</code>'s <code>selector</code> (or both) are explicitly set, and match. This change can significantly improve $productName$'s memory footprint when many <code>AmbassadorHost</code>s are involved. Further details are available in the <a href="../about/changes-2.x/#host-and-mapping-association">2.0.0 Changes</a> document.
        docs: about/changes-2.x/#host-and-mapping-association
        type: change

      - title: AmbassadorHost or Ingress now required for TLS termination
        body: An <code>AmbassadorHost</code> or <code>Ingress</code> resource is now required when terminating TLS -- simply creating a <code>TLSContext</code> is not sufficient. Further details are available in the <a href="../about/changes-2.x/#host-tlscontext-and-tls-termination"><code>AmbassadorHost</code> CRD documentation.</a>
        docs: about/changes-2.x/#host-tlscontext-and-tls-termination
        type: change
        image: ./edge-stack-2.0.0-host_crd.png

      - title: Envoy V3 APIs
        body: By default, $productName$ will configure Envoy using the V3 Envoy API. This change is mostly transparent to users, but note that Envoy V3 does not support unsafe regular expressions or, e.g., Zipkin's V1 collector protocol. Further details are available in the <a href="../about/changes-2.x">Major Changes in 2.X</a> document.
        type: change
        docs: about/changes-2.x/#envoy-v3-api-by-default

      - title: Module-based TLS no longer supported
        body: The <code>tls</code> module and the <code>tls</code> field in the Ambassador module are no longer supported. Please use <code>TLSContext</code> resources instead.
        docs: about/changes-2.x/#tls-the-ambassador-module-and-the-tls-module
        image: ./edge-stack-2.0.0-tlscontext.png
        type: change

      - title: Higher performance while generating Envoy configuration now enabled by default
        body: The environment variable <code>AMBASSADOR_FAST_RECONFIGURE</code> is now set by default, enabling the higher-performance implementation of the code that $productName$ uses to generate and validate Envoy configurations.
        docs: topics/running/scaling/#ambassador_fast_reconfigure-and-ambassador_legacy_mode-flags
        type: change

      - title: Service Preview no longer supported
        body: >-
          Service Preview and the <code>AGENT_SERVICE</code> environment variable are no longer supported.
          The Telepresence product replaces this functionality.
        docs: https://www.getambassador.io/docs/telepresence/
        type: change

      - title: edgectl no longer supported
        body: The <code>edgectl</code> CLI tool has been deprecated; please use the <code>emissary-ingress</code> helm chart instead.
        docs: topics/install/helm/
        type: change

  - version: 1.14.2
    date: '2021-09-29'
    notes:
      - title: Mappings support controlling DNS refresh with DNS TTL
        type: feature
        body: >-
          You can now set <code>respect_dns_ttl</code> in Ambassador Mappings. When true it
          configures that upstream's refresh rate to be set to resource record’s TTL
        docs: topics/using/mappings/#dns-configuration-for-mappings

      - title: Mappings support configuring strict or logical DNS
        type: feature
        body: >-
          You can now set <code>dns_type</code> in Ambassador Mappings to use Envoy's
          <code>logical_dns</code> resolution instead of the default <code>strict_dns</code>.
        docs: topics/using/mappings/#dns-configuration-for-mappings

      - title: Support configuring upstream buffer size
        type: feature
        body: >-
          You can now set <code>buffer_limit_bytes</code> in the <code>ambassador</code>
          <code>Module</code> to to change the size of the upstream read and write buffers.
          The default is 1MiB.
        docs: topics/running/ambassador/#modify-default-buffer-size

  - version: 1.14.1
    date: '2021-08-24'
    notes:
      - title: Envoy security updates
        type: change
        body: >-
          Upgraded Envoy to 1.17.4 to address security vulnerabilities CVE-2021-32777,
          CVE-2021-32778, CVE-2021-32779, and CVE-2021-32781.
        docs: https://groups.google.com/g/envoy-announce/c/5xBpsEZZDfE

  - version: 1.14.0
    date: '2021-08-19'
    notes:
      - title: Envoy upgraded to 1.17.3!
        type: change
        body: >-
          Update from Envoy 1.15 to 1.17.3
        docs: https://www.envoyproxy.io/docs/envoy/latest/version_history/version_history

      - title: Expose Envoy's allow_chunked_length HTTPProtocolOption
        type: feature
        body: >-
          You can now set <code>allow_chunked_length</code> in the Ambassador Module to configure
          the same value in Envoy.
        docs: topics/running/ambassador/#content-length-headers

      - title: Default Envoy API version is now V3
        type: change
        body: >-
          <code>AMBASSADOR_ENVOY_API_VERSION</code> now defaults to <code>V3</code>
        docs: topics/running/running/#ambassador_envoy_api_version

      - title: Subsecond time resolution in logs
        type: change
        body: Logs now include subsecond time resolutions, rather than just seconds.
        docs: https://github.com/emissary-ingress/emissary/pull/3650

  - version: 1.13.10
    date: '2021-07-28'
    notes:
      - title: Fix for CORS origins configuration on the Mapping resource
        type: bugfix
        body: >-
          Fixed a regression when specifying a comma separated string for <code>cors.origins</code>
          on the <code>Mapping</code> resource.
          ([#3609](https://github.com/emissary-ingress/emissary/issues/3609))
        docs: topics/using/cors
        image: ../images/emissary-1.13.10-cors-origin.png

      - title: New Envoy-configuration snapshots for debugging
        body: 'Envoy-configuration snapshots get saved (as <code>ambex-#.json</code>) in <code>/ambassador/snapshots</code>. The number of snapshots is controlled by the <code>AMBASSADOR_AMBEX_SNAPSHOT_COUNT</code> environment variable; set it to 0 to disable. The default is 30.'
        type: change
        docs: topics/running/environment/

      - title: Optionally remove ratelimiting for Envoy reconfiguration
        body: >-
          Set <code>AMBASSADOR_AMBEX_NO_RATELIMIT</code> to <code>true</code> to completely disable
          ratelimiting Envoy reconfiguration under memory pressure. This can help performance with
          the endpoint or Consul resolvers, but could make OOMkills more likely with large
          configurations. The default is <code>false</code>, meaning that the rate limiter is
          active.
        type: change
        docs: topics/running/environment/

      - title: Mappings support configuring the DevPortal fetch timeout
        type: bugfix
        body: >-
          The <code>Mapping</code> resource can now specify <code>docs.timeout_ms</code> to set the
          timeout when the Dev Portal is fetching API specifications.
        docs: topics/using/dev-portal
        image: ../images/edge-stack-1.13.10-docs-timeout.png

      - title: Dev Portal will strip HTML tags when displaying results
        type: bugfix
        body: >-
          The Dev Portal will now strip HTML tags when displaying search results, showing just the
          actual content of the search result.
        docs: topics/using/dev-portal

      - title: Consul certificate rotation logs more information
        type: change
        body: >-
          Consul certificate-rotation logging now includes the fingerprints and validity timestamps
          of certificates being rotated.
        docs: howtos/consul/
        image: ../images/edge-stack-1.13.10-consul-cert-log.png

  - version: 1.13.9
    date: '2021-06-30'
    notes:
      - title: Fix for TCPMappings
        body: >-
          Configuring multiple TCPMappings with the same ports (but different hosts) no longer
          generates invalid Envoy configuration.
        type: bugfix
        docs: topics/using/tcpmappings/

  - version: 1.13.8
    date: '2021-06-08'
    notes:
      - title: Fix Ambassador Cloud Service Details
        body: >-
          Ambassador Agent now accurately reports up-to-date Endpoint information to Ambassador
          Cloud
        type: bugfix
        docs: tutorials/getting-started/#3-connect-your-cluster-to-ambassador-cloud
        image: ../images/edge-stack-1.13.8-cloud-bugfix.png

      - title: Improved Argo Rollouts Experience with Ambassador Cloud
        body: >-
          Ambassador Agent reports ConfigMaps and Deployments to Ambassador Cloud to provide a
          better Argo Rollouts experience. See [Argo+Ambassador
          documentation](https://www.getambassador.io/docs/argo) for more info.
        type: feature
        docs: https://www.getambassador.io/docs/argo

  - version: 1.13.7
    date: '2021-06-03'
    notes:
      - title: JSON logging support
        body: >-
          Add AMBASSADOR_JSON_LOGGING to enable JSON for most of the Ambassador control plane. Some
          (but few) logs from gunicorn and the Kubernetes client-go package still log text.
        image: ../images/edge-stack-1.13.7-json-logging.png
        docs: topics/running/running/#log-format
        type: feature

      - title: Consul resolver bugfix with TCPMappings
        body: >-
          Fixed a bug where the Consul resolver would not actually use Consul endpoints with
          TCPMappings.
        image: ../images/edge-stack-1.13.7-tcpmapping-consul.png
        docs: topics/running/resolvers/#the-consul-resolver
        type: bugfix

      - title: Memory usage calculation improvements
        body: >-
          Ambassador now calculates its own memory usage in a way that is more similar to how the
          kernel OOMKiller tracks memory.
        image: ../images/edge-stack-1.13.7-memory.png
        docs: topics/running/scaling/#inspecting-ambassador-performance
        type: change

  - version: 1.13.6
    date: '2021-05-24'
    notes:
      - title: Quieter logs in legacy mode
        type: bugfix
        body: >-
          Fixed a regression where Ambassador snapshot data was logged at the INFO label
          when using <code>AMBASSADOR_LEGACY_MODE=true</code>.

  - version: 1.13.5
    date: '2021-05-13'
    notes:
      - title: Correctly support proper_case and preserve_external_request_id
        type: bugfix
        body: >-
          Fix a regression from 1.8.0 that prevented <code>ambassador</code> <code>Module</code>
          config keys <code>proper_case</code> and <code>preserve_external_request_id</code>
          from working correctly.
        docs: topics/running/ambassador/#header-case

      - title: Correctly support Ingress statuses in all cases
        type: bugfix
        body: >-
          Fixed a regression in detecting the Ambassador Kubernetes service that could cause the
          wrong IP or hostname to be used in Ingress statuses (thanks, [Noah
          Fontes](https://github.com/impl)!
        docs: topics/running/ingress-controller

  - version: 1.13.4
    date: '2021-05-11'
    notes:
      - title: Envoy 1.15.5
        body: >-
          Incorporate the Envoy 1.15.5 security update by adding the
          <code>reject_requests_with_escaped_slashes</code> option to the Ambassador module.
        image: ../images/edge-stack-1.13.4.png
        docs: topics/running/ambassador/#rejecting-client-requests-with-escaped-slashes
        type: security
# Don't go any further back than 1.13.4.