- 
-
- 
-
getambassador.io/v2
+ and getambassador.io/v3alpha1. If you are using any resources with
+ older API versions, you will need to upgrade them.
+Listener.Host.
+Host.
+Host.Mapping.
+Host.
+Host.TLSContext.
+Mapping.
+Mapping.
+Host.
+Listener.
+AMBASSADOR_ENVOY_API_VERSION because it no longer configurable and will have no effect.
+
+
+## 4. Zipkin HTTP_JSON_V1 support is removed
+
+Envoy removed support for the older `HTTP_JSON_V1` collector_endpoint_version. If using the `zipkin` driver with the `TracingService`,
+then you will have to update it to use `HTTP_JSON` or `HTTP_PROTO`.
diff --git a/docs/edge-stack/3.9/about/faq.md b/docs/edge-stack/3.9/about/faq.md
new file mode 100644
index 000000000..14528f9a1
--- /dev/null
+++ b/docs/edge-stack/3.9/about/faq.md
@@ -0,0 +1,88 @@
+# Frequently Asked Questions
+
+## General
+
+### Why $productName$?
+
+Kubernetes shifts application architecture for microservices, as well as the
+development workflow for a full-cycle development. $productName$ is designed for
+the Kubernetes world with:
+
+* Sophisticated traffic management capabilities (thanks to its use of [Envoy Proxy](https://www.envoyproxy.io)), such as load balancing, circuit breakers, rate limits, and automatic retries.
+* API management capabilities such as a developer portal and OpenID Connect integration for Single Sign-On.
+* A declarative, self-service management model built on Kubernetes Custom Resource Definitions, enabling GitOps-style continuous delivery workflows.
+
+We've written about [the history of $productName$](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844), [Why $productName$ In Depth](../why-ambassador), [Features and Benefits](../features-and-benefits) and about the [evolution of API Gateways](../../topics/concepts/microservices-api-gateways/).
+
+### What's the difference between $OSSproductName$ and $AESproductName$?
+
+$OSSproductName$ is a CNCF Incubating project and provides the open-source core of $AESproductName$. Originally we called $OSSproductName$ the "Ambassador API Gateway", but as the project evolved, we realized that the functionality we were building had extended far beyond an API Gateway. In particular, the $AESproductName$ is intended to provide all the functionality you need at the edge -- hence, an "edge stack." This includes an API Gateway, ingress controller, load balancer, developer portal, and more.
+
+### How is $AESproductName$ licensed?
+
+The core $OSSproductName$ is open source under the Apache Software License 2.0. The GitHub repository for the core is [https://github.com/emissary-ingress/emissary](https://github.com/emissary-ingress/emissary). Some additional features of the $AESproductName$ (e.g., Single Sign-On) are not open source and available under a proprietary license.
+
+### Can I use the add-on features for $AESproductName$ for free?
+
+Yes! For more details please see the [$productName$ Licenses page](../../topics/using/licenses).
+
+### How does $productName$ use Envoy Proxy?
+
+$productName$ uses [Envoy Proxy](https://www.envoyproxy.io) as its core proxy. Envoy is an open-source, high-performance proxy originally written by Lyft. Envoy is now part of the Cloud Native Computing Foundation.
+
+### Is $productName$ production ready?
+
+Yes. Thousands of organizations, large and small, run $productName$ in production.
+Public users include Chick-Fil-A, ADP, Microsoft, NVidia, and AppDirect, among others.
+
+### What is the performance of $productName$?
+
+There are many dimensions to performance. We published a benchmark of [$productName$ performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/). Our internal performance regressions cover many other scenarios; we expect to publish more data in the future.
+
+### What's the difference between a service mesh (such as Istio) and $productName$?
+
+Service meshes focus on routing internal traffic from service to service
+("east-west"). $productName$ focuses on traffic into your cluster ("north-south").
+While both a service mesh and $productName$ can route L7 traffic, the reality is that
+these use cases are quite different. Many users will integrate $productName$ with a
+service mesh. Production customers of $productName$ have integrated with Consul,
+Istio, and Linkerd2.
+
+## Common Configurations
+
+### How do I disable the 404 landing page?
+
+See the [Controlling the $productName$ 404 Page](../../howtos/controlling-404) how-to.
+
+### How do I disable the default Admin mappings?
+
+See the [Protecting the Diagnostics Interface](../../howtos/protecting-diag-access) how-to.
+
+## Troubleshooting
+
+### How do I get help for $productName$?
+
+We have an online [Slack community](http://a8r.io/slack) with thousands of
+users. We try to help out as often as possible, although we can't promise a
+particular response time. If you need a guaranteed SLA, we also have commercial
+contracts. [Contact sales](/contact-us/) for more information.
+
+### What do I do when I get the error `no healthy upstream`?
+
+This error means that $productName$ could not connect to your backend service.
+Start by verifying that your backend service is actually available and
+responding by sending an HTTP response directly to the pod. Then, verify that
+$productName$ is routing by deploying a test service and seeing if the mapping
+works. Then, verify that your load balancer is properly routing requests to
+$productName$. In general, verifying each network hop between your client and
+backend service is critical to finding the source of the problem.
+
+### What is the difference between the v3alpha1 and v1alpha1 CRDs?
+
+There are two different CRD versions supported by $productName$.
+The first are the `getambassador.io/v3alpha1` CRDs which were introduced with
+$productName$ 2.x. These are still supported and are not deprecated. As of $productName$ $version$, the new `gateway.getambassador.io/v1alpha1` CRDs have also been introduced.
+The `v1alpha1` CRDs have not only a new version, but also a new apigoup so that way they can
+be installed alongside the older CRDs without causing any conflicts.
+
+The `v1alpha1` CRDs are only available for the `Filter`, `FilterPolicy`, `WebApplicationFirewall`, and `WebApplicationFirewallPolicy` resources, and are the next generation of the CRDs that $productName$ will support. We are introducing them now to allow users to try them out without needing to stop using the `v3alpha1` CRDs. You can use `v1alpha1` and `v3alpha1` CRDs in the same cluster at the same time, but `FilterPolicies` are not able to reference `Filters` that do not match their CRD version.
diff --git a/docs/edge-stack/3.9/about/features-and-benefits.md b/docs/edge-stack/3.9/about/features-and-benefits.md
new file mode 100644
index 000000000..ecad16175
--- /dev/null
+++ b/docs/edge-stack/3.9/about/features-and-benefits.md
@@ -0,0 +1,39 @@
+# Features and benefits
+
+In cloud-native organizations, developers frequently take on responsibility for the full development lifecycle of a service, from development to QA to operations. $productName$ was specifically designed for these organizations where developers have operational responsibility for their service(s).
+
+As such, the $productName$ is designed to be used by both developers and operators.
+
+## Self-Service via Kubernetes Annotations
+
+$productName$ is built from the start to support _self-service_ deployments -- a developer working on a new service doesn't have to go to Operations to get their service added to the mesh, they can do it themselves in a matter of seconds. Likewise, a developer can remove their service from the mesh, or merge services, or separate services, as needed, at their convenience. All of these operations are performed via Kubernetes resources or annotations, so they can easily integrate with your existing development workflow.
+
+## Flexible canary deployments
+
+Canary deployments are an essential component of cloud-native development workflows. In a canary deployment, a small percentage of production traffic is routed to a new version of a service to test it under real-world conditions. $productName$ allows developers to easily control and manage the amount of traffic routed to a given service through annotations. [This tutorial](https://www.datawire.io/faster/canary-workflow/) covers a complete canary workflow using the $productName$.
+
+## Kubernetes-native architecture
+
+$productName$ relies entirely on Kubernetes for reliability, availability, and scalability. For example, $productName$ persists all state in Kubernetes, instead of requiring a separate database. Scaling the $productName$ is as simple as changing the replicas in your deployment, or using a [horizontal pod autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
+
+$productName$ uses [Envoy](https://www.envoyproxy.io) for all traffic routing and proxying. Envoy is a modern L7 proxy that is used in production at companies including Lyft, Apple, Google, and Stripe.
+
+## gRPC and HTTP/2 support
+
+$productName$ fully supports gRPC and HTTP/2 routing, thanks to Envoy's extensive capabilities in this area. See [gRPC and $productName$](../../howtos/grpc) for more information.
+
+## Istio Integration
+
+$productName$ integrates with the [Istio](https://istio.io) service mesh as the edge proxy. In this configuration, $productName$ routes external traffic to the internal Istio service mesh. See [Istio and $productName$](../../howtos/istio) for details.
+
+## Authentication
+
+$productName$ supports authenticating incoming requests with a custom authentication service, OAuth/OpenID Connect, or JWT. When configured, the $productName$ will check with a third party authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/using/filters/).
+
+## Rate limiting
+
+$productName$ supports rate limiting incoming requests. When configured, the $productName$ will check with a third party rate limit service prior to routing an incoming request. For more information, see the [rate limiting guide](../../topics/using/rate-limits/).
+
+## Integrated UI
+
+$productName$ includes a diagnostics service so that you can quickly debug issues associated with configuring the $productName$. For more information, see [running $productName$ in Production](../../topics/running).
diff --git a/docs/edge-stack/3.9/about/known-issues.md b/docs/edge-stack/3.9/about/known-issues.md
new file mode 100644
index 000000000..4a5c45f5b
--- /dev/null
+++ b/docs/edge-stack/3.9/about/known-issues.md
@@ -0,0 +1,20 @@
+import Alert from '@material-ui/lab/Alert';
+
+Known Issues in $productName$
+=============================
+
+## 2.2.1
+
+- TLS certificates using elliptic curves were incorrectly flagged as invalid. This issue is
+ corrected in $productName$ 2.2.2.
+
+## 2.2.0
+
+- If $productName$'s Pods start before Redis is responding, it may be necessary to restart
+ $productName$ for rate limiting to function correctly.
+
+- When using the ACME client provided with $productName$, a delayed ACME response can
+ prevent the `Host` using ACME from becoming active.
+
+ - Workaround: Make sure you have a wildcard `Host` that does not use ACME. The insecure routing
+ action doesn't matter: it's fine for this `Host` to redirect or even reject insecure requests.
diff --git a/docs/edge-stack/3.9/about/why-ambassador.md b/docs/edge-stack/3.9/about/why-ambassador.md
new file mode 100644
index 000000000..f16def3a1
--- /dev/null
+++ b/docs/edge-stack/3.9/about/why-ambassador.md
@@ -0,0 +1,54 @@
+# Why $productName$?
+
+$productName$ gives platform engineers a comprehensive, self-service edge stack for managing the boundary between end-users and Kubernetes. Built on the [Envoy Proxy](https://www.envoyproxy.io) and fully Kubernetes-native, $productName$ is made to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. A true edge stack, $productName$ can also be used to handle the functions of an API Gateway, a Kubernetes ingress controller, and a layer 7 load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
+
+## How Does $productName$ work?
+
+$productName$ is a Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on the open core of $OSSproductName$ and the [Envoy Proxy](https://www.envoyproxy.io). $productName$ is built from the ground up to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. $productName$ can also be used to handle the functions of a Kubernetes ingress controller and load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
+
+## Cloud-native applications today
+
+Traditional cloud applications were built using a monolithic approach. These applications were designed, coded, and deployed as a single unit. Today's cloud-native applications, by contrast, consist of many individual (micro)services. This results in an architecture that is:
+
+* __Heterogeneous__: Services are implemented using multiple (polyglot) languages, they are designed using multiple architecture styles, and they communicate with each other over multiple protocols.
+* __Dynamic__: Services are frequently updated and released (often without coordination), which results in a constantly-changing application.
+* __Decentralized__: Services are managed by independent product-focused teams, with different development workflows and release cadences.
+
+### Heterogeneous services
+
+$productName$ is commonly used to route traffic to a wide variety of services. It supports:
+
+* configuration on a *per-service* basis, enabling fine-grained control of timeouts, rate limiting, authentication policies, and more.
+* a wide range of L7 protocols natively, including HTTP, HTTP/2, gRPC, gRPC-Web, and WebSockets.
+* Can route raw TCP for services that use protocols not directly supported by $productName$.
+
+### Dynamic services
+
+Service updates result in a constantly changing application. The dynamic nature of cloud-native applications introduces new challenges around configuration updates, release, and testing. $productName$:
+
+* Enables [progressive delivery](../../topics/concepts/progressive-delivery), with support for canary routing and traffic shadowing.
+* Exposes high-resolution observability metrics, providing insight into service behavior.
+* Uses a zero downtime configuration architecture, so configuration changes have no end-user impact.
+
+### Decentralized workflows
+
+Independent teams can create their own workflows for developing and releasing functionality that are optimized for their specific service(s). With $productName$, teams can:
+
+* Leverage a [declarative configuration model](../../topics/concepts/gitops-continuous-delivery), making it easy to understand the canonical configuration and implement GitOps-style best practices.
+* Independently configure different aspects of $productName$, eliminating the need to request configuration changes through a centralized operations team.
+
+## $productName$ is engineered for Kubernetes
+
+$productName$ takes full advantage of Kubernetes and Envoy Proxy.
+
+* All of the state required for $productName$ is stored directly in Kubernetes, eliminating the need for an additional database.
+* The $productName$ team has added extensive engineering efforts and integration testing to ensure optimal performance and scale of Envoy and Kubernetes.
+
+## For more information
+
+[Deploy $productName$ today](../../tutorials/getting-started) and join the community [Slack Channel](http://a8r.io/slack).
+
+Interested in learning more?
+
+* [Why did we start building $productName$?](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844)
+* [$productName$ Architecture overview](../../topics/concepts/architecture)
diff --git a/docs/edge-stack/3.9/aes-pages.yml b/docs/edge-stack/3.9/aes-pages.yml
new file mode 100644
index 000000000..bd03e5c39
--- /dev/null
+++ b/docs/edge-stack/3.9/aes-pages.yml
@@ -0,0 +1,24 @@
+# AES pages should be represented in a yaml array with the pathnames as the value
+# Ex:
+# - /docs
+# - /reference
+#
+
+/topics/using/filters/
+/topics/using/filters/oauth2
+/topics/using/filters/jwt
+/topics/using/filters/external
+/topics/using/filters/plugin
+/topics/using/edgectl/
+/topics/using/edgectl/edge-control
+/topics/using/edgectl/edge-control-in-ci
+/topics/using/edgectl/service-preview-install
+/topics/using/edgectl/service-preview-reference
+/topics/using/edgectl/service-preview-tutorial
+/topics/using/dev-portal
+/topics/using/edge-policy-console
+/topics/using/rate-limits/rate-limits/
+/topics/running/aes-redis
+/topics/running/aes-extensions/
+/topics/running/aes-extensions/authentication
+/topics/running/aes-extensions/ratelimit
diff --git a/docs/edge-stack/3.9/api-gateway-pages.yml b/docs/edge-stack/3.9/api-gateway-pages.yml
new file mode 100644
index 000000000..b9010fdbc
--- /dev/null
+++ b/docs/edge-stack/3.9/api-gateway-pages.yml
@@ -0,0 +1,72 @@
+# API Gateway pages should be represented in a yaml array with the pathnames as the value
+# Ex:
+# - /docs
+# - /reference
+#
+- /docs/dev-guide/canary-release-concepts
+- /docs/dev-guide/test-in-prod
+- /docs/guides/
+- /reference/add_request_headers
+- /reference/add_response_headers
+- /reference/ambassador-with-aws
+- /reference/canary
+- /reference/circuit-breakers
+- /reference/configuration
+- /reference/core/ambassador
+- /reference/core/crds
+- /reference/core/ingress-controller
+- /reference/core/load-balancer
+- /reference/core/resolvers
+- /reference/core/tls
+- /reference/cors
+- /reference/diagnostics
+- /reference/gzip
+- /reference/headers
+- /reference/host
+- /reference/host-crd
+- /reference/ambassadormappings
+- /reference/modules
+- /reference/prefix_regex
+- /reference/rate-limits
+- /reference/redirects
+- /reference/remove_request_headers
+- /reference/remove_response_headers
+- /reference/retries
+- /reference/rewrites
+- /reference/running
+- /reference/services/auth-service
+- /reference/services/log-service
+- /reference/services/rate-limit-service
+- /reference/services/services
+- /reference/services/tracing-service
+- /reference/shadowing
+- /reference/statistics
+- /reference/tcpmappings
+- /reference/timeouts
+- /reference/tls/cleartext-redirection
+- /reference/tls/client-cert-validation
+- /reference/tls/mtls
+- /reference/tls/origination
+- /user-guide/auth-tutorial
+- /user-guide/bare-metal
+- /user-guide/cd-declarative-gitops
+- /user-guide/cert-manager
+- /user-guide/consul
+- /user-guide/early-access
+- /user-guide/gitops-ambassador
+- /user-guide/grpc
+- /user-guide/helm
+- /user-guide/install-ambassador-oss
+- /user-guide/knative
+- /user-guide/linkerd2
+- /user-guide/monitoring
+- /user-guide/rate-limiting
+- /user-guide/rate-limiting-tutorial
+- /user-guide/security
+- /user-guide/sni
+- /user-guide/tls-termination
+- /user-guide/tracing-tutorial
+- /user-guide/tracing-tutorial-datadog
+- /user-guide/tracing-tutorial-zipkin
+- /user-guide/websockets-ambassador
+- /user-guide/with-istio
diff --git a/docs/edge-stack/3.9/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md b/docs/edge-stack/3.9/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md
new file mode 100644
index 000000000..2e99bc239
--- /dev/null
+++ b/docs/edge-stack/3.9/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md
@@ -0,0 +1,74 @@
+
+import Alert from '@material-ui/lab/Alert';
+
+# The **APIKey Filter** Type (v1alpha1)
+
+The `APIKey Filter` validates API Keys present in HTTP headers. The list of authorized API Keys is defined directly in a Secret.
+If an incoming request does not have the header specified by the `APIKey Filter` or it does not contain one of the key values
+configured by the `Filter` then the request is denied. For more information about how requests are matched to `Filter` resources and the order in which `Filters` are executed, please refer to the [FilterPolicy Resource][] documentation.
+
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+Filter is fil, so you can get filters using kubectl get filter or kubectl get fil.
+v1alpha1 FilterPolicies can only be reference v1alpha1 Filters.
+WebApplicationFirewall resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+WebApplicationFirewallPolicy resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 FilterPolicies can only be reference v3alpha1 Filters.
+v2 or later for the apiVersion in the Mapping resource. Previous versions do not support labels.
+ 
What's next?
+
+* Get started with authentication by [installing $AESproductName$](../../tutorials/getting-started/).
+
+* For more details see the [`External` filter](../../topics/using/filters) documentation.
diff --git a/docs/edge-stack/3.9/howtos/external-dns.md b/docs/edge-stack/3.9/howtos/external-dns.md
new file mode 100644
index 000000000..fd75f1b47
--- /dev/null
+++ b/docs/edge-stack/3.9/howtos/external-dns.md
@@ -0,0 +1,126 @@
+import Alert from '@material-ui/lab/Alert';
+
+# ExternalDNS with $productName$
+
+[ExternalDNS](https://github.com/kubernetes-sigs/external-dns) configures your existing DNS provider to make Kubernetes resources discoverable via public DNS servers by getting resources from the Kubernetes API to create a list of DNS records.
+
+
+## Getting started
+
+### Prerequisites
+
+Before you begin, review [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider has its own required steps, as well as annotations, arguments, and permissions needed for the following configuration.
+
+
+### Installation
+
+Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` is necessary for the ExternalDNS deployment to support compatibility with $productName$ and allow ExternalDNS to get hostnames from $productName$'s `Hosts`.
+
+The following configuration is an example configuring $productName$ - ExternalDNS integration with [AWS Route53](https://aws.amazon.com/route53/) as the DNS provider. Refer to the [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) for annotations and arguments for your DNS Provider.
+
+
+1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it:
+
+ apiGroups include "getambassador.io" following "networking.k8s.io", and that the resources include "hosts" after "ingresses".
+ istio-certs cannot be changed.
+ Mapping's service
+ element, or set up the Kubernetes Service resource for your upstream service to map port
+ 443. If you don't do one of these, connections to your upstream will hang — see the
+ "Configure Service Ports" section below for more information.
+
+
+The behavior of your service will not seem to change, even though mTLS is active:
+
+ ```console
+ $ curl -k https://{{AMBASSADOR_HOST}}/backend/
+
+ {
+ "server": "bewitched-acai-5jq7q81r",
+ "quote": "A late night does not make any sense.",
+ "time": "2020-06-02T10:48:45.211178139Z"
+ }
+ ```
+
+This request first went to $productName$, which routed it over an mTLS connection to the quote service in the
+default namespace. That connection was intercepted by the `istio-proxy` which authenticated the request as
+being from $productName$, exported various metrics, and finally forwarded it on to the actual quote service.
+
+### Configure Service Ports
+
+When mTLS is active, Istio makes TLS connections to your services. Since Istio handles the TLS protocol for
+you, you don't need to modify your services — however, the TLS connection will still use port 443
+if you don't configure your `Mapping`s to _explicitly_ use port 80.
+
+If your upstream service was not written to use TLS, its `Service` resource may only map port 80. If Istio
+attempts a TLS connection on port 443 when port 443 is not defined by the `Service` resource, the connection
+will hang _even though the Istio sidecar is active_, because Kubernetes itself doesn't know how to handle
+the connection to port 443.
+
+As shown above, one simple way to deal with this situation is to explicitly specify port 80 in the `Mapping`'s
+`service`:
+
+ ```yaml
+ service: quote:80 # Be explicit about port 80.
+ ```
+
+Another way is to set up your Kubernetes `Service` to map both port 80 and port 443. For example, the
+Quote deployment (which listens on port 8080 in its pod) might use a `Service` like this:
+
+ ```yaml
+ apiVersion: v1
+ kind: Service
+ metadata:
+ name: quote
+ spec:
+ type: ClusterIP
+ selector:
+ app: quote
+ ports:
+ - name: http
+ port: 80
+ protocol: TCP
+ targetPort: 8080
+ - name: https
+ port: 443
+ protocol: TCP
+ targetPort: 8080
+ ```
+
+Note that ports 80 and 443 are both mapped to `targetPort` 8080, where the service is actually listening.
+This permits Istio routing to work whether mTLS is active or not.
+
+## Enable Strict mTLS
+
+Istio defaults to _permissive_ mTLS, where mTLS is allowed between services, but not required. Configuring
+[_strict_ mTLS](https://istio.io/docs/tasks/security/authentication/authn-policy/#globally-enabling-istio-mutual-tls-in-strict-mode) requires all connections within the cluster be encrypted. To switch Istio to use strict mTLS,
+apply a `PeerAuthentication` resource in each namespace that should operate in strict mode:
+
+ ```yaml
+ $ kubectl apply -f - <WebApplicationFirewall and WebApplicationFirewall resources, check their statuses to make sure that they were not rejected due to any configuration errors.
+ gateway.getambassador.io/v1alpha1. It is NOT backwards compatible with getambassador.io/v3alpha1 Filter and FilterPolicy resources. These are the next generation of CRD's that you can
+ progressively adopt over time. They provide stronger typings so that
+ feedback is given at apply time rather than runtime.
+ docs: custom-resources/gateway-getambassador/v1alpha1/filter
+
+ - title: getambassador.io/v3alpha1 Filter & FilterPolicy statuses
+ type: feature
+ body: >-
+ Filter and FilterPolicy resources for the getambassador.io/v3alpha1 version will now provide statuses when they are "Ready". If there are
+ configuration errors they will provide an error message with details about the configuration issues. This will help troubleshoot configuration issues.
+
+ docs: custom-resources/getambassador/v3alpha1/filter
+
+ - title: Upgrade to Envoy 1.27.2
+ type: feature
+ body: >-
+ This upgrades $productName$ to be built on Envoy v1.27.2 which provides security, performance and feature enhancements. You can read more about them here: Envoy Proxy 1.27.2 Release Notes
+ docs: https://www.envoyproxy.io/docs/envoy/v1.27.2/version_history/version_history
+
+ - title: Added support for RESOURCE_EXHAUSTED responses to grpc clients when rate limited
+ type: feature
+ body: >-
+ By default, $productName$ will return an UNAVAILABLE code when a request using gRPC is rate limited. The RateLimitService resource now exposes a new grpc.use_resource_exhausted_code field that when set to true, $productName$ will return a RESOURCE_EXHAUSTED gRPC code instead. Thanks to Jerome Froelich for contributing this feature!
+ docs: topics/using/running/aes-extensions/ratelimit
+
+ - title: Added support for setting specific Envoy runtime flags in the Module
+ type: feature
+ body: >-
+ Envoy runtime fields that were provided to mitigate the recent HTTP/2 rapid reset
+ vulnerability can now be configured via the Module resource so the configuration will
+ persist between restarts. This configuration is added to the Envoy bootstrap config, so
+ restarting Emissary is necessary after changing these fields for the configuration to take effect.
+ docs: topics/running/ambassador/#set-envoy-runtime-flags
+
+ - title: Update APIExt minimum TLS version
+ type: change
+ body: >-
+ APIExt would previously allow for TLS 1.0 connections. We have updated it to now only use a minimum TLS version of 1.3 to resolve security concerns.
+ docs: https://www.tenable.com/plugins/nessus/104743
+
+ - title: Shipped Helm chart v8.9.0
+ type: change
+ body: >-
+ - Update default image to $productName$ v3.9.0. mappingSelector 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 v3alpha1 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 v3alpha1 Mappings. For users who may have this issue, please
+ be sure to re-apply any v3alpha1 Mappings in order to update the stored v2 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. ExternalFilter now supports configuring a CA certificate and/or client certificate via the new tlsConfig 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 insteadOfRedirect.filters 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 onDeny=continue 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: Envoy Proxy 1.25.4 Release Notes
+ 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. nodeSelector, tolerations and affinity on the Ambassador Agent. Thanks to Philip Panyukov. KubernetesEndpointResolver & ConsulResolver apiVersions to getambassador.io/v3alpha1
+
+ 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.authService 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 Module resource fails validation when setting the ambassador_id after upgrading to getambassador.io/v3alpha1.TracingService.spec.driver=opentelemetry to export traces in the otlp format./ready 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).AMBASSADOR_READY_PORT and enable access log using AMBASSADOR_READY_LOG 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.Host.hostname=example.com:8500). 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.ExternalFilter to communicate using gRPC with TLS would fail due to $productName$ trying to connect via cleartext. This has been fixed so that setting ExternalFilter.spec.tls=true $productName$ will talk to the external filter using TLS. startupProbes on the $productName$ deployment.podSecurityPolicy 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:TracingService. The recommended upgrade path is to leverage a supported Tracing driver such as Zipkin and use the Open Telemetry Collector to collect and forward Observabity data to LightStep. A guide for this can be found here: Distributed Tracing with Open Telemetry and LightStep.span is named. Prior to Envoy 1.24 it would always set the span name to the cluster.name. The expected behavior from Envoy was that if provided an alt_stat_name then use it else fallback to cluster.name.
+
+ 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 getambassador.io/v1 apiVersion has been re-introduced, in order to facilitate smoother migrations from $productName$ 1.y. Previously, in order to make migrations possible, an "unserved" v1 version was declared to Kubernetes, but was unsupported by $productName$. That unserved v1 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 v1 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 Mapping. 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:AMBASSADOR_HEALTHCHECK_BIND_ADDRESS: The address to bind the healthcheck server to.AMBASSADOR_HEALTHCHECK_BIND_PORT: The port to bind the healthcheck server to.AMBASSADOR_HEALTHCHECK_IP_FAMILY: The IP family to use for the healthcheck server.clientSessionMaxIdle, 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 AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED 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 Filter 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 proto: http. Now, adding supported tracing headers (b3, etc...) to the spec.allowed_request_headers 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 postLogoutRedirectURI to your Oauth2 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 https:{{host}}/.ambassador/oauth2/post-logout-redirect. Upon logout
+ $productName$ will redirect to the custom URI which will then redirect to the URI you have defined in postLogoutRedirectURI.
+ docs: topics/using/filters/oauth2
+
+ - title: Add support for Host resources using secrets from different namespaces
+ type: feature
+ body: >-
+ Previously the Host resource could only use secrets that are in the namespace as the
+ Host. The tlsSecret field in the Host has a new subfield namespace 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 AMBASSADOR_EDS_BYPASS to true to bypass EDS handling of endpoints and have endpoints be
+ inserted to clusters manually. This can help resolve with 503 UH caused by certification rotation relating to
+ a delay between EDS + CDS. The default is false.
+ docs: topics/running/environment/#ambassador_eds_bypass
+
+ - title: Add support for config change batch window before reconfiguring Envoy
+ type: feature
+ body: >-
+ The AMBASSADOR_RECONFIG_MAX_DELAY 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 custom_tags in the
+ TracingService. Trace tags can be set based on
+ literal values, environment variables, or request headers. The existing tag_headers field is now deperacated. If both tag_headers and custom_tags are set then tag_headers will be ignored.
+ (Thanks to Paul!)
+ 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
+ RateLimitService resource now exposes the
+ failure_mode_deny
+ option. Set failure_mode_deny: true, 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 Hosts are associated with Mappings and how Listeners are associated with Hosts. There was a bug with label
+ selectors that was causing resources that configure a selector 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 all labels required by
+ their selector are present. This brings the mappingSelector/selector fields in-line with how label selectors are used
+ in Kubernetes. To avoid unexpected behavior after the upgrade, add all labels that Hosts/Listeners have in their
+ mappingSelector/selector to Mappings/Hosts you want to associate with them. You can opt-out of the new behavior
+ by setting the environment variable DISABLE_STRICT_LABEL_SELECTORS to "true" (default: "false").
+ (Thanks to Filip Herceg and Joe Andaverde!).
+ 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 stats_name for the TracingService, RateLimitService
+ or the AuthService would have no affect because it was not being properly passed to the Envoy cluster
+ config. This has been fixed and the alt_stats_name field in the cluster config is now set correctly.
+ (Thanks to Paul!).
+
+ - title: Diagnostics stats properly handles parsing envoy metrics with colons
+ type: bugfix
+ body: >-
+ If a Host or TLSContext contained a hostname with a : when using the
+ diagnostics endpoints ambassador/v0/diagd 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 TCPMapping that uses SNI,
+ instead of using the hostname glob in the TCPMapping, uses the hostname glob
+ in the Host 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 TCPMapping that terminates TLS
+ must have a corresponding Host that it can take the TLS configuration from.
+ This was semi-intentional, but didn't make much sense. You can now use a
+ TLSContext without a Hostas in $productName$ 1.y releases, or a
+ Host with or without a TLSContext 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
+ TCPMapping cannot be used on the same port that HTTP is served on, even if
+ TLS+SNI would make this possible. $productName$ now allows TCPMappings to be
+ used on the same Listener port as HTTP Hosts, as long as that
+ Listener 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 Filter has been added to support validating APIKey's on incoming requests.The new APIKeyFilter when applied with a FilterPolicy will check to
+ see if the incoming requests has a valid API Key in the request header. $productName$ uses Kubernetes Secret'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 APIKeyFilter.
+ - 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 AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED=true to enable the experimental feature. Most of the standard Redis configuration fields (e.g.REDIS_*) can be used with the driver.
+ However, due to the drivers better connection handling the new driver no longer supports setting REDIS_SURGE_LIMIT_INTERVAL, REDIS_SURGE_LIMIT_AFTER, REDIS_SURGE_POOL_SIZE, REDIS_SURGE_POOL_DRAIN_INTERVAL and these will be ignored.
+
+ Note: Other $productName$ features such as the RateLimitService 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 protocol_version field is not set or set to an invalid value then it will automatically get upgraded protocol_version: v3.
+
+ This matches the existing behavior that was introduced in $productName$ v3.0.0 for the AuthService. For new installs a valid RateLimitService 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 .yaml files, the Module resource enables serving remote client requests to the :8877/ambassador/v0/diag/ 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 (/debug/pprof/profile) and tracing (/debug/pprof/trace). Also add additional endpoints serving the command line running (/debug/pprof/cmdline) and program counters (/debug/pprof/symbol) for the sake of completeness.
+ - title: Correct cookies for mixed HTTP/HTTPS OAuth2 origins
+ type: bugfix
+ body: >-
+ When an OAuth2 filter sets cookies for a protectedOrigin, it should set a cookie's "Secure" flag to true for https:// origins and false for http:// 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 OAuth2 filter with multiple protectedOrigins 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 OAuth2 filter's known endpoints /.ambassador/oauth2/logout and /.ambassador/oauth2/multicookie 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 404 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: Envoy Proxy 1.22.0 Release Notes
+
+ 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:
+
+ - 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 LogServices and External Filters are working properly by setting protocol_version: "v3".
+
+ If protocol_version is not specified in 3.Y, the default value of v2 will cause an error to be posted and a static response will be returned. Therefore, you must set it to protocol_version: v3. If upgrading from a previous version, you will want to set it to v3 and ensure it is working before upgrading to Emissary-ingress 3.Y. The default value for protocol_version remains v2 in the getambassador.io/v3alpha1 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 443 because the alt-svc 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 Host or TLSContext contained a hostname with a : then when using the
+ diagnostics endpoints ambassador/v0/diagd 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 Host or TLSContext contained a hostname with a : then when using the diagnostics endpoints ambassador/v0/diagd 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 Host resource could only use secrets that are in the namespace as the
+ Host. The tlsSecret field in the Host has a new subfield namespace 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 AMBASSADOR_EDS_BYPASS to true to bypass EDS handling of endpoints and have endpoints be
+ inserted to clusters manually. This can help resolve with 503 UH caused by certification rotation relating to
+ a delay between EDS + CDS. The default is false.
+ 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 stats_name for the TracingService, RateLimitService
+ or the AuthService would have no affect because it was not being properly passed to the Envoy cluster
+ config. This has been fixed and the alt_stats_name field in the cluster config is now set correctly.
+ (Thanks to Paul!)
+
+ - title: Diagnostics stats properly handles parsing envoy metrics with colons
+ type: bugfix
+ body: >-
+ If a Host or TLSContext contained a hostname with a : when using the
+ diagnostics endpoints ambassador/v0/diagd 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 TCPMapping that uses SNI,
+ instead of using the hostname glob in the TCPMapping, uses the hostname glob
+ in the Host 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 TCPMapping that terminates TLS
+ must have a corresponding Host that it can take the TLS configuration from.
+ This was semi-intentional, but didn't make much sense. You can now use a
+ TLSContext without a Hostas in $productName$ 1.y releases, or a
+ Host with or without a TLSContext 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
+ TCPMapping cannot be used on the same port that HTTP is served on, even if
+ TLS+SNI would make this possible. $productName$ now allows TCPMappings to be
+ used on the same Listener port as HTTP Hosts, as long as that
+ Listener 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 OAuth2 filter sets cookies for a protectedOrigin, it
+ should set a cookie's "Secure" flag to true for https:// origins and false
+ for http:// 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 OAuth2 filter with multiple protectedOrigins 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 OAuth2 filter's known endpoints /.ambassador/oauth2/logout
+ and /.ambassador/oauth2/multicookie 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 zipkin
+ 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 does not support internal
+ redirects, 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 gdbm, pip, smtplib, and sqlite packages, as they are unused.
+
+ - title: CORS now happens before auth
+ type: bugfix
+ body: >-
+ When CORS is specified (either in a Mapping or in the Ambassador
+ Module), 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 Mappings that have the same
+ metadata.name 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 Mappings 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 TracingService to specify
+ collector_endpoint_version: HTTP_JSON_V1 when using xDS v3 to configure Envoy
+ (which has been the default since $productName$ 1.14.0). The HTTP_JSON_V1
+ value configures Envoy to speak to Zipkin using Zipkin's old API-v1, while the
+ HTTP_JSON value configures Envoy to speak to Zipkin using Zipkin's new
+ API-v2. In previous versions of $productName$ it was only possible to use
+ HTTP_JSON_V1 when explicitly setting the
+ AMBASSADOR_ENVOY_API_VERSION=V2 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 AuthService 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 protocol_version field on the External Filter is explicitly set to v3.
+ docs: topics/using/filters/external
+
+ - title: Allow setting propagation modes for Lightstep tracing
+ type: feature
+ body: >-
+ It is now possible to set propagation_modes in the
+ TracingService config when using lightstep as the driver.
+ (Thanks to Paul!)
+ 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 Envoy's Certificate Revocation lists.
+ 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 LogService would always have $productName$ communicate with the
+ external log service using the envoy.service.accesslog.v2.AccessLogService
+ API. It is now possible for the LogService to specify
+ protocol_version: v3 to use the newer
+ envoy.service.accesslog.v3.AccessLogService API instead. This functionality
+ is not available if you set the AMBASSADOR_ENVOY_API_VERSION=V2 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
+ AMBASSADOR_FORCE_SECRET_VALIDATION=true 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 AMBASSADOR_ENVOY_API_VERSION 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 AMBASSADOR_ENVOY_API_VERSION 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
+ AGENT_CONFIG_RESOURCE_NAME 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 ambassador_log_level{label="debug"}
+ 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 Fabrice!)
+ 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 preserve_servers in Ambassador Edge Stack's
+ DevPortal 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 AMBASSADOR_ENVOY_API_VERSION 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
+ clientAuthentication.method=jwtAssertion 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 ifRequestHeader selector (in a
+ FilterPolicy, OAuth2 Filter useSessionCookies, or OAuth2 Filter
+ insteadOfRedirect) without a value or valueRegex
+ would erroneously behave as if valueRegex='^$', rather than performing a
+ simple presence check.
+ docs: custom-resources/getambassador/v3alpha1/filterpolicy
+
+ - title: Fix support for for v2 Mappings with CORS
+ type: bugfix
+ body: >-
+ Ambassador Edge Stack 2.1.1 generated invalid Envoy configuration for
+ getambassador.io/v2 Mappings that set
+ spec.cors.origins to a string rather than a list of strings; this has been
+ fixed, and these Mappings 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 weight of Mapping 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 Mapping that is not part of a canary group, but that has a
+ weight less than 100, will be correctly configured to receive all
+ traffic as if the weight 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 rewrite: "" in a Mapping 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 Mapping that uses the host_redirect field is now properly discovered and used. Thanks
+ to Gabriel Féron 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: >-
+ Mappings with DNS wildcard hostname will now be correctly
+ matched with Hosts. Previously, the case where both the Host
+ and the Mapping 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 ambassador Module sets a global default for
+ add_request_headers, add_response_headers,
+ remove_request_headers, or remove_response_headers, it is often
+ desirable to be able to turn off that setting locally for a specific Mapping.
+ For several releases this has not been possible for Mappings 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 Mapping
+ spec.error_response_overrides body.text_format to an empty
+ string or body.json_format 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 getambassador.io/config 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: >-
+ Ambassador Edge Stack 2.1.1 is not recommended; upgrade to 2.1.2 instead.
+
+ - 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 AMBASSADOR_ENVOY_API_VERSION 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 Filters,
+ FilterPolicies, and RateLimits that were created as
+ v3alpha1 (but correctly paid attention to them if they were created as
+ v2 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: >-
+ Ambassador Edge Stack 2.1.0 is not recommended; upgrade to 2.1.2 instead.
+
+ - 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 AMBASSADOR_ENVOY_API_VERSION 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 getambassador.io/v2 CRDs, to simplify migration from $productName$
+ 1.X. Note: it is important to read the migration
+ documentation 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 (Filter, FilterPolicy, and RateLimit)
+ will now be validated for correct syntax by Kubernetes itself. This means that kubectl apply
+ 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
+ Mappings had the same prefix ("canary"ing multiple
+ Mappings 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 JWT Filter), 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 circuit_breakers for AuthServices,
+ exactly the same as for Mappings and TCPMappings. This makes it
+ possible to configure your AuthService 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 JWT Filter) it logs (at the info 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 error_response_overrides
+ 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 Host CRD now correctly supports the mappingSelector
+ element, as documented. As a transition aid, selector is a synonym for
+ mappingSelector; a future version of $productName$ will remove the
+ selector 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
+ Slack 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 x.getambassador.io/v3alpha1 API version has become the
+ getambassador.io/v3alpha1 API version. The Ambassador-
+ prefixes from x.getambassador.io/v3alpha1 resources have been
+ removed for ease of migration. Note that getambassador.io/v3alpha1
+ is the only supported API version for 2.0.4 — full support for
+ getambassador.io/v2 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 getambassador.io/v3alpha1 API version and the published chart
+ and manifests have been updated to support Kubernetes 1.22. Thanks to
+ Mohit Sharma 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 dns_type between strict_dns and
+ logical_dns in a Mapping 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 respect_dns_ttl to true to force the
+ DNS refresh rate for a Mapping 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 buffer_limit_bytes in the ambassador
+ Module 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 l7Depth element of the Listener 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 developer preview. 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 Slack 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 AES_LOG_LEVEL now also sets the log level for the diagd 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 dns_type in the AmbassadorMapping 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 DOCKER_BUILDKIT=0 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 developer preview. 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 Slack 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 allow_chunked_length 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 ambex-#.json) in /ambassador/snapshots. The number of snapshots is controlled by the AMBASSADOR_AMBEX_SNAPSHOT_COUNT 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 developer preview. 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 Slack 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 AmbassadorMapping 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 stats_prefix element of the AmbassadorListener CRD now determines the prefix of HTTP statistics emitted for a specific AmbassadorListener.
+ type: feature
+ docs: topics/running/listener
+
+ - title: Configurable statistics names
+ body: The optional stats_name element of AmbassadorMapping, AmbassadorTCPMapping, AuthService, LogService, RateLimitService, and TracingService now sets the name under which cluster statistics will be logged. The default is the service, with non-alphanumeric characters replaced by underscores.
+ type: feature
+ docs: topics/running/statistics
+
+ - title: Configurable Dev Portal fetch timeout
+ type: bugfix
+ body: The AmbassadorMapping resource can now specify docs.timeout_ms 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 k8s.io/klog/v2 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 AMBASSADOR_AMBEX_NO_RATELIMIT to true 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 false, 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 maxStale field is now supported in in the JWT Filter to configure how long $productname$ should cache OIDC responses for similar to the existing maxStale 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 developer preview. 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 Slack 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 x.getambassador.io/v3alpha1 for
+ configuration changes that are not backwards compatible with the 1.X family. API versions
+ getambassador.io/v0, getambassador.io/v1, and
+ getambassador.io/v2 are deprecated. Further details are available in the Major Changes
+ in 2.X 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 AmbassadorListener CRD defines where and how to listen for requests from the network, and which AmbassadorHost definitions should be used to process those requests. Note that the AmbassadorListener CRD is mandatory and consolidates all port configuration; see the AmbassadorListener documentation 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 AmbassadorMapping's host field is either an exact match or (with host_regex set) a regex,
+ the new hostname element is always a DNS glob. Use hostname instead of host 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 prune_unreachable_routes field is now automatic, which should reduce Envoy memory requirements for installations with many AmbassadorHosts
+ 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 AmbassadorHost can specify its requestPolicy.insecure.action independently of any other AmbassadorHost, 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, Noah Fontes!
+ 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 :authority header didn't match
+ type: bugfix
+
+ - title: Port configuration outside AmbassadorListener has been moved to AmbassadorListener
+ body: The TLSContext redirect_cleartext_from and AmbassadorHost requestPolicy.insecure.additionalPort elements are no longer supported. Use a AmbassadorListener 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 use_proxy_protocol element of the Ambassador Module is no longer supported, as it is now part of the AmbassadorListener resource (and can be set per-AmbassadorListener rather than globally).
+ type: change
+ docs: about/changes-2.x/#proxy-protocol-configuration
+
+ - title: Stricter rules for AmbassadorHost/AmbassadorMapping association
+ body: An AmbassadorMapping will only be matched with an AmbassadorHost if the AmbassadorMapping's host or the AmbassadorHost's selector (or both) are explicitly set, and match. This change can significantly improve $productName$'s memory footprint when many AmbassadorHosts are involved. Further details are available in the 2.0.0 Changes document.
+ docs: about/changes-2.x/#host-and-mapping-association
+ type: change
+
+ - title: AmbassadorHost or Ingress now required for TLS termination
+ body: An AmbassadorHost or Ingress resource is now required when terminating TLS -- simply creating a TLSContext is not sufficient. Further details are available in the AmbassadorHost CRD documentation.
+ 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 Major Changes in 2.X document.
+ type: change
+ docs: about/changes-2.x/#envoy-v3-api-by-default
+
+ - title: Module-based TLS no longer supported
+ body: The tls module and the tls field in the Ambassador module are no longer supported. Please use TLSContext 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 AMBASSADOR_FAST_RECONFIGURE 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 AGENT_SERVICE 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 edgectl CLI tool has been deprecated; please use the emissary-ingress 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 respect_dns_ttl 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 dns_type in Ambassador Mappings to use Envoy's
+ logical_dns resolution instead of the default strict_dns.
+ docs: topics/using/mappings/#dns-configuration-for-mappings
+
+ - title: Support configuring upstream buffer size
+ type: feature
+ body: >-
+ You can now set buffer_limit_bytes in the ambassador
+ Module 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 allow_chunked_length 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: >-
+ AMBASSADOR_ENVOY_API_VERSION now defaults to V3
+ 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 cors.origins
+ on the Mapping 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 ambex-#.json) in /ambassador/snapshots. The number of snapshots is controlled by the AMBASSADOR_AMBEX_SNAPSHOT_COUNT 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 AMBASSADOR_AMBEX_NO_RATELIMIT to true 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 false, 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 Mapping resource can now specify docs.timeout_ms 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 AMBASSADOR_LEGACY_MODE=true.
+
+ - 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 ambassador Module
+ config keys proper_case and preserve_external_request_id
+ 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
+ reject_requests_with_escaped_slashes 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.
diff --git a/docs/edge-stack/3.9/topics/install/helm.md b/docs/edge-stack/3.9/topics/install/helm.md
new file mode 100644
index 000000000..84c40d586
--- /dev/null
+++ b/docs/edge-stack/3.9/topics/install/helm.md
@@ -0,0 +1,107 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Install with Helm
+
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ 
Install with Helm
+Helm, the package manager for Kubernetes, is the recommended way to install
+$productName$. Full details are in the [Helm instructions.](helm/)
+
+## 
Install with Kubernetes YAML
+Another way to install $productName$ if you are unable to use Helm is to
+directly apply Kubernetes YAML. See details in the
+[manual YAML installation instructions.](yaml-install).
+
+## 
Try the demo with Docker
+The Docker install will let you try the $productName$ locally in seconds,
+but is not supported for production workloads. [Try $productName$ on Docker.](docker/)
+
+## Upgrade or migrate to a newer version
+If you already have an existing installation of $AESproductName$ or
+$OSSproductName$, you can upgrade your instance. The [migration matrix](migration-matrix/)
+shows you how.
+
+## Container Images
+Although our installation guides will favor using the `docker.io` container registry,
+we publish $AESproductName$ and $OSSproductName$ releases to multiple registries.
+
+Starting with version 1.0.0, you can pull the aes image from any of the following registries:
+- `docker.io/datawire/`
+- `gcr.io/datawire/`
+
+We want to give you flexibility and independence from a hosting platform's uptime to support
+your production needs for $AESproductName$ or $OSSproductName$. Read more about
+[Running $productName$ in Production](../running).
+
+# What’s Next?
+$productName$ has a comprehensive range of [features](/features/) to
+support the requirements of any edge microservice. To learn more about how $productName$ works, along with use cases, best practices, and more,
+check out the [Welcome page](../../tutorials/getting-started/) or read the [$productName$
+Story](../../about/why-ambassador).
diff --git a/docs/edge-stack/3.9/topics/install/migrate-to-3-alternate.md b/docs/edge-stack/3.9/topics/install/migrate-to-3-alternate.md
new file mode 100644
index 000000000..d0b791a12
--- /dev/null
+++ b/docs/edge-stack/3.9/topics/install/migrate-to-3-alternate.md
@@ -0,0 +1,36 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$ with a separate cluster
+
+You can upgrade from any version of $AESproductName$ or $OSSproductName$ to
+any version of either by installing the new version in a new Kubernetes cluster,
+then copying over configuration as needed. This is the way to be absolutely
+certain that each installation cannot affect the other: it is extremely safe,
+but is also significantly more effort.
+
+For example, to upgrade from some other version of $AESproductName$ or
+$OSSproductName$ to $productName$ $version$:
+
+1. Install $productName$ $version$ in a completely new cluster.
+
+2. **Create `Listener`s for $productName$ $version$.**
+
+ When $productName$ $version$ starts, it will not have any `Listener`s, and it will not
+ create any. You must create `Listener` resources by hand, or $productName$ $version$
+ will not listen on any ports.
+
+3. Copy the entire configuration from the $productName$ 1.X cluster to the $productName$
+ $version$ cluster. This is most simply done with `kubectl get -o yaml | kubectl apply -f -`.
+
+ This will create `getambassador.io/v2` resources in the $productName$ $version$ cluster.
+ $productName$ $version$ will translate them internally to `getambassador.io/v3alpha1`
+ resources.
+
+4. Each $productName$ instance has its own cluster, so you can test the new
+ instance without disrupting traffic to the existing instance.
+
+5. If you need to make changes, you can change the `getambassador.io/v2` resource, or convert the
+ resource you're changing to `getambassador.io/v3alpha1` by using `kubectl edit`.
+
+6. Once everything is working with both versions, transfer incoming traffic to the $productName$
+ $version$ cluster.
diff --git a/docs/edge-stack/3.9/topics/install/migration-matrix.md b/docs/edge-stack/3.9/topics/install/migration-matrix.md
new file mode 100644
index 000000000..ead43c6e0
--- /dev/null
+++ b/docs/edge-stack/3.9/topics/install/migration-matrix.md
@@ -0,0 +1,48 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$
+
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AES_ACME_LEADER_DISABLE flag. This prevents
+ $productName$ $versionTwoX$ from trying to manage ACME, so that $productName$ 1.14 can
+ do it instead.
+ $productHelmName$ Helm chart for $productName$ $versionTwoX$.
+ Do not use the ambassador Helm chart.
+ Hosts you create use API version getambassador.io/v2,
+ so that they can be managed by $productName$ 1.14 as long as both installations are running.
+
+
+ This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`)
+ and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`.
+
+5. **Test!**
+
+ Your $productName$ $versionTwoX$ installation can support the `getambassador.io/v2`
+ configuration resources used by $productName$ 1.14, but you may need to make some
+ changes to the configuration, as detailed in the documentation on
+ [configuring $productName$ Communications](../../../../../../howtos/configure-communications)
+ and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1).
+
+ getambassador.io/v3alpha1 resource
+ with the same name as a getambassador.io/v2 resource or vice versa: only
+ one version can be stored at a time.emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 2.X.
+ Do not use the ambassador Helm chart.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 2.X.
+ Do not use the ambassador Helm chart.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AES_ACME_LEADER_DISABLE flag. This prevents collisions in trying to manage
+ ACME.
+ Hosts you create use API version getambassador.io/v2,
+ so that they can be managed by $productName$ 1.14 as long as both installations are running.
+
+
+ This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`)
+ and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`.
+
+5. **Test!**
+
+ Your $productName$ $versionTwoX$ installation can support the `getambassador.io/v2`
+ configuration resources used by $productName$ 1.14, but you may need to make some
+ changes to the configuration, as detailed in the documentation on
+ [configuring $productName$ Communications](../../../../../../howtos/configure-communications)
+ and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1).
+
+ getambassador.io/v3alpha1 resource
+ with the same name as a getambassador.io/v2 resource or vice versa: only
+ one version can be stored at a time.emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service.
+ timeout_ms of the ambassador-edge-stack-auth AuthService defaults
+to a value of 5000 (five seconds). You will need to adjust this as well.
+
+AES_AUTH_TIMEOUT should always be around one second shorter than the timeout_ms of the AuthService to ensure Filter error responses make it to the client.
+
+The External Filter also have a timeout_ms field that must be set if a single Filter will take longer than five seconds.
+ambassador-redis-password instead
+ of providing the value directly.
+ AUTH without USERNAME and PASSWORD can result in various problems since AUTH does not
+ overwrite the basic Redis authentication behavior for systems outside of rate limit preview.
+all_methods and services are present, all_methods will be ignored.
+proper_case and header_case_overrides are mutually exclusive.ip_allow and ip_deny may be specified.xff_num_trusted_hops for Envoy to respect the change.
+Listener resources are required for a functioning
+ $productName$ installation!Listener.
+Host exists! If the
+ wildcard behavior is needed, a Host with a hostname of "*"
+ must be defined by the user.
+Listener will also be required for this example to
+be functional. Many examples of setting up `Host` and `Listener` are available in the
+[Configuring $productName$ to Communicate](../../../howtos/configure-communications) document.
+
+## Setting the `hostname`
+
+The `hostname` element tells $productName$ which hostnames to expect. `hostname` is a DNS glob,
+so all of the following are valid:
+
+- `host.example.com`
+- `*.example.com`
+- `host.example.*`
+
+The following are _not_ valid:
+
+- `host.*.com` -- Envoy supports only prefix and suffix globs
+- `*host.example.com` -- the wildcard must be its own element in the DNS name
+
+In all cases, the `hostname` is used to match the `:authority` header for HTTP routing.
+When TLS termination is active, the `hostname` is also used for SNI matching.
+
+## Controlling Association with `Mapping`s
+
+A `Mapping` will not be associated with a `Host` unless at least one of the following is true:
+
+- The `Mapping` specifies a `hostname` attribute that matches the `Host` in question.
+- The `Host` specifies a `mappingSelector` that matches the `Mapping`'s Kubernetes `label`s.
+
+> **Note:** The `mappingSelector` field is only configurable on `v3alpha1` CRDs. In the `v2` CRDs the equivalent field is `selector`.
+either `selector` or `mappingSelector` may be configured in the `v3alpha1` CRDs, but `selector` has been deprecated in favour of `mappingSelector`.
+
+If neither of the above is true, the `Mapping` will not be associated with the `Host` in
+question. This is intended to help manage memory consumption with large numbers of `Host`s and large
+numbers of `Mapping`s.
+
+If the `Host` specifies `mappingSelector` _and_ the `Mapping` specifies `hostname`, both must match
+for the association to happen.
+
+The `mappingSelector` is a Kubernetes [label selector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta). For a `Mapping` to be associated with a `Host` that uses `mappingSelector`, then **all** labels
+required by the `mappingSelector` must be present on the `Mapping` in order for it to be associated with the `Host`.
+A `Mapping` may have additional labels other than those required by the `mappingSelector` so long as the required labels are present.
+
+**in 2.0, only `matchLabels` is supported**, for example:
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: minimal-host
+spec:
+ hostname: host.example.com
+ mappingSelector:
+ matchLabels:
+ examplehost: host
+```
+
+The above `Host` will associate with these `Mapping`s:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-label-match
+ labels:
+ examplehost: host # This matches the Host's mappingSelector.
+spec:
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-hostname-match
+spec:
+ hostname: host.example.com # This is an exact match of the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-hostname-glob-match
+spec:
+ hostname: '*.example.com' # This glob matches the Host's hostname too.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-both-matches
+ labels:
+ examplehost: host # This matches the Host's mappingSelector.
+spec:
+ hostname: '*.example.com' # This glob matches the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+```
+
+It will _not_ associate with any of these:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-wrong-label
+ labels:
+ examplehost: staging # This doesn't match the Host's mappingSelector.
+spec:
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-wrong-hostname
+spec:
+ hosname: 'bad.example.com' # This doesn't match the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-still-wrong
+ labels:
+ examplehost: staging # This doesn't match the Host's mappingSelector,
+spec: # and if the Host specifies mappingSelector AND the
+ hostname: host.example.com # Mapping specifies hostname, BOTH must match. So
+ prefix: /httpbin/ # the matching hostname isn't good enough.
+ service: http://httpbin.org
+```
+
+Future versions of $productName$ will support `matchExpressions` as well.
+
+> **Note:** In $productName$ version `3.2`, a bug with how `Hosts` are associated with `Mappings` was fixed. The `mappingSelector` field in `Hosts` was not
+properly being enforced in prior versions. If any single label from the selector was matched then the `Host` would be associated with the `Mapping` instead
+of requiring all labels in the selector to be present. Additonally, if the `hostname` of the `Mapping` matched the `hostname` of the `Host` then they would be associated
+regardless of the configuration of `mappingSelector`.
+In version `3.2` this bug was fixed and a `Host` will only be associated with a `Mapping` if **all** labels required by the selector are present.
+This brings the `mappingSelector` field in-line with how label selectors are used throughout Kubernetes. To avoid unexpected behavior after the upgrade,
+add all labels that `Hosts` have in their `mappingSelector` to `Mappings` you want to associate with the `Host`. You can opt-out of this fix and return to the old
+`Mapping`/`Host` association behavior by setting the environment variable `DISABLE_STRICT_LABEL_SELECTORS` to `"true"` (default: `"false"`). A future version of
+$productName$ may remove the ability to opt-out of this bugfix.
+
+## Secure and insecure requests
+
+A **secure** request arrives via HTTPS; an **insecure** request does not. By default, secure requests will be routed and insecure requests will be redirected (using an HTTP 301 response) to HTTPS. The behavior of insecure requests can be overridden using the `requestPolicy` element of a `Host`:
+
+```yaml
+requestPolicy:
+ insecure:
+ action: insecure-action
+ additionalPort: insecure-port
+```
+
+The `insecure-action` can be one of:
+
+- `Redirect` (the default): redirect to HTTPS
+- `Route`: go ahead and route as normal; this will allow handling HTTP requests normally
+- `Reject`: reject the request with a 400 response
+
+```yaml
+requestPolicy:
+ insecure:
+ additionalPort: -1 # This is how to disable the default redirection from 8080.
+```
+
+Some special cases to be aware of here:
+
+- **Case matters in the actions:** you must use e.g. `Reject`, not `reject`.
+- The `X-Forwarded-Proto` header is honored when determining whether a request is secure or insecure. For more information, see "Load Balancers, the `Host` Resource, and `X-Forwarded-Proto`" below.
+- ACME challenges with prefix `/.well-known/acme-challenge/` are always forced to be considered insecure, since they are not supposed to arrive over HTTPS.
+- $AESproductName$ provides native handling of ACME challenges. If you are using this support, $AESproductName$ will automatically arrange for insecure ACME challenges to be handled correctly. If you are handling ACME yourself - as you must when running $OSSproductName$ - you will need to supply appropriate `Host` resources and `Mapping`s to correctly direct ACME challenges to your ACME challenge handler.
+
+## TLS settings
+
+The `Host` is responsible for high-level TLS configuration in $productName$. There are
+several settings covering TLS:
+
+### ACME support
+
+$AESproductName$ comes with built in support for automatic certificate
+management using the [ACME protocol](https://tools.ietf.org/html/rfc8555).
+
+It does this by using the `hostname` of a `Host` to request a certificate from
+the `acmeProvider.authority` using the `HTTP-01` challenge. After requesting a
+certificate, $AESproductName$ will then manage the renewal process automatically.
+
+The `acmeProvider` element of the `Host` configures the Certificate Authority
+$AESproductName$ will request the certificate from and the email address that the CA
+will use to notify about any lifecycle events of the certificate.
+
+```yaml
+acmeProvider:
+ authority: url-to-provider
+ email: email-of-registrant
+```
+
+**Notes on ACME Support:**
+
+- If the authority is not supplied, the Let’s Encrypt production environment is assumed.
+
+- In general, `email-of-registrant` is mandatory when using ACME: it should be
+ a valid email address that will reach someone responsible for certificate
+ management.
+
+- ACME stores certificates in Kubernetes secrets. The name of the secret can be
+ set using the `tlsSecret` element:
+
+ ```yaml
+ acmeProvider:
+ email: user@example.com
+ tlsSecret:
+ name: tls-cert
+ ```
+
+ if not supplied, a name will be automatically generated from the `hostname` and `email`.
+
+- $AESproductName$ uses the [`HTTP-01` challenge
+ ](https://letsencrypt.org/docs/challenge-types/) for ACME support:
+ - Does not require permission to edit DNS records
+ - The `hostname` must be reachable from the internet so the CA can check
+ `POST` to an endpoint in $AESproductName$.
+ - Wildcard domains are not supported.
+
+### `tlsSecret` enables TLS termination
+
+`tlsSecret` specifies a Kubernetes `Secret` is **required** for any TLS termination to occur. If ACME is enabled,
+it will set `tlsSecret`: in all other cases, TLS termination will not occur if `tlsSecret` is not specified.
+
+The following `Host` will configure $productName$ to read a `Secret` named
+`tls-cert` for a certificate to use when terminating TLS.
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: example-host
+spec:
+ hostname: host.example.com
+ acmeProvider:
+ authority: none
+ tlsSecret:
+ name: tls-cert
+```
+
+### `tlsContext` links to a `TLSContext` for additional configuration
+
+`tlsContext` specifies a [`TLSContext`](#) to use for additional TLS information. Note that you **must** still
+define `tlsSecret` for TLS termination to happen. It is an error to supply both `tlsContext` and `tls`.
+
+See the [TLS discussion](../tls) for more details.
+
+### `tls` allows manually providing additional configuration
+
+`tls` allows specifying most of the things a `TLSContext` can, inline in the `Host`. Note that you **must** still
+define `tlsSecret` for TLS termination to happen. It is an error to supply both `tlsContext` and `tls`.
+
+See the [TLS discussion](../tls) for more details.
+
+## Load balancers, the `Host` resource, and `X-Forwarded-Proto`
+
+In a typical installation, $productName$ runs behind a load balancer. The
+configuration of the load balancer can affect how $productName$ sees requests
+arriving from the outside world, which can in turn can affect whether $productName$
+considers the request secure or insecure. As such:
+
+- **We recommend layer 4 load balancers** unless your workload includes
+ long-lived connections with multiple requests arriving over the same
+ connection. For example, a workload with many requests carried over a small
+ number of long-lived gRPC connections.
+- **$productName$ fully supports TLS termination at the load balancer** with a single exception, listed below.
+- If you are using a layer 7 load balancer, **it is critical that the system be configured correctly**:
+ - The load balancer must correctly handle `X-Forwarded-For` and `X-Forwarded-Proto`.
+ - The `l7Depth` element in the [`Listener` CRD](../../running/listener) must be set to the number of layer 7 load balancers the request passes through to reach $productName$ (in the typical case, where the client speaks to the load balancer, which then speaks to $productName$, you would set `l7Depth` to 1). If `l7Depth` remains at its default of 0, the system might route correctly, but upstream services will see the load balancer's IP address instead of the actual client's IP address.
+
+It's important to realize that Envoy manages the `X-Forwarded-Proto` header such that it **always** reflects the most trustworthy information Envoy has about whether the request arrived encrypted or unencrypted. If no `X-Forwarded-Proto` is received from downstream, **or if it is considered untrustworthy**, Envoy will supply an `X-Forwarded-Proto` that reflects the protocol used for the connection to Envoy itself. The `l7Depth` element is also used when determining trust for `X-Forwarded-For`, and it is therefore important to set it correctly. Its default of 0 should always be correct when $productName$ is behind only layer 4 load balancers; it should need to be changed **only** when layer 7 load balancers are involved.
+
+### CRD specification
+
+The `Host` CRD is formally described by its protobuf specification. Developers who need access to the specification can find it [here](https://github.com/emissary-ingress/emissary/blob/release/v2.0/api/getambassador.io/v2/Host.proto).
diff --git a/docs/edge-stack/3.9/topics/running/tls/cleartext-redirection.md b/docs/edge-stack/3.9/topics/running/tls/cleartext-redirection.md
new file mode 100644
index 000000000..74fc88eeb
--- /dev/null
+++ b/docs/edge-stack/3.9/topics/running/tls/cleartext-redirection.md
@@ -0,0 +1,91 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Cleartext support
+
+While most modern web applications choose to encrypt all traffic, there remain
+cases where supporting cleartext communications is important. $productName$ supports
+both forcing [automatic redirection to HTTPS](#http-https-redirection) and
+[serving cleartext](#cleartext-routing) traffic on a `Host`.
+
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+requestPolicy; however, most real-world
+ usage of $productName$ will require defining the requestPolicy.Host documentation.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+tls setting and the tlsContext
+ setting on the same Host. The recommended setting is using the tls setting
+ unless you have multiple Hosts that need to share TLS configuration.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+TLSContext linkage is deprecated and will be removed
+ in a future version of $productName$; it is not recommended for new
+ configurations. Any other TLS configuration in the Host will override
+ this implict TLSContext link.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+key-1 in the example) used in the Secret do not matter, so you can name them whatever helps you keep track of the associated API Keys.
+
+
+4. Create a [FilterPolicy resource][] to use the `Filter` created above
+
+ ```yaml
+ kubectl apply -f -<ambassador_xsrf.NAME.NAMESPACE cookie, and instead required you to use the ambassador_session.NAME.NAMESPACE cookie. The ambassador_session.NAME.NAMESPACE cookie should no longer be used for XSRF-protection purposes.
+labels require Mapping resources with apiVersion
+ getambassador.io/v2 or newer — if you're updating an old installation, check the
+ apiVersion!
+ kubectl get services,deployments quote to see their status.
+
+3. Generate the YAML for a `Mapping` to tell $productName$ to route all traffic inbound to the `/backend/` path to the `quote` Service.
+
+ In this step, we'll be using the Mapping Editor, which you can find in the service details view of your [Ambassador Cloud connected installation](#getting-a-license-from-ambassador-cloud).
+ Open your browser to https://app.getambassador.io/cloud/services/quote/details and click on **New Mapping**.
+
+ Default options are automatically populated. **Enable and configure the following settings**, then click **Generate Mapping**:
+ - **Path Matching**: `/backend/`
+ - **OpenAPI Docs**: `/.ambassador-internal/openapi-docs`
+
+ 
+
+ Whether you decide to automatically push the change to Git for this newly create Mapping resource or not, the resulting Mapping should be similar to the example below.
+
+ **Apply this YAML to your target cluster now.**
+
+ ```yaml
+ kubectl apply -f - < What's next?
+
+Explore some of the popular tutorials on $productName$:
+
+* [Intro to Mappings](../../topics/using/intro-mappings/): declaratively routes traffic from
+the edge of your cluster to a Kubernetes service
+* [Host resource](../../topics/running/host-crd/): configure a hostname and TLS options for your ingress.
+* [Rate Limiting](../../topics/using/rate-limits/rate-limits/): create policies to control sustained traffic loads
+
+$productName$ has a comprehensive range of [features](/features/) to
+support the requirements of any edge microservice.
+
+To learn more about how $productName$ works, read the [$productName$ Story](../../about/why-ambassador).
diff --git a/docs/edge-stack/3.9/tutorials/gs-tabs.js b/docs/edge-stack/3.9/tutorials/gs-tabs.js
new file mode 100644
index 000000000..6cbeab1bc
--- /dev/null
+++ b/docs/edge-stack/3.9/tutorials/gs-tabs.js
@@ -0,0 +1,132 @@
+import AppBar from '@material-ui/core/AppBar';
+import Box from '@material-ui/core/Box';
+import Tab from '@material-ui/core/Tab';
+import Tabs from '@material-ui/core/Tabs';
+import { makeStyles } from '@material-ui/core/styles';
+import PropTypes from 'prop-types';
+import React from 'react';
+
+import CodeBlock from '../../../../../src/components/CodeBlock';
+import Icon from '../../../../../src/components/Icon';
+
+function TabPanel(props) {
+ const { children, value, index, ...other } = props;
+
+ return (
+ cloud-connect-token that is used to connect your
+ cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ cloud-connect-token that is used to connect your
+ cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ cloud-connect-token that is used to connect
+ your cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ edgectl is
+ identical to the Kubernetes YAML procedure.
+ cloud-connect-token that is used to connect
+ your cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ timeout field is set to `5 Seconds` and is not currently configurable but will be made so for the official release of $productName$ 4.x.
@@ -100,6 +110,16 @@ Configures passing along the request body to the External Service. If not set th
| `maxBytes` | `int` | Sets the number of bytes of the request body to buffer over to the External Service |
| `allowPartial` | `bool` | Indicates whether the included body can be a partially buffered body or if the complete buffered body is expected. If not partial then a 413 http error is returned by Envoy. |
+### TLSConfig
+
+**Appears On**: [ExternalFilter][]
+Configures passing along the request body to the External Service. If not set then a blank body is sent over to the External Service.
+
+| **Field** | **Type** | **Description** |
+|-----------------------------|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `certificate.fromSecret` | SecretReference | Configures $productName$ to use the provided certificate to present to the server when connecting. Provide the `name` and `namespace` (optional) of a `kubernetes.io/tls` [Kubernetes Secret][] that contains the private key and public certificate that will be presented to the AuthService. Secret namespace defaults to Filter namespace if not set |
+| `caCertificate.fromSecret` | SecretReference | Configures $productName$ to use the provided CA certifcate to verify the server provided certificate. Provide the `name` and `namespace` (optional) of an `Opaque` [Kubernetes Secret][] that contains the `tls.crt` key with the CA Certificate. Secret namespace defaults to Filter namespace if not set |
+
## External Filter Usage Guides
- [Using External Filters][]: Use the External Filter to write your own service with custom processing and authentication logic
@@ -110,6 +130,7 @@ Configures passing along the request body to the External Service. If not set th
[ExternalFilter]: #externalfilter
[GRPCSettings]: #grpcsettings
[IncludeBody]: #includebody
+[TLSConfig]: #tlsconfig
[usage guides section]: #external-filter-usage-guides
[ext_authz protocol]: ../../guides/custom-filters/ext-authz
[The Ext_Authz Protocol]: ../../guides/custom-filters/ext-authz
diff --git a/docs/edge-stack/4.0-preview/custom-resources/filter-oauth2.md b/docs/edge-stack/4.0-preview/custom-resources/filter-oauth2.md
index 92f4dc45c..124c0f81e 100644
--- a/docs/edge-stack/4.0-preview/custom-resources/filter-oauth2.md
+++ b/docs/edge-stack/4.0-preview/custom-resources/filter-oauth2.md
@@ -7,7 +7,7 @@ The OAuth2 Filter type performs OAuth2 authorization against an identity provide
This doc is an overview of all the fields on the OAuth2 `Filter` Custom Resource with descriptions of the purpose, type, and default values of those fields.
Tutorials and guides for the OAuth2 `Filter` Resource can be found in the [usage guides section][].
-## External Filter API Reference
+## OAuth2 Filter API Reference
To create an OAuth2 Filter, the `spec.type` must be set to `oauth2`, and the `oauth2` field must contain the configuration for your
OAuth2 filter.
diff --git a/docs/edge-stack/latest b/docs/edge-stack/latest
deleted file mode 120000
index 98fccd6d0..000000000
--- a/docs/edge-stack/latest
+++ /dev/null
@@ -1 +0,0 @@
-3.8
\ No newline at end of file
diff --git a/docs/edge-stack/latest/about/aes-emissary-eol.md b/docs/edge-stack/latest/about/aes-emissary-eol.md
new file mode 100644
index 000000000..1e4b2caa9
--- /dev/null
+++ b/docs/edge-stack/latest/about/aes-emissary-eol.md
@@ -0,0 +1,56 @@
+# $productName$ End of Life Policy
+
+This document describes the End of Life policy and maintenance windows for Ambassador Edge Stack, and to the open source project Emissary Ingress.
+
+## Supported Versions
+
+Ambassador Edge Stack and Emissary-ingress versions are expressed as **x.y.z**, where **x** is the major version, **y** is the minor version, and **z** is the patch version, following [Semantic Versioning](https://semver.org/) terminology.
+
+**X-series (Major Versions)**
+
+- **1.y**: 1.0 GA on January 2020
+- **2.y**: 2.0.4 GA on October 2021, and 2.1.0 in December 2021.
+
+**Y-release (Minor versions)**
+
+- For 1.y, that is **1.14.z**
+- For 2.y, that is **2.3.z**
+
+In this document, **Current** refers to the latest X-series release.
+
+Maintenance refers to the previous X-series release, including security and Sev1 defect patches.
+
+## CNCF Ecosystem Considerations
+
+- Envoy releases a major version every 3 months and supports its previous releases for 12 months. Envoy does not support any release longer than 12 months.
+- Kubernetes 1.19 and newer receive 12 months of patch support (The [Kubernetes Yearly Support Period](https://github.com/kubernetes/enhancements/blob/master/keps/sig-release/1498-kubernetes-yearly-support-period/README.md)).
+
+# The Policy
+
+> We will offer a 6 month maintenance window for the latest Y-release of an X-series after a new X-series goes GA and becomes the current release. For example, we will support 2.3 for severity 1 and defect patches for six months after 3.0 is released.
+>
+
+> During the maintenance window, Y-releases will only receive security and Sev1 defect patches. Users desiring new features or bug fixes for lower severity defects will need to upgrade to the current X-series.
+>
+
+> The current X-series will receive as many Y-releases as necessary and as often as we have new features or patches to release.
+>
+
+> Ambassador Labs offers no-downtime migration to current versions from maintenance releases. Migration from releases that are outside of the maintenance window may be subject to downtime.
+>
+
+> Artifacts of releases outside of the maintenance window will be frozen and will remain available publicly for download with the best effort. These artifacts include Docker images, application binaries, Helm charts, etc.
+>
+
+### When we say support with “defect patches”, what do we mean?
+
+- We will fix security issues in our Emissary-ingress and Ambassador Edge Stack code
+- We will pick up security fixes from dependencies as they are made available
+- We will not maintain forks of our major dependencies
+- We will not attempt our own back ports of critical fixes to dependencies which are out of support from their own communities
+
+## Extended Maintenance for 1.14
+
+Given this policy, we should have dropped maintenance for 1.14 in March 2022, however we recognize that the introduction of an EOL policy necessitates a longer maintenance window. For this reason, we do offer an "extended maintenance" window for 1.14 until the end of September 2022, 3 months after the latest 2.3 release. Please note that this extended maintenance window will not apply to customers using Kubernetes 1.22 and above, and this extended maintenance will also not provide a no-downtime migration path from 1.14 to 3.0.
+
+After September 2022, the current series will be 3.x, and the maintenance series will be 2.y.
diff --git a/docs/edge-stack/latest/about/changes-2.x.md b/docs/edge-stack/latest/about/changes-2.x.md
new file mode 100644
index 000000000..89938a44b
--- /dev/null
+++ b/docs/edge-stack/latest/about/changes-2.x.md
@@ -0,0 +1,243 @@
+import Alert from '@material-ui/lab/Alert';
+
+Major Changes in $productName$ 2.X
+==================================
+
+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
+[Slack](http://a8r.io/slack) and let us know what you think.
+
+While $productName$ 2 is functionally compatible with $productName$ 1.14, note
+that this is a **major version change** and there are important differences between
+$productName$ 1.X and $productName$ $version$. For details, read on.
+
+## 1. Configuration API Version `getambassador.io/v3alpha1`
+
+$productName$ 2.0 introduced API version `getambassador.io/v3alpha1` to allow
+certain changes in configuration resources that are not backwards compatible with
+$productName$ 1.X. The most notable example of change is the addition of the
+**mandatory** `Listener` resource; however, there are important changes
+in `Host` and `Mapping` as well.
+
+getambassador.io/v2
+ and getambassador.io/v3alpha1. If you are using any resources with
+ older API versions, you will need to upgrade them.
+Listener.Host.
+Host.
+Host.Mapping.
+Host.
+Host.TLSContext.
+Mapping.
+Mapping.
+Host.
+Listener.
+AMBASSADOR_ENVOY_API_VERSION because it no longer configurable and will have no effect.
+
+
+## 4. Zipkin HTTP_JSON_V1 support is removed
+
+Envoy removed support for the older `HTTP_JSON_V1` collector_endpoint_version. If using the `zipkin` driver with the `TracingService`,
+then you will have to update it to use `HTTP_JSON` or `HTTP_PROTO`.
diff --git a/docs/edge-stack/latest/about/faq.md b/docs/edge-stack/latest/about/faq.md
new file mode 100644
index 000000000..14528f9a1
--- /dev/null
+++ b/docs/edge-stack/latest/about/faq.md
@@ -0,0 +1,88 @@
+# Frequently Asked Questions
+
+## General
+
+### Why $productName$?
+
+Kubernetes shifts application architecture for microservices, as well as the
+development workflow for a full-cycle development. $productName$ is designed for
+the Kubernetes world with:
+
+* Sophisticated traffic management capabilities (thanks to its use of [Envoy Proxy](https://www.envoyproxy.io)), such as load balancing, circuit breakers, rate limits, and automatic retries.
+* API management capabilities such as a developer portal and OpenID Connect integration for Single Sign-On.
+* A declarative, self-service management model built on Kubernetes Custom Resource Definitions, enabling GitOps-style continuous delivery workflows.
+
+We've written about [the history of $productName$](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844), [Why $productName$ In Depth](../why-ambassador), [Features and Benefits](../features-and-benefits) and about the [evolution of API Gateways](../../topics/concepts/microservices-api-gateways/).
+
+### What's the difference between $OSSproductName$ and $AESproductName$?
+
+$OSSproductName$ is a CNCF Incubating project and provides the open-source core of $AESproductName$. Originally we called $OSSproductName$ the "Ambassador API Gateway", but as the project evolved, we realized that the functionality we were building had extended far beyond an API Gateway. In particular, the $AESproductName$ is intended to provide all the functionality you need at the edge -- hence, an "edge stack." This includes an API Gateway, ingress controller, load balancer, developer portal, and more.
+
+### How is $AESproductName$ licensed?
+
+The core $OSSproductName$ is open source under the Apache Software License 2.0. The GitHub repository for the core is [https://github.com/emissary-ingress/emissary](https://github.com/emissary-ingress/emissary). Some additional features of the $AESproductName$ (e.g., Single Sign-On) are not open source and available under a proprietary license.
+
+### Can I use the add-on features for $AESproductName$ for free?
+
+Yes! For more details please see the [$productName$ Licenses page](../../topics/using/licenses).
+
+### How does $productName$ use Envoy Proxy?
+
+$productName$ uses [Envoy Proxy](https://www.envoyproxy.io) as its core proxy. Envoy is an open-source, high-performance proxy originally written by Lyft. Envoy is now part of the Cloud Native Computing Foundation.
+
+### Is $productName$ production ready?
+
+Yes. Thousands of organizations, large and small, run $productName$ in production.
+Public users include Chick-Fil-A, ADP, Microsoft, NVidia, and AppDirect, among others.
+
+### What is the performance of $productName$?
+
+There are many dimensions to performance. We published a benchmark of [$productName$ performance on Kubernetes](/resources/envoyproxy-performance-on-k8s/). Our internal performance regressions cover many other scenarios; we expect to publish more data in the future.
+
+### What's the difference between a service mesh (such as Istio) and $productName$?
+
+Service meshes focus on routing internal traffic from service to service
+("east-west"). $productName$ focuses on traffic into your cluster ("north-south").
+While both a service mesh and $productName$ can route L7 traffic, the reality is that
+these use cases are quite different. Many users will integrate $productName$ with a
+service mesh. Production customers of $productName$ have integrated with Consul,
+Istio, and Linkerd2.
+
+## Common Configurations
+
+### How do I disable the 404 landing page?
+
+See the [Controlling the $productName$ 404 Page](../../howtos/controlling-404) how-to.
+
+### How do I disable the default Admin mappings?
+
+See the [Protecting the Diagnostics Interface](../../howtos/protecting-diag-access) how-to.
+
+## Troubleshooting
+
+### How do I get help for $productName$?
+
+We have an online [Slack community](http://a8r.io/slack) with thousands of
+users. We try to help out as often as possible, although we can't promise a
+particular response time. If you need a guaranteed SLA, we also have commercial
+contracts. [Contact sales](/contact-us/) for more information.
+
+### What do I do when I get the error `no healthy upstream`?
+
+This error means that $productName$ could not connect to your backend service.
+Start by verifying that your backend service is actually available and
+responding by sending an HTTP response directly to the pod. Then, verify that
+$productName$ is routing by deploying a test service and seeing if the mapping
+works. Then, verify that your load balancer is properly routing requests to
+$productName$. In general, verifying each network hop between your client and
+backend service is critical to finding the source of the problem.
+
+### What is the difference between the v3alpha1 and v1alpha1 CRDs?
+
+There are two different CRD versions supported by $productName$.
+The first are the `getambassador.io/v3alpha1` CRDs which were introduced with
+$productName$ 2.x. These are still supported and are not deprecated. As of $productName$ $version$, the new `gateway.getambassador.io/v1alpha1` CRDs have also been introduced.
+The `v1alpha1` CRDs have not only a new version, but also a new apigoup so that way they can
+be installed alongside the older CRDs without causing any conflicts.
+
+The `v1alpha1` CRDs are only available for the `Filter`, `FilterPolicy`, `WebApplicationFirewall`, and `WebApplicationFirewallPolicy` resources, and are the next generation of the CRDs that $productName$ will support. We are introducing them now to allow users to try them out without needing to stop using the `v3alpha1` CRDs. You can use `v1alpha1` and `v3alpha1` CRDs in the same cluster at the same time, but `FilterPolicies` are not able to reference `Filters` that do not match their CRD version.
diff --git a/docs/edge-stack/latest/about/features-and-benefits.md b/docs/edge-stack/latest/about/features-and-benefits.md
new file mode 100644
index 000000000..ecad16175
--- /dev/null
+++ b/docs/edge-stack/latest/about/features-and-benefits.md
@@ -0,0 +1,39 @@
+# Features and benefits
+
+In cloud-native organizations, developers frequently take on responsibility for the full development lifecycle of a service, from development to QA to operations. $productName$ was specifically designed for these organizations where developers have operational responsibility for their service(s).
+
+As such, the $productName$ is designed to be used by both developers and operators.
+
+## Self-Service via Kubernetes Annotations
+
+$productName$ is built from the start to support _self-service_ deployments -- a developer working on a new service doesn't have to go to Operations to get their service added to the mesh, they can do it themselves in a matter of seconds. Likewise, a developer can remove their service from the mesh, or merge services, or separate services, as needed, at their convenience. All of these operations are performed via Kubernetes resources or annotations, so they can easily integrate with your existing development workflow.
+
+## Flexible canary deployments
+
+Canary deployments are an essential component of cloud-native development workflows. In a canary deployment, a small percentage of production traffic is routed to a new version of a service to test it under real-world conditions. $productName$ allows developers to easily control and manage the amount of traffic routed to a given service through annotations. [This tutorial](https://www.datawire.io/faster/canary-workflow/) covers a complete canary workflow using the $productName$.
+
+## Kubernetes-native architecture
+
+$productName$ relies entirely on Kubernetes for reliability, availability, and scalability. For example, $productName$ persists all state in Kubernetes, instead of requiring a separate database. Scaling the $productName$ is as simple as changing the replicas in your deployment, or using a [horizontal pod autoscaler](https://kubernetes.io/docs/tasks/run-application/horizontal-pod-autoscale/).
+
+$productName$ uses [Envoy](https://www.envoyproxy.io) for all traffic routing and proxying. Envoy is a modern L7 proxy that is used in production at companies including Lyft, Apple, Google, and Stripe.
+
+## gRPC and HTTP/2 support
+
+$productName$ fully supports gRPC and HTTP/2 routing, thanks to Envoy's extensive capabilities in this area. See [gRPC and $productName$](../../howtos/grpc) for more information.
+
+## Istio Integration
+
+$productName$ integrates with the [Istio](https://istio.io) service mesh as the edge proxy. In this configuration, $productName$ routes external traffic to the internal Istio service mesh. See [Istio and $productName$](../../howtos/istio) for details.
+
+## Authentication
+
+$productName$ supports authenticating incoming requests with a custom authentication service, OAuth/OpenID Connect, or JWT. When configured, the $productName$ will check with a third party authentication service prior to routing an incoming request. For more information, see the [authentication guide](../../topics/using/filters/).
+
+## Rate limiting
+
+$productName$ supports rate limiting incoming requests. When configured, the $productName$ will check with a third party rate limit service prior to routing an incoming request. For more information, see the [rate limiting guide](../../topics/using/rate-limits/).
+
+## Integrated UI
+
+$productName$ includes a diagnostics service so that you can quickly debug issues associated with configuring the $productName$. For more information, see [running $productName$ in Production](../../topics/running).
diff --git a/docs/edge-stack/latest/about/known-issues.md b/docs/edge-stack/latest/about/known-issues.md
new file mode 100644
index 000000000..4a5c45f5b
--- /dev/null
+++ b/docs/edge-stack/latest/about/known-issues.md
@@ -0,0 +1,20 @@
+import Alert from '@material-ui/lab/Alert';
+
+Known Issues in $productName$
+=============================
+
+## 2.2.1
+
+- TLS certificates using elliptic curves were incorrectly flagged as invalid. This issue is
+ corrected in $productName$ 2.2.2.
+
+## 2.2.0
+
+- If $productName$'s Pods start before Redis is responding, it may be necessary to restart
+ $productName$ for rate limiting to function correctly.
+
+- When using the ACME client provided with $productName$, a delayed ACME response can
+ prevent the `Host` using ACME from becoming active.
+
+ - Workaround: Make sure you have a wildcard `Host` that does not use ACME. The insecure routing
+ action doesn't matter: it's fine for this `Host` to redirect or even reject insecure requests.
diff --git a/docs/edge-stack/latest/about/why-ambassador.md b/docs/edge-stack/latest/about/why-ambassador.md
new file mode 100644
index 000000000..f16def3a1
--- /dev/null
+++ b/docs/edge-stack/latest/about/why-ambassador.md
@@ -0,0 +1,54 @@
+# Why $productName$?
+
+$productName$ gives platform engineers a comprehensive, self-service edge stack for managing the boundary between end-users and Kubernetes. Built on the [Envoy Proxy](https://www.envoyproxy.io) and fully Kubernetes-native, $productName$ is made to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. A true edge stack, $productName$ can also be used to handle the functions of an API Gateway, a Kubernetes ingress controller, and a layer 7 load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
+
+## How Does $productName$ work?
+
+$productName$ is a Kubernetes-native [microservices API gateway](../../topics/concepts/microservices-api-gateways) built on the open core of $OSSproductName$ and the [Envoy Proxy](https://www.envoyproxy.io). $productName$ is built from the ground up to support multiple, independent teams that need to rapidly publish, monitor, and update services for end-users. $productName$ can also be used to handle the functions of a Kubernetes ingress controller and load balancer (for more, see [this blog post](https://blog.getambassador.io/kubernetes-ingress-nodeport-load-balancers-and-ingress-controllers-6e29f1c44f2d)).
+
+## Cloud-native applications today
+
+Traditional cloud applications were built using a monolithic approach. These applications were designed, coded, and deployed as a single unit. Today's cloud-native applications, by contrast, consist of many individual (micro)services. This results in an architecture that is:
+
+* __Heterogeneous__: Services are implemented using multiple (polyglot) languages, they are designed using multiple architecture styles, and they communicate with each other over multiple protocols.
+* __Dynamic__: Services are frequently updated and released (often without coordination), which results in a constantly-changing application.
+* __Decentralized__: Services are managed by independent product-focused teams, with different development workflows and release cadences.
+
+### Heterogeneous services
+
+$productName$ is commonly used to route traffic to a wide variety of services. It supports:
+
+* configuration on a *per-service* basis, enabling fine-grained control of timeouts, rate limiting, authentication policies, and more.
+* a wide range of L7 protocols natively, including HTTP, HTTP/2, gRPC, gRPC-Web, and WebSockets.
+* Can route raw TCP for services that use protocols not directly supported by $productName$.
+
+### Dynamic services
+
+Service updates result in a constantly changing application. The dynamic nature of cloud-native applications introduces new challenges around configuration updates, release, and testing. $productName$:
+
+* Enables [progressive delivery](../../topics/concepts/progressive-delivery), with support for canary routing and traffic shadowing.
+* Exposes high-resolution observability metrics, providing insight into service behavior.
+* Uses a zero downtime configuration architecture, so configuration changes have no end-user impact.
+
+### Decentralized workflows
+
+Independent teams can create their own workflows for developing and releasing functionality that are optimized for their specific service(s). With $productName$, teams can:
+
+* Leverage a [declarative configuration model](../../topics/concepts/gitops-continuous-delivery), making it easy to understand the canonical configuration and implement GitOps-style best practices.
+* Independently configure different aspects of $productName$, eliminating the need to request configuration changes through a centralized operations team.
+
+## $productName$ is engineered for Kubernetes
+
+$productName$ takes full advantage of Kubernetes and Envoy Proxy.
+
+* All of the state required for $productName$ is stored directly in Kubernetes, eliminating the need for an additional database.
+* The $productName$ team has added extensive engineering efforts and integration testing to ensure optimal performance and scale of Envoy and Kubernetes.
+
+## For more information
+
+[Deploy $productName$ today](../../tutorials/getting-started) and join the community [Slack Channel](http://a8r.io/slack).
+
+Interested in learning more?
+
+* [Why did we start building $productName$?](https://blog.getambassador.io/building-ambassador-an-open-source-api-gateway-on-kubernetes-and-envoy-ed01ed520844)
+* [$productName$ Architecture overview](../../topics/concepts/architecture)
diff --git a/docs/edge-stack/latest/aes-pages.yml b/docs/edge-stack/latest/aes-pages.yml
new file mode 100644
index 000000000..bd03e5c39
--- /dev/null
+++ b/docs/edge-stack/latest/aes-pages.yml
@@ -0,0 +1,24 @@
+# AES pages should be represented in a yaml array with the pathnames as the value
+# Ex:
+# - /docs
+# - /reference
+#
+
+/topics/using/filters/
+/topics/using/filters/oauth2
+/topics/using/filters/jwt
+/topics/using/filters/external
+/topics/using/filters/plugin
+/topics/using/edgectl/
+/topics/using/edgectl/edge-control
+/topics/using/edgectl/edge-control-in-ci
+/topics/using/edgectl/service-preview-install
+/topics/using/edgectl/service-preview-reference
+/topics/using/edgectl/service-preview-tutorial
+/topics/using/dev-portal
+/topics/using/edge-policy-console
+/topics/using/rate-limits/rate-limits/
+/topics/running/aes-redis
+/topics/running/aes-extensions/
+/topics/running/aes-extensions/authentication
+/topics/running/aes-extensions/ratelimit
diff --git a/docs/edge-stack/latest/api-gateway-pages.yml b/docs/edge-stack/latest/api-gateway-pages.yml
new file mode 100644
index 000000000..b9010fdbc
--- /dev/null
+++ b/docs/edge-stack/latest/api-gateway-pages.yml
@@ -0,0 +1,72 @@
+# API Gateway pages should be represented in a yaml array with the pathnames as the value
+# Ex:
+# - /docs
+# - /reference
+#
+- /docs/dev-guide/canary-release-concepts
+- /docs/dev-guide/test-in-prod
+- /docs/guides/
+- /reference/add_request_headers
+- /reference/add_response_headers
+- /reference/ambassador-with-aws
+- /reference/canary
+- /reference/circuit-breakers
+- /reference/configuration
+- /reference/core/ambassador
+- /reference/core/crds
+- /reference/core/ingress-controller
+- /reference/core/load-balancer
+- /reference/core/resolvers
+- /reference/core/tls
+- /reference/cors
+- /reference/diagnostics
+- /reference/gzip
+- /reference/headers
+- /reference/host
+- /reference/host-crd
+- /reference/ambassadormappings
+- /reference/modules
+- /reference/prefix_regex
+- /reference/rate-limits
+- /reference/redirects
+- /reference/remove_request_headers
+- /reference/remove_response_headers
+- /reference/retries
+- /reference/rewrites
+- /reference/running
+- /reference/services/auth-service
+- /reference/services/log-service
+- /reference/services/rate-limit-service
+- /reference/services/services
+- /reference/services/tracing-service
+- /reference/shadowing
+- /reference/statistics
+- /reference/tcpmappings
+- /reference/timeouts
+- /reference/tls/cleartext-redirection
+- /reference/tls/client-cert-validation
+- /reference/tls/mtls
+- /reference/tls/origination
+- /user-guide/auth-tutorial
+- /user-guide/bare-metal
+- /user-guide/cd-declarative-gitops
+- /user-guide/cert-manager
+- /user-guide/consul
+- /user-guide/early-access
+- /user-guide/gitops-ambassador
+- /user-guide/grpc
+- /user-guide/helm
+- /user-guide/install-ambassador-oss
+- /user-guide/knative
+- /user-guide/linkerd2
+- /user-guide/monitoring
+- /user-guide/rate-limiting
+- /user-guide/rate-limiting-tutorial
+- /user-guide/security
+- /user-guide/sni
+- /user-guide/tls-termination
+- /user-guide/tracing-tutorial
+- /user-guide/tracing-tutorial-datadog
+- /user-guide/tracing-tutorial-zipkin
+- /user-guide/websockets-ambassador
+- /user-guide/with-istio
diff --git a/docs/edge-stack/latest/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md b/docs/edge-stack/latest/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md
new file mode 100644
index 000000000..2e99bc239
--- /dev/null
+++ b/docs/edge-stack/latest/custom-resources/gateway-getambassador/v1alpha1/filter-apikey.md
@@ -0,0 +1,74 @@
+
+import Alert from '@material-ui/lab/Alert';
+
+# The **APIKey Filter** Type (v1alpha1)
+
+The `APIKey Filter` validates API Keys present in HTTP headers. The list of authorized API Keys is defined directly in a Secret.
+If an incoming request does not have the header specified by the `APIKey Filter` or it does not contain one of the key values
+configured by the `Filter` then the request is denied. For more information about how requests are matched to `Filter` resources and the order in which `Filters` are executed, please refer to the [FilterPolicy Resource][] documentation.
+
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+Filter is fil, so you can get filters using kubectl get filter or kubectl get fil.
+v1alpha1 FilterPolicies can only be reference v1alpha1 Filters.
+WebApplicationFirewall resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+WebApplicationFirewallPolicy resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 FilterPolicies can only be reference v3alpha1 Filters.
+v2 or later for the apiVersion in the Mapping resource. Previous versions do not support labels.
+ What's next?
+
+* Get started with authentication by [installing $AESproductName$](../../tutorials/getting-started/).
+
+* For more details see the [`External` filter](../../topics/using/filters) documentation.
diff --git a/docs/edge-stack/latest/howtos/external-dns.md b/docs/edge-stack/latest/howtos/external-dns.md
new file mode 100644
index 000000000..fd75f1b47
--- /dev/null
+++ b/docs/edge-stack/latest/howtos/external-dns.md
@@ -0,0 +1,126 @@
+import Alert from '@material-ui/lab/Alert';
+
+# ExternalDNS with $productName$
+
+[ExternalDNS](https://github.com/kubernetes-sigs/external-dns) configures your existing DNS provider to make Kubernetes resources discoverable via public DNS servers by getting resources from the Kubernetes API to create a list of DNS records.
+
+
+## Getting started
+
+### Prerequisites
+
+Before you begin, review [ExternalDNS repo's deployment instructions](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) to get information about supported DNS providers and steps to setup ExternalDNS for your provider. Each DNS provider has its own required steps, as well as annotations, arguments, and permissions needed for the following configuration.
+
+
+### Installation
+
+Configuration for a `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` is necessary for the ExternalDNS deployment to support compatibility with $productName$ and allow ExternalDNS to get hostnames from $productName$'s `Hosts`.
+
+The following configuration is an example configuring $productName$ - ExternalDNS integration with [AWS Route53](https://aws.amazon.com/route53/) as the DNS provider. Refer to the [ExternalDNS documentation](https://github.com/kubernetes-sigs/external-dns#deploying-to-a-cluster) for annotations and arguments for your DNS Provider.
+
+
+1. Create a YAML file named `externaldns-config.yaml`, and copy the following configuration into it:
+
+ apiGroups include "getambassador.io" following "networking.k8s.io", and that the resources include "hosts" after "ingresses".
+ istio-certs cannot be changed.
+ Mapping's service
+ element, or set up the Kubernetes Service resource for your upstream service to map port
+ 443. If you don't do one of these, connections to your upstream will hang — see the
+ "Configure Service Ports" section below for more information.
+ WebApplicationFirewall and WebApplicationFirewall resources, check their statuses to make sure that they were not rejected due to any configuration errors.
+ gateway.getambassador.io/v1alpha1. It is NOT backwards compatible with getambassador.io/v3alpha1 Filter and FilterPolicy resources. These are the next generation of CRD's that you can
+ progressively adopt over time. They provide stronger typings so that
+ feedback is given at apply time rather than runtime.
+ docs: custom-resources/gateway-getambassador/v1alpha1/filter
+
+ - title: getambassador.io/v3alpha1 Filter & FilterPolicy statuses
+ type: feature
+ body: >-
+ Filter and FilterPolicy resources for the getambassador.io/v3alpha1 version will now provide statuses when they are "Ready". If there are
+ configuration errors they will provide an error message with details about the configuration issues. This will help troubleshoot configuration issues.
+
+ docs: custom-resources/getambassador/v3alpha1/filter
+
+ - title: Upgrade to Envoy 1.27.2
+ type: feature
+ body: >-
+ This upgrades $productName$ to be built on Envoy v1.27.2 which provides security, performance and feature enhancements. You can read more about them here: Envoy Proxy 1.27.2 Release Notes
+ docs: https://www.envoyproxy.io/docs/envoy/v1.27.2/version_history/version_history
+
+ - title: Added support for RESOURCE_EXHAUSTED responses to grpc clients when rate limited
+ type: feature
+ body: >-
+ By default, $productName$ will return an UNAVAILABLE code when a request using gRPC is rate limited. The RateLimitService resource now exposes a new grpc.use_resource_exhausted_code field that when set to true, $productName$ will return a RESOURCE_EXHAUSTED gRPC code instead. Thanks to Jerome Froelich for contributing this feature!
+ docs: topics/using/running/aes-extensions/ratelimit
+
+ - title: Added support for setting specific Envoy runtime flags in the Module
+ type: feature
+ body: >-
+ Envoy runtime fields that were provided to mitigate the recent HTTP/2 rapid reset
+ vulnerability can now be configured via the Module resource so the configuration will
+ persist between restarts. This configuration is added to the Envoy bootstrap config, so
+ restarting Emissary is necessary after changing these fields for the configuration to take effect.
+ docs: topics/running/ambassador/#set-envoy-runtime-flags
+
+ - title: Update APIExt minimum TLS version
+ type: change
+ body: >-
+ APIExt would previously allow for TLS 1.0 connections. We have updated it to now only use a minimum TLS version of 1.3 to resolve security concerns.
+ docs: https://www.tenable.com/plugins/nessus/104743
+
+ - title: Shipped Helm chart v8.9.0
+ type: change
+ body: >-
+ - Update default image to $productName$ v3.9.0. mappingSelector 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 v3alpha1 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 v3alpha1 Mappings. For users who may have this issue, please
+ be sure to re-apply any v3alpha1 Mappings in order to update the stored v2 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. ExternalFilter now supports configuring a CA certificate and/or client certificate via the new tlsConfig 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 insteadOfRedirect.filters 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 onDeny=continue 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: Envoy Proxy 1.25.4 Release Notes
+ 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. nodeSelector, tolerations and affinity on the Ambassador Agent. Thanks to Philip Panyukov. KubernetesEndpointResolver & ConsulResolver apiVersions to getambassador.io/v3alpha1
+
+ 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.authService 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 Module resource fails validation when setting the ambassador_id after upgrading to getambassador.io/v3alpha1.TracingService.spec.driver=opentelemetry to export traces in the otlp format./ready 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).AMBASSADOR_READY_PORT and enable access log using AMBASSADOR_READY_LOG 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.Host.hostname=example.com:8500). 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.ExternalFilter to communicate using gRPC with TLS would fail due to $productName$ trying to connect via cleartext. This has been fixed so that setting ExternalFilter.spec.tls=true $productName$ will talk to the external filter using TLS. startupProbes on the $productName$ deployment.podSecurityPolicy 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:TracingService. The recommended upgrade path is to leverage a supported Tracing driver such as Zipkin and use the Open Telemetry Collector to collect and forward Observabity data to LightStep. A guide for this can be found here: Distributed Tracing with Open Telemetry and LightStep.span is named. Prior to Envoy 1.24 it would always set the span name to the cluster.name. The expected behavior from Envoy was that if provided an alt_stat_name then use it else fallback to cluster.name.
+
+ 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 getambassador.io/v1 apiVersion has been re-introduced, in order to facilitate smoother migrations from $productName$ 1.y. Previously, in order to make migrations possible, an "unserved" v1 version was declared to Kubernetes, but was unsupported by $productName$. That unserved v1 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 v1 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 Mapping. 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:AMBASSADOR_HEALTHCHECK_BIND_ADDRESS: The address to bind the healthcheck server to.AMBASSADOR_HEALTHCHECK_BIND_PORT: The port to bind the healthcheck server to.AMBASSADOR_HEALTHCHECK_IP_FAMILY: The IP family to use for the healthcheck server.clientSessionMaxIdle, 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 AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED 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 Filter 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 proto: http. Now, adding supported tracing headers (b3, etc...) to the spec.allowed_request_headers 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 postLogoutRedirectURI to your Oauth2 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 https:{{host}}/.ambassador/oauth2/post-logout-redirect. Upon logout
+ $productName$ will redirect to the custom URI which will then redirect to the URI you have defined in postLogoutRedirectURI.
+ docs: topics/using/filters/oauth2
+
+ - title: Add support for Host resources using secrets from different namespaces
+ type: feature
+ body: >-
+ Previously the Host resource could only use secrets that are in the namespace as the
+ Host. The tlsSecret field in the Host has a new subfield namespace 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 AMBASSADOR_EDS_BYPASS to true to bypass EDS handling of endpoints and have endpoints be
+ inserted to clusters manually. This can help resolve with 503 UH caused by certification rotation relating to
+ a delay between EDS + CDS. The default is false.
+ docs: topics/running/environment/#ambassador_eds_bypass
+
+ - title: Add support for config change batch window before reconfiguring Envoy
+ type: feature
+ body: >-
+ The AMBASSADOR_RECONFIG_MAX_DELAY 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 custom_tags in the
+ TracingService. Trace tags can be set based on
+ literal values, environment variables, or request headers. The existing tag_headers field is now deperacated. If both tag_headers and custom_tags are set then tag_headers will be ignored.
+ (Thanks to Paul!)
+ 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
+ RateLimitService resource now exposes the
+ failure_mode_deny
+ option. Set failure_mode_deny: true, 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 Hosts are associated with Mappings and how Listeners are associated with Hosts. There was a bug with label
+ selectors that was causing resources that configure a selector 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 all labels required by
+ their selector are present. This brings the mappingSelector/selector fields in-line with how label selectors are used
+ in Kubernetes. To avoid unexpected behavior after the upgrade, add all labels that Hosts/Listeners have in their
+ mappingSelector/selector to Mappings/Hosts you want to associate with them. You can opt-out of the new behavior
+ by setting the environment variable DISABLE_STRICT_LABEL_SELECTORS to "true" (default: "false").
+ (Thanks to Filip Herceg and Joe Andaverde!).
+ 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 stats_name for the TracingService, RateLimitService
+ or the AuthService would have no affect because it was not being properly passed to the Envoy cluster
+ config. This has been fixed and the alt_stats_name field in the cluster config is now set correctly.
+ (Thanks to Paul!).
+
+ - title: Diagnostics stats properly handles parsing envoy metrics with colons
+ type: bugfix
+ body: >-
+ If a Host or TLSContext contained a hostname with a : when using the
+ diagnostics endpoints ambassador/v0/diagd 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 TCPMapping that uses SNI,
+ instead of using the hostname glob in the TCPMapping, uses the hostname glob
+ in the Host 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 TCPMapping that terminates TLS
+ must have a corresponding Host that it can take the TLS configuration from.
+ This was semi-intentional, but didn't make much sense. You can now use a
+ TLSContext without a Hostas in $productName$ 1.y releases, or a
+ Host with or without a TLSContext 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
+ TCPMapping cannot be used on the same port that HTTP is served on, even if
+ TLS+SNI would make this possible. $productName$ now allows TCPMappings to be
+ used on the same Listener port as HTTP Hosts, as long as that
+ Listener 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 Filter has been added to support validating APIKey's on incoming requests.The new APIKeyFilter when applied with a FilterPolicy will check to
+ see if the incoming requests has a valid API Key in the request header. $productName$ uses Kubernetes Secret'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 APIKeyFilter.
+ - 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 AES_REDIS_EXPERIMENTAL_DRIVER_ENABLED=true to enable the experimental feature. Most of the standard Redis configuration fields (e.g.REDIS_*) can be used with the driver.
+ However, due to the drivers better connection handling the new driver no longer supports setting REDIS_SURGE_LIMIT_INTERVAL, REDIS_SURGE_LIMIT_AFTER, REDIS_SURGE_POOL_SIZE, REDIS_SURGE_POOL_DRAIN_INTERVAL and these will be ignored.
+
+ Note: Other $productName$ features such as the RateLimitService 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 protocol_version field is not set or set to an invalid value then it will automatically get upgraded protocol_version: v3.
+
+ This matches the existing behavior that was introduced in $productName$ v3.0.0 for the AuthService. For new installs a valid RateLimitService 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 .yaml files, the Module resource enables serving remote client requests to the :8877/ambassador/v0/diag/ 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 (/debug/pprof/profile) and tracing (/debug/pprof/trace). Also add additional endpoints serving the command line running (/debug/pprof/cmdline) and program counters (/debug/pprof/symbol) for the sake of completeness.
+ - title: Correct cookies for mixed HTTP/HTTPS OAuth2 origins
+ type: bugfix
+ body: >-
+ When an OAuth2 filter sets cookies for a protectedOrigin, it should set a cookie's "Secure" flag to true for https:// origins and false for http:// 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 OAuth2 filter with multiple protectedOrigins 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 OAuth2 filter's known endpoints /.ambassador/oauth2/logout and /.ambassador/oauth2/multicookie 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 404 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: Envoy Proxy 1.22.0 Release Notes
+
+ 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:
+
+ - 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 LogServices and External Filters are working properly by setting protocol_version: "v3".
+
+ If protocol_version is not specified in 3.Y, the default value of v2 will cause an error to be posted and a static response will be returned. Therefore, you must set it to protocol_version: v3. If upgrading from a previous version, you will want to set it to v3 and ensure it is working before upgrading to Emissary-ingress 3.Y. The default value for protocol_version remains v2 in the getambassador.io/v3alpha1 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 443 because the alt-svc 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 Host or TLSContext contained a hostname with a : then when using the
+ diagnostics endpoints ambassador/v0/diagd 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 Host or TLSContext contained a hostname with a : then when using the diagnostics endpoints ambassador/v0/diagd 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 Host resource could only use secrets that are in the namespace as the
+ Host. The tlsSecret field in the Host has a new subfield namespace 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 AMBASSADOR_EDS_BYPASS to true to bypass EDS handling of endpoints and have endpoints be
+ inserted to clusters manually. This can help resolve with 503 UH caused by certification rotation relating to
+ a delay between EDS + CDS. The default is false.
+ 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 stats_name for the TracingService, RateLimitService
+ or the AuthService would have no affect because it was not being properly passed to the Envoy cluster
+ config. This has been fixed and the alt_stats_name field in the cluster config is now set correctly.
+ (Thanks to Paul!)
+
+ - title: Diagnostics stats properly handles parsing envoy metrics with colons
+ type: bugfix
+ body: >-
+ If a Host or TLSContext contained a hostname with a : when using the
+ diagnostics endpoints ambassador/v0/diagd 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 TCPMapping that uses SNI,
+ instead of using the hostname glob in the TCPMapping, uses the hostname glob
+ in the Host 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 TCPMapping that terminates TLS
+ must have a corresponding Host that it can take the TLS configuration from.
+ This was semi-intentional, but didn't make much sense. You can now use a
+ TLSContext without a Hostas in $productName$ 1.y releases, or a
+ Host with or without a TLSContext 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
+ TCPMapping cannot be used on the same port that HTTP is served on, even if
+ TLS+SNI would make this possible. $productName$ now allows TCPMappings to be
+ used on the same Listener port as HTTP Hosts, as long as that
+ Listener 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 OAuth2 filter sets cookies for a protectedOrigin, it
+ should set a cookie's "Secure" flag to true for https:// origins and false
+ for http:// 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 OAuth2 filter with multiple protectedOrigins 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 OAuth2 filter's known endpoints /.ambassador/oauth2/logout
+ and /.ambassador/oauth2/multicookie 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 zipkin
+ 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 does not support internal
+ redirects, 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 gdbm, pip, smtplib, and sqlite packages, as they are unused.
+
+ - title: CORS now happens before auth
+ type: bugfix
+ body: >-
+ When CORS is specified (either in a Mapping or in the Ambassador
+ Module), 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 Mappings that have the same
+ metadata.name 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 Mappings 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 TracingService to specify
+ collector_endpoint_version: HTTP_JSON_V1 when using xDS v3 to configure Envoy
+ (which has been the default since $productName$ 1.14.0). The HTTP_JSON_V1
+ value configures Envoy to speak to Zipkin using Zipkin's old API-v1, while the
+ HTTP_JSON value configures Envoy to speak to Zipkin using Zipkin's new
+ API-v2. In previous versions of $productName$ it was only possible to use
+ HTTP_JSON_V1 when explicitly setting the
+ AMBASSADOR_ENVOY_API_VERSION=V2 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 AuthService 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 protocol_version field on the External Filter is explicitly set to v3.
+ docs: topics/using/filters/external
+
+ - title: Allow setting propagation modes for Lightstep tracing
+ type: feature
+ body: >-
+ It is now possible to set propagation_modes in the
+ TracingService config when using lightstep as the driver.
+ (Thanks to Paul!)
+ 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 Envoy's Certificate Revocation lists.
+ 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 LogService would always have $productName$ communicate with the
+ external log service using the envoy.service.accesslog.v2.AccessLogService
+ API. It is now possible for the LogService to specify
+ protocol_version: v3 to use the newer
+ envoy.service.accesslog.v3.AccessLogService API instead. This functionality
+ is not available if you set the AMBASSADOR_ENVOY_API_VERSION=V2 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
+ AMBASSADOR_FORCE_SECRET_VALIDATION=true 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 AMBASSADOR_ENVOY_API_VERSION 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 AMBASSADOR_ENVOY_API_VERSION 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
+ AGENT_CONFIG_RESOURCE_NAME 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 ambassador_log_level{label="debug"}
+ 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 Fabrice!)
+ 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 preserve_servers in Ambassador Edge Stack's
+ DevPortal 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 AMBASSADOR_ENVOY_API_VERSION 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
+ clientAuthentication.method=jwtAssertion 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 ifRequestHeader selector (in a
+ FilterPolicy, OAuth2 Filter useSessionCookies, or OAuth2 Filter
+ insteadOfRedirect) without a value or valueRegex
+ would erroneously behave as if valueRegex='^$', rather than performing a
+ simple presence check.
+ docs: custom-resources/getambassador/v3alpha1/filterpolicy
+
+ - title: Fix support for for v2 Mappings with CORS
+ type: bugfix
+ body: >-
+ Ambassador Edge Stack 2.1.1 generated invalid Envoy configuration for
+ getambassador.io/v2 Mappings that set
+ spec.cors.origins to a string rather than a list of strings; this has been
+ fixed, and these Mappings 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 weight of Mapping 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 Mapping that is not part of a canary group, but that has a
+ weight less than 100, will be correctly configured to receive all
+ traffic as if the weight 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 rewrite: "" in a Mapping 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 Mapping that uses the host_redirect field is now properly discovered and used. Thanks
+ to Gabriel Féron 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: >-
+ Mappings with DNS wildcard hostname will now be correctly
+ matched with Hosts. Previously, the case where both the Host
+ and the Mapping 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 ambassador Module sets a global default for
+ add_request_headers, add_response_headers,
+ remove_request_headers, or remove_response_headers, it is often
+ desirable to be able to turn off that setting locally for a specific Mapping.
+ For several releases this has not been possible for Mappings 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 Mapping
+ spec.error_response_overrides body.text_format to an empty
+ string or body.json_format 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 getambassador.io/config 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: >-
+ Ambassador Edge Stack 2.1.1 is not recommended; upgrade to 2.1.2 instead.
+
+ - 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 AMBASSADOR_ENVOY_API_VERSION 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 Filters,
+ FilterPolicies, and RateLimits that were created as
+ v3alpha1 (but correctly paid attention to them if they were created as
+ v2 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: >-
+ Ambassador Edge Stack 2.1.0 is not recommended; upgrade to 2.1.2 instead.
+
+ - 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 AMBASSADOR_ENVOY_API_VERSION 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 getambassador.io/v2 CRDs, to simplify migration from $productName$
+ 1.X. Note: it is important to read the migration
+ documentation 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 (Filter, FilterPolicy, and RateLimit)
+ will now be validated for correct syntax by Kubernetes itself. This means that kubectl apply
+ 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
+ Mappings had the same prefix ("canary"ing multiple
+ Mappings 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 JWT Filter), 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 circuit_breakers for AuthServices,
+ exactly the same as for Mappings and TCPMappings. This makes it
+ possible to configure your AuthService 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 JWT Filter) it logs (at the info 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 error_response_overrides
+ 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 Host CRD now correctly supports the mappingSelector
+ element, as documented. As a transition aid, selector is a synonym for
+ mappingSelector; a future version of $productName$ will remove the
+ selector 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
+ Slack 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 x.getambassador.io/v3alpha1 API version has become the
+ getambassador.io/v3alpha1 API version. The Ambassador-
+ prefixes from x.getambassador.io/v3alpha1 resources have been
+ removed for ease of migration. Note that getambassador.io/v3alpha1
+ is the only supported API version for 2.0.4 — full support for
+ getambassador.io/v2 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 getambassador.io/v3alpha1 API version and the published chart
+ and manifests have been updated to support Kubernetes 1.22. Thanks to
+ Mohit Sharma 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 dns_type between strict_dns and
+ logical_dns in a Mapping 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 respect_dns_ttl to true to force the
+ DNS refresh rate for a Mapping 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 buffer_limit_bytes in the ambassador
+ Module 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 l7Depth element of the Listener 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 developer preview. 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 Slack 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 AES_LOG_LEVEL now also sets the log level for the diagd 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 dns_type in the AmbassadorMapping 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 DOCKER_BUILDKIT=0 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 developer preview. 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 Slack 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 allow_chunked_length 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 ambex-#.json) in /ambassador/snapshots. The number of snapshots is controlled by the AMBASSADOR_AMBEX_SNAPSHOT_COUNT 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 developer preview. 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 Slack 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 AmbassadorMapping 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 stats_prefix element of the AmbassadorListener CRD now determines the prefix of HTTP statistics emitted for a specific AmbassadorListener.
+ type: feature
+ docs: topics/running/listener
+
+ - title: Configurable statistics names
+ body: The optional stats_name element of AmbassadorMapping, AmbassadorTCPMapping, AuthService, LogService, RateLimitService, and TracingService now sets the name under which cluster statistics will be logged. The default is the service, with non-alphanumeric characters replaced by underscores.
+ type: feature
+ docs: topics/running/statistics
+
+ - title: Configurable Dev Portal fetch timeout
+ type: bugfix
+ body: The AmbassadorMapping resource can now specify docs.timeout_ms 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 k8s.io/klog/v2 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 AMBASSADOR_AMBEX_NO_RATELIMIT to true 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 false, 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 maxStale field is now supported in in the JWT Filter to configure how long $productname$ should cache OIDC responses for similar to the existing maxStale 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 developer preview. 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 Slack 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 x.getambassador.io/v3alpha1 for
+ configuration changes that are not backwards compatible with the 1.X family. API versions
+ getambassador.io/v0, getambassador.io/v1, and
+ getambassador.io/v2 are deprecated. Further details are available in the Major Changes
+ in 2.X 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 AmbassadorListener CRD defines where and how to listen for requests from the network, and which AmbassadorHost definitions should be used to process those requests. Note that the AmbassadorListener CRD is mandatory and consolidates all port configuration; see the AmbassadorListener documentation 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 AmbassadorMapping's host field is either an exact match or (with host_regex set) a regex,
+ the new hostname element is always a DNS glob. Use hostname instead of host 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 prune_unreachable_routes field is now automatic, which should reduce Envoy memory requirements for installations with many AmbassadorHosts
+ 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 AmbassadorHost can specify its requestPolicy.insecure.action independently of any other AmbassadorHost, 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, Noah Fontes!
+ 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 :authority header didn't match
+ type: bugfix
+
+ - title: Port configuration outside AmbassadorListener has been moved to AmbassadorListener
+ body: The TLSContext redirect_cleartext_from and AmbassadorHost requestPolicy.insecure.additionalPort elements are no longer supported. Use a AmbassadorListener 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 use_proxy_protocol element of the Ambassador Module is no longer supported, as it is now part of the AmbassadorListener resource (and can be set per-AmbassadorListener rather than globally).
+ type: change
+ docs: about/changes-2.x/#proxy-protocol-configuration
+
+ - title: Stricter rules for AmbassadorHost/AmbassadorMapping association
+ body: An AmbassadorMapping will only be matched with an AmbassadorHost if the AmbassadorMapping's host or the AmbassadorHost's selector (or both) are explicitly set, and match. This change can significantly improve $productName$'s memory footprint when many AmbassadorHosts are involved. Further details are available in the 2.0.0 Changes document.
+ docs: about/changes-2.x/#host-and-mapping-association
+ type: change
+
+ - title: AmbassadorHost or Ingress now required for TLS termination
+ body: An AmbassadorHost or Ingress resource is now required when terminating TLS -- simply creating a TLSContext is not sufficient. Further details are available in the AmbassadorHost CRD documentation.
+ 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 Major Changes in 2.X document.
+ type: change
+ docs: about/changes-2.x/#envoy-v3-api-by-default
+
+ - title: Module-based TLS no longer supported
+ body: The tls module and the tls field in the Ambassador module are no longer supported. Please use TLSContext 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 AMBASSADOR_FAST_RECONFIGURE 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 AGENT_SERVICE 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 edgectl CLI tool has been deprecated; please use the emissary-ingress 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 respect_dns_ttl 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 dns_type in Ambassador Mappings to use Envoy's
+ logical_dns resolution instead of the default strict_dns.
+ docs: topics/using/mappings/#dns-configuration-for-mappings
+
+ - title: Support configuring upstream buffer size
+ type: feature
+ body: >-
+ You can now set buffer_limit_bytes in the ambassador
+ Module 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 allow_chunked_length 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: >-
+ AMBASSADOR_ENVOY_API_VERSION now defaults to V3
+ 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 cors.origins
+ on the Mapping 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 ambex-#.json) in /ambassador/snapshots. The number of snapshots is controlled by the AMBASSADOR_AMBEX_SNAPSHOT_COUNT 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 AMBASSADOR_AMBEX_NO_RATELIMIT to true 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 false, 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 Mapping resource can now specify docs.timeout_ms 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 AMBASSADOR_LEGACY_MODE=true.
+
+ - 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 ambassador Module
+ config keys proper_case and preserve_external_request_id
+ 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
+ reject_requests_with_escaped_slashes 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.
diff --git a/docs/edge-stack/latest/topics/install/helm.md b/docs/edge-stack/latest/topics/install/helm.md
new file mode 100644
index 000000000..84c40d586
--- /dev/null
+++ b/docs/edge-stack/latest/topics/install/helm.md
@@ -0,0 +1,107 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Install with Helm
+
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ Install with Helm
+Helm, the package manager for Kubernetes, is the recommended way to install
+$productName$. Full details are in the [Helm instructions.](helm/)
+
+## Install with Kubernetes YAML
+Another way to install $productName$ if you are unable to use Helm is to
+directly apply Kubernetes YAML. See details in the
+[manual YAML installation instructions.](yaml-install).
+
+## Try the demo with Docker
+The Docker install will let you try the $productName$ locally in seconds,
+but is not supported for production workloads. [Try $productName$ on Docker.](docker/)
+
+## Upgrade or migrate to a newer version
+If you already have an existing installation of $AESproductName$ or
+$OSSproductName$, you can upgrade your instance. The [migration matrix](migration-matrix/)
+shows you how.
+
+## Container Images
+Although our installation guides will favor using the `docker.io` container registry,
+we publish $AESproductName$ and $OSSproductName$ releases to multiple registries.
+
+Starting with version 1.0.0, you can pull the aes image from any of the following registries:
+- `docker.io/datawire/`
+- `gcr.io/datawire/`
+
+We want to give you flexibility and independence from a hosting platform's uptime to support
+your production needs for $AESproductName$ or $OSSproductName$. Read more about
+[Running $productName$ in Production](../running).
+
+# What’s Next?
+$productName$ has a comprehensive range of [features](/features/) to
+support the requirements of any edge microservice. To learn more about how $productName$ works, along with use cases, best practices, and more,
+check out the [Welcome page](../../tutorials/getting-started/) or read the [$productName$
+Story](../../about/why-ambassador).
diff --git a/docs/edge-stack/latest/topics/install/migrate-to-3-alternate.md b/docs/edge-stack/latest/topics/install/migrate-to-3-alternate.md
new file mode 100644
index 000000000..d0b791a12
--- /dev/null
+++ b/docs/edge-stack/latest/topics/install/migrate-to-3-alternate.md
@@ -0,0 +1,36 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$ with a separate cluster
+
+You can upgrade from any version of $AESproductName$ or $OSSproductName$ to
+any version of either by installing the new version in a new Kubernetes cluster,
+then copying over configuration as needed. This is the way to be absolutely
+certain that each installation cannot affect the other: it is extremely safe,
+but is also significantly more effort.
+
+For example, to upgrade from some other version of $AESproductName$ or
+$OSSproductName$ to $productName$ $version$:
+
+1. Install $productName$ $version$ in a completely new cluster.
+
+2. **Create `Listener`s for $productName$ $version$.**
+
+ When $productName$ $version$ starts, it will not have any `Listener`s, and it will not
+ create any. You must create `Listener` resources by hand, or $productName$ $version$
+ will not listen on any ports.
+
+3. Copy the entire configuration from the $productName$ 1.X cluster to the $productName$
+ $version$ cluster. This is most simply done with `kubectl get -o yaml | kubectl apply -f -`.
+
+ This will create `getambassador.io/v2` resources in the $productName$ $version$ cluster.
+ $productName$ $version$ will translate them internally to `getambassador.io/v3alpha1`
+ resources.
+
+4. Each $productName$ instance has its own cluster, so you can test the new
+ instance without disrupting traffic to the existing instance.
+
+5. If you need to make changes, you can change the `getambassador.io/v2` resource, or convert the
+ resource you're changing to `getambassador.io/v3alpha1` by using `kubectl edit`.
+
+6. Once everything is working with both versions, transfer incoming traffic to the $productName$
+ $version$ cluster.
diff --git a/docs/edge-stack/latest/topics/install/migration-matrix.md b/docs/edge-stack/latest/topics/install/migration-matrix.md
new file mode 100644
index 000000000..ead43c6e0
--- /dev/null
+++ b/docs/edge-stack/latest/topics/install/migration-matrix.md
@@ -0,0 +1,48 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$
+
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AES_ACME_LEADER_DISABLE flag. This prevents
+ $productName$ $versionTwoX$ from trying to manage ACME, so that $productName$ 1.14 can
+ do it instead.
+ $productHelmName$ Helm chart for $productName$ $versionTwoX$.
+ Do not use the ambassador Helm chart.
+ Hosts you create use API version getambassador.io/v2,
+ so that they can be managed by $productName$ 1.14 as long as both installations are running.
+
+
+ This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`)
+ and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`.
+
+5. **Test!**
+
+ Your $productName$ $versionTwoX$ installation can support the `getambassador.io/v2`
+ configuration resources used by $productName$ 1.14, but you may need to make some
+ changes to the configuration, as detailed in the documentation on
+ [configuring $productName$ Communications](../../../../../../howtos/configure-communications)
+ and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1).
+
+ getambassador.io/v3alpha1 resource
+ with the same name as a getambassador.io/v2 resource or vice versa: only
+ one version can be stored at a time.emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 2.X.
+ Do not use the ambassador Helm chart.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 2.X.
+ Do not use the ambassador Helm chart.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $OSSproductName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $AESproductName$ $version$.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AES_ACME_LEADER_DISABLE flag. This prevents collisions in trying to manage
+ ACME.
+ Hosts you create use API version getambassador.io/v2,
+ so that they can be managed by $productName$ 1.14 as long as both installations are running.
+
+
+ This example requires that you know the hostname for the $productName$ Service (`$EMISSARY_HOSTNAME`)
+ and that you have created a TLS Secret for it in `$EMISSARY_TLS_SECRET`.
+
+5. **Test!**
+
+ Your $productName$ $versionTwoX$ installation can support the `getambassador.io/v2`
+ configuration resources used by $productName$ 1.14, but you may need to make some
+ changes to the configuration, as detailed in the documentation on
+ [configuring $productName$ Communications](../../../../../../howtos/configure-communications)
+ and [updating CRDs to `getambassador.io/v3alpha1`](../../../../convert-to-v3alpha1).
+
+ getambassador.io/v3alpha1 resource
+ with the same name as a getambassador.io/v2 resource or vice versa: only
+ one version can be stored at a time.emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $OSSproductName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AuthService or RateLimitService resources be present; see
+ below for more.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ Listener, deploying a simple service to test with, and setting up a Mapping to route requests from $productName$ to the demo service.
+ timeout_ms of the ambassador-edge-stack-auth AuthService defaults
+to a value of 5000 (five seconds). You will need to adjust this as well.
+
+AES_AUTH_TIMEOUT should always be around one second shorter than the timeout_ms of the AuthService to ensure Filter error responses make it to the client.
+
+The External Filter also have a timeout_ms field that must be set if a single Filter will take longer than five seconds.
+ambassador-redis-password instead
+ of providing the value directly.
+ AUTH without USERNAME and PASSWORD can result in various problems since AUTH does not
+ overwrite the basic Redis authentication behavior for systems outside of rate limit preview.
+all_methods and services are present, all_methods will be ignored.
+proper_case and header_case_overrides are mutually exclusive.ip_allow and ip_deny may be specified.xff_num_trusted_hops for Envoy to respect the change.
+Listener resources are required for a functioning
+ $productName$ installation!Listener.
+Host exists! If the
+ wildcard behavior is needed, a Host with a hostname of "*"
+ must be defined by the user.
+Listener will also be required for this example to
+be functional. Many examples of setting up `Host` and `Listener` are available in the
+[Configuring $productName$ to Communicate](../../../howtos/configure-communications) document.
+
+## Setting the `hostname`
+
+The `hostname` element tells $productName$ which hostnames to expect. `hostname` is a DNS glob,
+so all of the following are valid:
+
+- `host.example.com`
+- `*.example.com`
+- `host.example.*`
+
+The following are _not_ valid:
+
+- `host.*.com` -- Envoy supports only prefix and suffix globs
+- `*host.example.com` -- the wildcard must be its own element in the DNS name
+
+In all cases, the `hostname` is used to match the `:authority` header for HTTP routing.
+When TLS termination is active, the `hostname` is also used for SNI matching.
+
+## Controlling Association with `Mapping`s
+
+A `Mapping` will not be associated with a `Host` unless at least one of the following is true:
+
+- The `Mapping` specifies a `hostname` attribute that matches the `Host` in question.
+- The `Host` specifies a `mappingSelector` that matches the `Mapping`'s Kubernetes `label`s.
+
+> **Note:** The `mappingSelector` field is only configurable on `v3alpha1` CRDs. In the `v2` CRDs the equivalent field is `selector`.
+either `selector` or `mappingSelector` may be configured in the `v3alpha1` CRDs, but `selector` has been deprecated in favour of `mappingSelector`.
+
+If neither of the above is true, the `Mapping` will not be associated with the `Host` in
+question. This is intended to help manage memory consumption with large numbers of `Host`s and large
+numbers of `Mapping`s.
+
+If the `Host` specifies `mappingSelector` _and_ the `Mapping` specifies `hostname`, both must match
+for the association to happen.
+
+The `mappingSelector` is a Kubernetes [label selector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.25/#labelselector-v1-meta). For a `Mapping` to be associated with a `Host` that uses `mappingSelector`, then **all** labels
+required by the `mappingSelector` must be present on the `Mapping` in order for it to be associated with the `Host`.
+A `Mapping` may have additional labels other than those required by the `mappingSelector` so long as the required labels are present.
+
+**in 2.0, only `matchLabels` is supported**, for example:
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: minimal-host
+spec:
+ hostname: host.example.com
+ mappingSelector:
+ matchLabels:
+ examplehost: host
+```
+
+The above `Host` will associate with these `Mapping`s:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-label-match
+ labels:
+ examplehost: host # This matches the Host's mappingSelector.
+spec:
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-hostname-match
+spec:
+ hostname: host.example.com # This is an exact match of the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-hostname-glob-match
+spec:
+ hostname: '*.example.com' # This glob matches the Host's hostname too.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: mapping-with-both-matches
+ labels:
+ examplehost: host # This matches the Host's mappingSelector.
+spec:
+ hostname: '*.example.com' # This glob matches the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+```
+
+It will _not_ associate with any of these:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-wrong-label
+ labels:
+ examplehost: staging # This doesn't match the Host's mappingSelector.
+spec:
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-wrong-hostname
+spec:
+ hosname: 'bad.example.com' # This doesn't match the Host's hostname.
+ prefix: /httpbin/
+ service: http://httpbin.org
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: skip-mapping-still-wrong
+ labels:
+ examplehost: staging # This doesn't match the Host's mappingSelector,
+spec: # and if the Host specifies mappingSelector AND the
+ hostname: host.example.com # Mapping specifies hostname, BOTH must match. So
+ prefix: /httpbin/ # the matching hostname isn't good enough.
+ service: http://httpbin.org
+```
+
+Future versions of $productName$ will support `matchExpressions` as well.
+
+> **Note:** In $productName$ version `3.2`, a bug with how `Hosts` are associated with `Mappings` was fixed. The `mappingSelector` field in `Hosts` was not
+properly being enforced in prior versions. If any single label from the selector was matched then the `Host` would be associated with the `Mapping` instead
+of requiring all labels in the selector to be present. Additonally, if the `hostname` of the `Mapping` matched the `hostname` of the `Host` then they would be associated
+regardless of the configuration of `mappingSelector`.
+In version `3.2` this bug was fixed and a `Host` will only be associated with a `Mapping` if **all** labels required by the selector are present.
+This brings the `mappingSelector` field in-line with how label selectors are used throughout Kubernetes. To avoid unexpected behavior after the upgrade,
+add all labels that `Hosts` have in their `mappingSelector` to `Mappings` you want to associate with the `Host`. You can opt-out of this fix and return to the old
+`Mapping`/`Host` association behavior by setting the environment variable `DISABLE_STRICT_LABEL_SELECTORS` to `"true"` (default: `"false"`). A future version of
+$productName$ may remove the ability to opt-out of this bugfix.
+
+## Secure and insecure requests
+
+A **secure** request arrives via HTTPS; an **insecure** request does not. By default, secure requests will be routed and insecure requests will be redirected (using an HTTP 301 response) to HTTPS. The behavior of insecure requests can be overridden using the `requestPolicy` element of a `Host`:
+
+```yaml
+requestPolicy:
+ insecure:
+ action: insecure-action
+ additionalPort: insecure-port
+```
+
+The `insecure-action` can be one of:
+
+- `Redirect` (the default): redirect to HTTPS
+- `Route`: go ahead and route as normal; this will allow handling HTTP requests normally
+- `Reject`: reject the request with a 400 response
+
+```yaml
+requestPolicy:
+ insecure:
+ additionalPort: -1 # This is how to disable the default redirection from 8080.
+```
+
+Some special cases to be aware of here:
+
+- **Case matters in the actions:** you must use e.g. `Reject`, not `reject`.
+- The `X-Forwarded-Proto` header is honored when determining whether a request is secure or insecure. For more information, see "Load Balancers, the `Host` Resource, and `X-Forwarded-Proto`" below.
+- ACME challenges with prefix `/.well-known/acme-challenge/` are always forced to be considered insecure, since they are not supposed to arrive over HTTPS.
+- $AESproductName$ provides native handling of ACME challenges. If you are using this support, $AESproductName$ will automatically arrange for insecure ACME challenges to be handled correctly. If you are handling ACME yourself - as you must when running $OSSproductName$ - you will need to supply appropriate `Host` resources and `Mapping`s to correctly direct ACME challenges to your ACME challenge handler.
+
+## TLS settings
+
+The `Host` is responsible for high-level TLS configuration in $productName$. There are
+several settings covering TLS:
+
+### ACME support
+
+$AESproductName$ comes with built in support for automatic certificate
+management using the [ACME protocol](https://tools.ietf.org/html/rfc8555).
+
+It does this by using the `hostname` of a `Host` to request a certificate from
+the `acmeProvider.authority` using the `HTTP-01` challenge. After requesting a
+certificate, $AESproductName$ will then manage the renewal process automatically.
+
+The `acmeProvider` element of the `Host` configures the Certificate Authority
+$AESproductName$ will request the certificate from and the email address that the CA
+will use to notify about any lifecycle events of the certificate.
+
+```yaml
+acmeProvider:
+ authority: url-to-provider
+ email: email-of-registrant
+```
+
+**Notes on ACME Support:**
+
+- If the authority is not supplied, the Let’s Encrypt production environment is assumed.
+
+- In general, `email-of-registrant` is mandatory when using ACME: it should be
+ a valid email address that will reach someone responsible for certificate
+ management.
+
+- ACME stores certificates in Kubernetes secrets. The name of the secret can be
+ set using the `tlsSecret` element:
+
+ ```yaml
+ acmeProvider:
+ email: user@example.com
+ tlsSecret:
+ name: tls-cert
+ ```
+
+ if not supplied, a name will be automatically generated from the `hostname` and `email`.
+
+- $AESproductName$ uses the [`HTTP-01` challenge
+ ](https://letsencrypt.org/docs/challenge-types/) for ACME support:
+ - Does not require permission to edit DNS records
+ - The `hostname` must be reachable from the internet so the CA can check
+ `POST` to an endpoint in $AESproductName$.
+ - Wildcard domains are not supported.
+
+### `tlsSecret` enables TLS termination
+
+`tlsSecret` specifies a Kubernetes `Secret` is **required** for any TLS termination to occur. If ACME is enabled,
+it will set `tlsSecret`: in all other cases, TLS termination will not occur if `tlsSecret` is not specified.
+
+The following `Host` will configure $productName$ to read a `Secret` named
+`tls-cert` for a certificate to use when terminating TLS.
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: example-host
+spec:
+ hostname: host.example.com
+ acmeProvider:
+ authority: none
+ tlsSecret:
+ name: tls-cert
+```
+
+### `tlsContext` links to a `TLSContext` for additional configuration
+
+`tlsContext` specifies a [`TLSContext`](#) to use for additional TLS information. Note that you **must** still
+define `tlsSecret` for TLS termination to happen. It is an error to supply both `tlsContext` and `tls`.
+
+See the [TLS discussion](../tls) for more details.
+
+### `tls` allows manually providing additional configuration
+
+`tls` allows specifying most of the things a `TLSContext` can, inline in the `Host`. Note that you **must** still
+define `tlsSecret` for TLS termination to happen. It is an error to supply both `tlsContext` and `tls`.
+
+See the [TLS discussion](../tls) for more details.
+
+## Load balancers, the `Host` resource, and `X-Forwarded-Proto`
+
+In a typical installation, $productName$ runs behind a load balancer. The
+configuration of the load balancer can affect how $productName$ sees requests
+arriving from the outside world, which can in turn can affect whether $productName$
+considers the request secure or insecure. As such:
+
+- **We recommend layer 4 load balancers** unless your workload includes
+ long-lived connections with multiple requests arriving over the same
+ connection. For example, a workload with many requests carried over a small
+ number of long-lived gRPC connections.
+- **$productName$ fully supports TLS termination at the load balancer** with a single exception, listed below.
+- If you are using a layer 7 load balancer, **it is critical that the system be configured correctly**:
+ - The load balancer must correctly handle `X-Forwarded-For` and `X-Forwarded-Proto`.
+ - The `l7Depth` element in the [`Listener` CRD](../../running/listener) must be set to the number of layer 7 load balancers the request passes through to reach $productName$ (in the typical case, where the client speaks to the load balancer, which then speaks to $productName$, you would set `l7Depth` to 1). If `l7Depth` remains at its default of 0, the system might route correctly, but upstream services will see the load balancer's IP address instead of the actual client's IP address.
+
+It's important to realize that Envoy manages the `X-Forwarded-Proto` header such that it **always** reflects the most trustworthy information Envoy has about whether the request arrived encrypted or unencrypted. If no `X-Forwarded-Proto` is received from downstream, **or if it is considered untrustworthy**, Envoy will supply an `X-Forwarded-Proto` that reflects the protocol used for the connection to Envoy itself. The `l7Depth` element is also used when determining trust for `X-Forwarded-For`, and it is therefore important to set it correctly. Its default of 0 should always be correct when $productName$ is behind only layer 4 load balancers; it should need to be changed **only** when layer 7 load balancers are involved.
+
+### CRD specification
+
+The `Host` CRD is formally described by its protobuf specification. Developers who need access to the specification can find it [here](https://github.com/emissary-ingress/emissary/blob/release/v2.0/api/getambassador.io/v2/Host.proto).
diff --git a/docs/edge-stack/latest/topics/running/tls/cleartext-redirection.md b/docs/edge-stack/latest/topics/running/tls/cleartext-redirection.md
new file mode 100644
index 000000000..74fc88eeb
--- /dev/null
+++ b/docs/edge-stack/latest/topics/running/tls/cleartext-redirection.md
@@ -0,0 +1,91 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Cleartext support
+
+While most modern web applications choose to encrypt all traffic, there remain
+cases where supporting cleartext communications is important. $productName$ supports
+both forcing [automatic redirection to HTTPS](#http-https-redirection) and
+[serving cleartext](#cleartext-routing) traffic on a `Host`.
+
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+Hosts are defined, $productName$ enables HTTP->HTTPS redirection. You will
+ need to explicitly create a Host to enable cleartext communication at all.
+Listener and
+ Host CRDs work together to manage HTTP and HTTPS routing.
+ This document is meant as a quick reference to the Host resource: for a more complete
+ treatment of handling cleartext and HTTPS, see Configuring $productName$ Communications.
+requestPolicy; however, most real-world
+ usage of $productName$ will require defining the requestPolicy.Host documentation.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+tls setting and the tlsContext
+ setting on the same Host. The recommended setting is using the tls setting
+ unless you have multiple Hosts that need to share TLS configuration.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+TLSContext linkage is deprecated and will be removed
+ in a future version of $productName$; it is not recommended for new
+ configurations. Any other TLS configuration in the Host will override
+ this implict TLSContext link.
+tlsSecret must contain a valid TLS certificate.
+ If `AMBASSADOR_FORCE_SECRET_VALIDATION` is set and the Secret contains an invalid
+ certificate, $productName$ will reject the Secret and completely disable the
+ `Host`; see [**Certificates and Secrets**](#certificates-and-secrets) above.
+
+key-1 in the example) used in the Secret do not matter, so you can name them whatever helps you keep track of the associated API Keys.
+
+
+4. Create a [FilterPolicy resource][] to use the `Filter` created above
+
+ ```yaml
+ kubectl apply -f -<ambassador_xsrf.NAME.NAMESPACE cookie, and instead required you to use the ambassador_session.NAME.NAMESPACE cookie. The ambassador_session.NAME.NAMESPACE cookie should no longer be used for XSRF-protection purposes.
+labels require Mapping resources with apiVersion
+ getambassador.io/v2 or newer — if you're updating an old installation, check the
+ apiVersion!
+ kubectl get services,deployments quote to see their status.
+
+3. Generate the YAML for a `Mapping` to tell $productName$ to route all traffic inbound to the `/backend/` path to the `quote` Service.
+
+ In this step, we'll be using the Mapping Editor, which you can find in the service details view of your [Ambassador Cloud connected installation](#getting-a-license-from-ambassador-cloud).
+ Open your browser to https://app.getambassador.io/cloud/services/quote/details and click on **New Mapping**.
+
+ Default options are automatically populated. **Enable and configure the following settings**, then click **Generate Mapping**:
+ - **Path Matching**: `/backend/`
+ - **OpenAPI Docs**: `/.ambassador-internal/openapi-docs`
+
+ 
+
+ Whether you decide to automatically push the change to Git for this newly create Mapping resource or not, the resulting Mapping should be similar to the example below.
+
+ **Apply this YAML to your target cluster now.**
+
+ ```yaml
+ kubectl apply -f - < What's next?
+
+Explore some of the popular tutorials on $productName$:
+
+* [Intro to Mappings](../../topics/using/intro-mappings/): declaratively routes traffic from
+the edge of your cluster to a Kubernetes service
+* [Host resource](../../topics/running/host-crd/): configure a hostname and TLS options for your ingress.
+* [Rate Limiting](../../topics/using/rate-limits/rate-limits/): create policies to control sustained traffic loads
+
+$productName$ has a comprehensive range of [features](/features/) to
+support the requirements of any edge microservice.
+
+To learn more about how $productName$ works, read the [$productName$ Story](../../about/why-ambassador).
diff --git a/docs/edge-stack/latest/tutorials/gs-tabs.js b/docs/edge-stack/latest/tutorials/gs-tabs.js
new file mode 100644
index 000000000..6cbeab1bc
--- /dev/null
+++ b/docs/edge-stack/latest/tutorials/gs-tabs.js
@@ -0,0 +1,132 @@
+import AppBar from '@material-ui/core/AppBar';
+import Box from '@material-ui/core/Box';
+import Tab from '@material-ui/core/Tab';
+import Tabs from '@material-ui/core/Tabs';
+import { makeStyles } from '@material-ui/core/styles';
+import PropTypes from 'prop-types';
+import React from 'react';
+
+import CodeBlock from '../../../../../src/components/CodeBlock';
+import Icon from '../../../../../src/components/Icon';
+
+function TabPanel(props) {
+ const { children, value, index, ...other } = props;
+
+ return (
+ cloud-connect-token that is used to connect your
+ cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ cloud-connect-token that is used to connect your
+ cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ cloud-connect-token that is used to connect
+ your cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ edgectl is
+ identical to the Kubernetes YAML procedure.
+ cloud-connect-token that is used to connect
+ your cluster to your Ambassador Cloud account.
+ $TOKEN
+ with your token:
+ v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+v1alpha1 Filters can only be referenced from v1alpha1 FilterPolicies.
+Filter is fil, so you can get filters using kubectl get filter or kubectl get fil.
+v1alpha1 FilterPolicies can only be reference v1alpha1 Filters.
+WebApplicationFirewall resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+WebApplicationFirewallPolicy resource was introduced more recently than the Filter and FilterPolicy resources, and does not have an older getambassador.io/v3alpha1 CRD version
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 Filters can only be referenced from v3alpha1 FilterPolicies.
+v3alpha1 FilterPolicies can only be reference v3alpha1 Filters.
+gateway.getambassador.io/v1alpha1. It is NOT backwards compatible with getambassador.io/v3alpha1 Filter and FilterPolicy resources. These are the next generation of CRD's that you can
+ progressively adopt over time. They provide stronger typings so that
+ feedback is given at apply time rather than runtime.
+ docs: custom-resources/gateway-getambassador/v1alpha1/filter
+
+ - title: getambassador.io/v3alpha1 Filter & FilterPolicy statuses
+ type: feature
+ body: >-
+ Filter and FilterPolicy resources for the getambassador.io/v3alpha1 version will now provide statuses when they are "Ready". If there are
+ configuration errors they will provide an error message with details about the configuration issues. This will help troubleshoot configuration issues.
+
+ docs: custom-resources/getambassador/v3alpha1/filter
+
+ - title: Upgrade to Envoy 1.27.2
+ type: feature
+ body: >-
+ This upgrades $productName$ to be built on Envoy v1.27.2 which provides security, performance and feature enhancements. You can read more about them here: Envoy Proxy 1.27.2 Release Notes
+ docs: https://www.envoyproxy.io/docs/envoy/v1.27.2/version_history/version_history
+
+ - title: Added support for RESOURCE_EXHAUSTED responses to grpc clients when rate limited
+ type: feature
+ body: >-
+ By default, $productName$ will return an UNAVAILABLE code when a request using gRPC is rate limited. The RateLimitService resource now exposes a new grpc.use_resource_exhausted_code field that when set to true, $productName$ will return a RESOURCE_EXHAUSTED gRPC code instead. Thanks to Jerome Froelich for contributing this feature!
+ docs: topics/using/running/aes-extensions/ratelimit
+
+ - title: Added support for setting specific Envoy runtime flags in the Module
+ type: feature
+ body: >-
+ Envoy runtime fields that were provided to mitigate the recent HTTP/2 rapid reset
+ vulnerability can now be configured via the Module resource so the configuration will
+ persist between restarts. This configuration is added to the Envoy bootstrap config, so
+ restarting Emissary is necessary after changing these fields for the configuration to take effect.
+ docs: topics/running/ambassador/#set-envoy-runtime-flags
+
+ - title: Update APIExt minimum TLS version
+ type: change
+ body: >-
+ APIExt would previously allow for TLS 1.0 connections. We have updated it to now only use a minimum TLS version of 1.3 to resolve security concerns.
+ docs: https://www.tenable.com/plugins/nessus/104743
+
+ - title: Shipped Helm chart v8.9.0
+ type: change
+ body: >-
+ - Update default image to $productName$ v3.9.0. insteadOfRedirect) without a value or valueRegex
would erroneously behave as if valueRegex='^$', rather than performing a
simple presence check.
- docs: topics/using/filters/#filterpolicy-definition
+ docs: custom-resources/getambassador/v3alpha1/filterpolicy
- title: Fix support for for v2 Mappings with CORS
type: bugfix
diff --git a/docs/edge-stack/pre-release/topics/install/migration-matrix.md b/docs/edge-stack/pre-release/topics/install/migration-matrix.md
index 21253feaf..ead43c6e0 100644
--- a/docs/edge-stack/pre-release/topics/install/migration-matrix.md
+++ b/docs/edge-stack/pre-release/topics/install/migration-matrix.md
@@ -25,22 +25,24 @@ See the [instructions on updating $OSSproductName$](../../../../../emissary/$oss
| If you're running. | You can upgrade to |
|-----------------------------------------|----------------------------------------------------------------------------------|
+| $AESproductName$ 3.8.X | [$AESproductName$ $version$](../upgrade/helm/edge-stack-3.8/edge-stack-3.X) |
| $AESproductName$ 3.7.X | [$AESproductName$ $version$](../upgrade/helm/edge-stack-3.7/edge-stack-3.X) |
| $AESproductName$ $versionTwoX$ | [$AESproductName$ $version$](../upgrade/helm/edge-stack-2.5/edge-stack-3.X) |
| $AESproductName$ 2.4.X | [$AESproductName$ $versionTwoX$](../upgrade/helm/edge-stack-2.4/edge-stack-2.X) |
| $AESproductName$ 2.0.X | [$AESproductName$ $versionTwoX$](../upgrade/helm/edge-stack-2.0/edge-stack-2.X) |
| $AESproductName$ $versionOneX$ | [$AESproductName$ $versionTwoX$](../upgrade/helm/edge-stack-1.14/edge-stack-2.X) |
| $AESproductName$ prior to $versionOneX$ | [$AESproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) |
-| $OSSproductName$ $ossVersion$ | [$AESproductName$ $version$](../upgrade/helm/emissary-3.8/edge-stack-3.X) |
+| $OSSproductName$ $ossVersion$ | [$AESproductName$ $version$](../upgrade/helm/emissary-3.9/edge-stack-3.X) |
## If you installed $AESproductName$ manually by applying YAML
| If you're running. | You can upgrade to |
|-----------------------------------------|----------------------------------------------------------------------------------|
+| $AESproductName$ 3.8.X | [$AESproductName$ $version$](../upgrade/yaml/edge-stack-3.8/edge-stack-3.X) |
| $AESproductName$ 3.7.X | [$AESproductName$ $version$](../upgrade/yaml/edge-stack-3.7/edge-stack-3.X) |
| $AESproductName$ $versionTwoX$ | [$AESproductName$ $version$](../upgrade/yaml/edge-stack-2.5/edge-stack-3.X) |
| $AESproductName$ 2.4.X | [$AESproductName$ $versionTwoX$](../upgrade/yaml/edge-stack-2.4/edge-stack-2.X) |
| $AESproductName$ 2.0.X | [$AESproductName$ $versionTwoX$](../upgrade/yaml/edge-stack-2.0/edge-stack-2.X) |
| $AESproductName$ $versionOneX$ | [$AESproductName$ $versionTwoX$](../upgrade/yaml/edge-stack-1.14/edge-stack-2.X) |
| $AESproductName$ prior to $versionOneX$ | [$AESproductName$ $versionOneX$](../../../../1.14/topics/install/upgrading) |
-| $OSSproductName$ $ossVersion$ | [$AESproductName$ $version$](../upgrade/yaml/emissary-3.8/edge-stack-3.X) |
+| $OSSproductName$ $ossVersion$ | [$AESproductName$ $version$](../upgrade/yaml/emissary-3.9/edge-stack-3.X) |
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-2.5/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-2.5/edge-stack-3.X.md
index acbc1e4a8..e0d02c0ec 100644
--- a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-2.5/edge-stack-3.X.md
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-2.5/edge-stack-3.X.md
@@ -90,7 +90,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou
As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
-$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
+$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
## Migration Steps
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.4/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.4/edge-stack-3.X.md
index ef874e5d2..c988b1123 100644
--- a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.4/edge-stack-3.X.md
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.4/edge-stack-3.X.md
@@ -90,7 +90,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou
As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
-$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
+$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
## Migration Steps
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.7/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.7/edge-stack-3.X.md
index 9876747d8..ab9bbf890 100644
--- a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.7/edge-stack-3.X.md
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.7/edge-stack-3.X.md
@@ -90,7 +90,7 @@ You can refer to the [Major changes in $productName$ 3.x](../../../../../../abou
As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
-$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
+$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
## Migration Steps
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.8/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.8/edge-stack-3.X.md
new file mode 100644
index 000000000..141473272
--- /dev/null
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/helm/edge-stack-3.8/edge-stack-3.X.md
@@ -0,0 +1,152 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrade $productName$ 3.8.X to $productName$ $version$ (Helm)
+
+LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $productName$ 3.X.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $OSSproductName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ $productHelmName$ Helm chart to install $AESproductName$ $version$.
+ LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read before upgrading.
-$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
+$productName$ 3.4 is based on Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
## Migration Steps
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.4/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.4/edge-stack-3.X.md
index d48526638..d342f175b 100644
--- a/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.4/edge-stack-3.X.md
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.4/edge-stack-3.X.md
@@ -23,7 +23,7 @@ versions is straightforward.
As of $productName$ 3.4.Z, the LightStep tracing driver is no longer supported. To ensure you do not drop any tracing data, be sure to read below before upgrading.
-$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
+$productName$ 3.4 has been upgraded from Envoy 1.23 to Envoy 1.24.1 which removed support for the `LightStep` tracing driver. The team at LightStep and the maintainers of Envoy-Proxy recommend that users instead leverage the OpenTelemetry Collector to send tracing information to LightStep. We have written a guide which can be found here Distributed Tracing with OpenTelemetry and Lightstep that outlines how to set this up. **It is important that you follow this upgrade path prior to upgrading or you will drop tracing data.**
## Migration Steps
diff --git a/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.8/edge-stack-3.X.md b/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.8/edge-stack-3.X.md
new file mode 100644
index 000000000..819df4573
--- /dev/null
+++ b/docs/edge-stack/pre-release/topics/install/upgrade/yaml/edge-stack-3.8/edge-stack-3.X.md
@@ -0,0 +1,63 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrade $productName$ 3.8.Z to $productName$ $version$ (YAML)
+
+emissary-apiext. This is the APIserver extension
+ that supports converting $productName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ emissary-apiext. This is the APIserver extension
+ that supports converting $OSSproductName$ CRDs between getambassador.io/v2
+ and getambassador.io/v3alpha1. This Deployment needs to be running at
+ all times.
+ emissary-apiext Deployment's Pods all stop running,
+ you will not be able to use getambassador.io/v3alpha1 CRDs until restarting
+ the emissary-apiext Deployment.
+ emissary-apiext service that impacts all $productName$ 2.x and 3.x users. Specifically, the TLS certificate used by apiext expires one year after creation and does not auto-renew. All users who are running $productName$/$OSSproductName$ 2.x or 3.x with the apiext service should proactively renew their certificate as soon as practical by running kubectl delete --all secrets --namespace=emissary-system to delete the existing certificate, and then restart the emissary-apiext deployment with kubectl rollout restart deploy/emissary-apiext -n emissary-system.
+ This will create a new certificate with a one year expiration. We will issue a software patch to address this issue well before the one year expiration. Note that certificate renewal will not cause any downtime.
+ AuthService or RateLimitService resources be present; see
+ below for more.
+ key-1 in the example) used in the Secret do not matter, so you can name them whatever helps you keep track of the associated API Keys.
+
+
+4. Create a [FilterPolicy resource][] to use the `Filter` created above
+
+ ```yaml
+ kubectl apply -f -<ambassador_xsrf.NAME.NAMESPACE cookie, and instead required you to use the ambassador_session.NAME.NAMESPACE cookie. The ambassador_session.NAME.NAMESPACE cookie should no longer be used for XSRF-protection purposes.
+ Prior versions of Ambassador Edge Stack did not have an ambassador_xsrf.NAME.NAMESPACE cookie, and instead required you to use the ambassador_session.NAME.NAMESPACE cookie. The ambassador_session.NAME.NAMESPACE cookie should no longer be used for XSRF-protection purposes.