- 
-
- 
-
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..59b1633f6
--- /dev/null
+++ b/docs/edge-stack/latest/about/faq.md
@@ -0,0 +1,78 @@
+# 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.
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/doc-links.yml b/docs/edge-stack/latest/doc-links.yml
new file mode 100644
index 000000000..50ebb708a
--- /dev/null
+++ b/docs/edge-stack/latest/doc-links.yml
@@ -0,0 +1,287 @@
+ - title: Quick start
+ link: /tutorials/getting-started
+ - title: Core concepts
+ items:
+ - title: Kubernetes network architecture
+ link: /topics/concepts/kubernetes-network-architecture
+ - title: 'The Ambassador operating model: GitOps and continuous delivery'
+ link: /topics/concepts/gitops-continuous-delivery
+ - title: Progressive delivery
+ link: /topics/concepts/progressive-delivery
+ - title: Microservices API gateways
+ link: /topics/concepts/microservices-api-gateways
+ - title: $productName$ architecture
+ link: /topics/concepts/architecture
+ - title: Rate limiting at the edge
+ link: /topics/concepts/rate-limiting-at-the-edge
+ - title: Installation and updates
+ link: /topics/install/
+ items:
+ - title: Install with Helm
+ link: /topics/install/helm
+ - title: Install with Kubernetes YAML
+ link: /topics/install/yaml-install
+ - title: Try the demo with Docker
+ link: /topics/install/docker
+ - title: Upgrade or migrate to a newer version
+ link: /topics/install/migration-matrix
+ - title: Edge Stack user guide
+ items:
+ - title: Deployment
+ items:
+ - title: Deployment architecture
+ link: /topics/running/ambassador-deployment
+ - title: $productName$ environment variables and ports
+ link: /topics/running/environment
+ - title: $productName$ and Redis
+ link: /topics/running/aes-redis
+ - title: $productName$ with AWS
+ link: /topics/running/ambassador-with-aws
+ - title: $productName$ with GKE
+ link: /topics/running/ambassador-with-gke
+ - title: Advanced deployment configuration
+ link: /topics/running/running
+ - title: Performance and scaling $productName$
+ link: /topics/running/scaling
+ - title: Active health checking configuration
+ link: /howtos/active-health-checking
+ - title: HTTP/3 configuration
+ items:
+ - title: HTTP3 setup in $productName$
+ link: /topics/running/http3
+ - title: HTTP/3 with AKS
+ link: /howtos/http3-aks
+ - title: HTTP/3 with EKS
+ link: /howtos/http3-eks
+ - title: HTTP/3 with GKE
+ link: /howtos/http3-gke
+ - title: Web Application Firewalls
+ items:
+ - title: $productName$'s Web Application Firewall
+ link: /howtos/web-application-firewalls
+ - title: Configuring Web Application Firewall rules
+ link: /howtos/web-application-firewalls-config
+ - title: Using Web Application Firewalls in Production
+ link: /howtos/web-application-firewalls-in-production
+ - title: Service routing and communication
+ items:
+ - title: Configuring $productName$ to communicate
+ link: /howtos/configure-communications
+ - title: Get traffic from the edge
+ link: /howtos/route
+ - title: TCP connections
+ link: /topics/using/tcpmappings
+ - title: gRPC connections
+ link: /howtos/grpc
+ - title: WebSocket connections
+ link: /howtos/websockets
+ - title: Authentication
+ items:
+ - title: Basic authentication
+ link: /howtos/ext-filters
+ - title: Using the OAuth2 filter for SSO
+ link: /howtos/oauth-oidc-auth
+ - title: Single Sign-On with Google
+ link: /howtos/sso/google
+ - title: Single Sign-On with Keycloak
+ link: /howtos/sso/keycloak
+ - title: Kubernetes SSO with OIDC and Keycloak
+ link: /howtos/auth-kubectl-keycloak
+ - title: Single Sign-On with Okta
+ link: /howtos/sso/okta
+ - title: Single Sign-On with Auth0
+ link: /howtos/sso/auth0
+ - title: Single Sign-On with Azure AD
+ link: /howtos/sso/azure
+ - title: Single Sign-On with OneLogin
+ link: /howtos/sso/onelogin
+ - title: Single Sign-On with Salesforce
+ link: /howtos/sso/salesforce
+ - title: Single Sign-On with UAA
+ link: /howtos/sso/uaa
+ - title: Authentication extension
+ link: /topics/running/aes-extensions/authentication
+ - title: Rate limiting
+ items:
+ - title: Rate limiting in $productName$
+ link: /howtos/advanced-rate-limiting
+ - title: Basic rate limiting
+ link: /topics/using/rate-limits/
+ - title: Rate limiting on token claims
+ link: /howtos/token-ratelimit
+ - title: Rate limiting reference
+ link: /topics/using/rate-limits/rate-limits
+ - title: Rate limiting extension
+ link: /topics/running/aes-extensions/ratelimit
+ - title: Service monitoring
+ items:
+ - title: Explore distributed tracing and Kubernetes monitoring
+ link: /howtos/dist-tracing
+ - title: Distributed tracing with Datadog
+ link: /howtos/tracing-datadog
+ - title: Distributed tracing with Zipkin
+ link: /howtos/tracing-zipkin
+ - title: Distributed tracing with LightStep
+ link: /howtos/tracing-lightstep
+ - title: Monitoring with Prometheus and Grafana
+ link: /howtos/prometheus
+ - title: Statistics
+ link: /topics/running/statistics
+ - title: Envoy statistics with StatsD
+ link: /topics/running/statistics/envoy-statsd
+ - title: The metrics endpoint
+ link: /topics/running/statistics/8877-metrics
+ - title: $productName$ integrations
+ items:
+ - title: Knative Serverless Framework
+ link: /howtos/knative
+ - title: ExternalDNS integration
+ link: /howtos/external-dns
+ - title: Consul integration
+ link: /howtos/consul
+ - title: Istio integration
+ link: /howtos/istio
+ - title: Linkerd 2 integration
+ link: /howtos/linkerd2
+ - title: Technical reference
+ items:
+ - title: Custom resources
+ items:
+ - title: The Host resource
+ link: /topics/running/host-crd
+ - title: The Listener resource
+ link: /topics/running/listener
+ - title: The Module resource
+ link: /topics/running/ambassador
+ - title: The Mapping resource
+ link: /topics/using/intro-mappings
+ - title: Advanced Mapping configuration
+ link: /topics/using/mappings
+ - title: TLS configuration
+ items:
+ - title: TLS overview
+ link: /topics/running/tls/
+ - title: Cleartext support
+ link: /topics/running/tls/cleartext-redirection
+ - title: Mutual TLS (mTLS)
+ link: /topics/running/tls/mtls
+ - title: Server Name Indication (SNI)
+ link: /topics/running/tls/sni
+ - title: TLS origination
+ link: /topics/running/tls/origination
+ - title: TLS termination and enabling HTTPS
+ link: /howtos/tls-termination
+ - title: Using cert-manager
+ link: /howtos/cert-manager
+ - title: Client certificate validation
+ link: /howtos/client-cert-validation
+ - title: Filters
+ items:
+ - title: Filters and Filter policies
+ link: /topics/using/filters/
+ - title: OAuth2 Filter
+ link: /topics/using/filters/oauth2
+ - title: JWT Filter
+ link: /topics/using/filters/jwt
+ - title: External Filter
+ link: /topics/using/filters/external
+ - title: Plugin Filter
+ link: /topics/using/filters/plugin
+ - title: API Keys Filter
+ link: /topics/using/filters/apikeys
+ - title: Ingress and load balancing
+ items:
+ - title: AuthService settings
+ link: /topics/using/authservice
+ - title: Automatic retries
+ link: /topics/using/retries
+ - title: Canary releases
+ link: /topics/using/canary
+ - title: Circuit Breakers
+ link: /topics/using/circuit-breakers
+ - title: Cross-Origin Resource Sharing (CORS)
+ link: /topics/using/cors
+ - title: Ingress controller
+ link: /topics/running/ingress-controller
+ - title: Load balancing
+ link: /topics/running/load-balancer
+ - title: Service discovery and resolvers
+ link: /topics/running/resolvers
+ - title: Headers
+ items:
+ - title: Headers overview
+ link: /topics/using/headers/headers
+ - title: Add request headers
+ link: /topics/using/headers/add_request_headers
+ - title: Remove request headers
+ link: /topics/using/headers/remove_request_headers
+ - title: Add response headers
+ link: /topics/using/headers/add_response_headers
+ - title: Remove response headers
+ link: /topics/using/headers/remove_response_headers
+ - title: Header-based routing
+ link: /topics/using/headers/headers
+ - title: Host header
+ link: /topics/using/headers/host
+ - title: Routing
+ items:
+ - title: Keepalive
+ link: /topics/using/keepalive
+ - title: Method-based routing
+ link: /topics/using/method
+ - title: Prefix regex
+ link: /topics/using/prefix_regex
+ - title: Query parameter-based routing
+ link: /topics/using/query_parameters/
+ - title: Redirects
+ link: /topics/using/redirects
+ - title: Rewrites
+ link: /topics/using/rewrites
+ - title: Timeouts
+ link: /topics/using/timeouts
+ - title: Traffic shadowing
+ link: /topics/using/shadowing
+ - title: Plug-in services
+ items:
+ - title: Authentication service
+ link: /topics/running/services/auth-service
+ - title: ExtAuth protocol
+ link: /topics/running/services/ext_authz
+ - title: Log service
+ link: /topics/running/services/log-service
+ - title: Rate limit service
+ link: /topics/running/services/rate-limit-service
+ - title: Tracing service
+ link: /topics/running/services/tracing-service
+ - title: Traffic management
+ items:
+ - title: Custom error responses
+ link: /topics/running/custom-error-responses
+ - title: Gzip compression
+ link: /topics/running/gzip
+ - title: API
+ items:
+ - title: Gateway API
+ link: /topics/using/gateway-api
+ - title: Developer Portal
+ link: /topics/using/dev-portal
+ - title: FAQs
+ link: /about/faq
+ - title: Troubleshooting
+ link: /topics/running/debugging
+ - title: Known issues
+ link: /about/known-issues
+ - title: Changes in $productName$ 2.X
+ link: /about/changes-2.x
+ - title: Changes in $productName$ 3.X
+ link: /about/changes-3.y
+ - title: Release Notes
+ link: /release-notes
+ - title: Community
+ link: /community
+ - title: End of Life Policy
+ link: /about/aes-emissary-eol
+ - title: $productName$ Licenses
+ link: topics/using/licenses
+ - title: Open Source Dependency Licenses
+ link: licenses
diff --git a/docs/edge-stack/latest/howtos/advanced-rate-limiting.md b/docs/edge-stack/latest/howtos/advanced-rate-limiting.md
new file mode 100644
index 000000000..1c6f6ff51
--- /dev/null
+++ b/docs/edge-stack/latest/howtos/advanced-rate-limiting.md
@@ -0,0 +1,246 @@
+# Advanced rate limiting
+
+$productName$ features a built-in [Rate Limit Service (RLS)](../../topics/running/services/rate-limit-service/#external-rate-limit-service). The $productName$ RLS uses a decentralized configuration model that enables individual teams the ability to independently manage [rate limits](https://www.getambassador.io/learn/kubernetes-glossary/rate-limiting) independently.
+
+All of the examples on this page use the backend service of the quote sample application to illustrate how to perform the rate limiting functions.
+
+## Rate Limiting in $productName$
+
+In $productName$, the `RateLimit` resource defines the policy for rate limiting. The rate limit policy is applied to individual requests according to the labels you add to the `Mapping` resource. This allows you to assign labels based on the particular needs of you rate limiting policies and apply the `RateLimit` policies to only the domains in the related `Mapping` resource.
+
+You can apply the `RateLimit` policy globally to all requests with matching labels from the `Module` resource. This can be used in conjunction with the `Mapping` resource to have a global rate limit with more granular rate limiting for specific requests that go through that specific `Mapping` resource.
+
+ In order for you to enact rate limiting policies:
+
+* Each domain you target needs to have labels.
+* For individual request, the service's `Mapping` resource needs to contain the labels related to the domains you want to apply the rate limiting policy to.
+* For global requests, the service's `Module` resource needs to contain the labels related to the policy you want to apply.
+* The `RateLimit` resource needs to set the rate limit policy for the labels the `Mapping` resource.
+
+
+## Rate limiting for availability
+
+Global rate limiting applies to the entire Kubernetes service mesh. This example shows how to limit the `quote` service to 3 requests per minute.
+
+1. First, add a request label to the `request_label_group` of the `quote` service's `Mapping` resource. This example uses `backend` for the label:
+
+ ```yaml
+ apiVersion: getambassador.io/v3alpha1
+ kind: Mapping
+ metadata:
+ name: quote-backend
+ spec:
+ hostname: "*"
+ prefix: /backend/
+ service: quote
+ labels:
+ ambassador:
+ - request_label_group:
+ - generic_key:
+ value: backend
+ ```
+
+ Apply the mapping configuration changes with `kubectl apply -f quote-backend.yaml`.
+
+ 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.
+
+
+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.
+ 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: topics/using/filters/#filterpolicy-definition
+
+ - title: Fix support for for v2 Mappings with CORS
+ type: bugfix
+ body: >-
+ Ambassador Edge Stack 2.1.1 generated invalid Envoy configuration for
+ 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..21253feaf
--- /dev/null
+++ b/docs/edge-stack/latest/topics/install/migration-matrix.md
@@ -0,0 +1,46 @@
+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.
+ 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 $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.
+
+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:
+ 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.
+Listener.
+AMBASSADOR_ENVOY_API_VERSION has been removed and will no longer have the affect
+of changing the transport protocol.
+transport_protocol to v2 is no longer supported within CRDS (AuthService, etc...). An error will now be logged and $productName$ will not configure envoy correctly. You should remove this field from your CRD's or convert it to v3 the only supported version at this time.
+Mapping that does not use the endpoint resolver then the health checking configuration will be ignored.
+Listener and Host resources are
+ required for a functioning $productName$ installation that can route traffic!Listener.Host.
+Host exists! If the
+ wildcard behavior is needed, a Host with a hostname of "*"
+ must be defined by the user.
+Listener.Host.Mapping.TCPMapping.TLSContext.
+Listener
+Host
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+ListenerHost
+apiGroups include "getambassador.io" following "networking.k8s.io" and the resources include "hosts" after "ingresses".
+ LoadBalancer services. Refer to the Azure Docs - Managed Identity for more information.
+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:
+
+ ```shell
+ $ 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 (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 - <labels require Mapping resources with apiVersion getambassador.io/v2 or newer — if you're updating an old installation, check the
+ apiVersion!
+Listener and Host resources are
+ required for a functioning $productName$ installation that can route traffic!Listener.Host.
+Listener.Host.
+service.namespace.svc.cluster.local may work for Kubernetes resolvers, the preferred syntax is service.namespace. What's next?
+
+There are many options for [advanced mapping configurations](../../topics/using/mappings), with features like [automatic retries](../../topics/using/retries/), [timeouts](../../topics/using/timeouts/), [rate limiting](../../topics/using/rate-limits/), [redirects](../../topics/using/redirects/), and more.
diff --git a/docs/emissary/latest/howtos/tls-termination.md b/docs/emissary/latest/howtos/tls-termination.md
new file mode 100644
index 000000000..2bbdf4c40
--- /dev/null
+++ b/docs/emissary/latest/howtos/tls-termination.md
@@ -0,0 +1,192 @@
+# TLS termination and enabling HTTPS
+
+TLS encryption is one of the basic requirements of having a secure system.
+$AESproductName$ [automatically enables TLS termination/HTTPs
+](../../topics/running/host-crd#tls-settings), making TLS encryption
+easy and centralizing TLS termination for all of your services in Kubernetes.
+
+While this automatic certificate management in $AESproductName$ helps
+simply TLS configuration in your cluster, the Open-Source $OSSproductName$
+still requires you provide your own certificate to enable TLS.
+
+The following will walk you through the process of enabling TLS with a
+self-signed certificate created with the `openssl` utility.
+
+**Note** these instructions also work if you would like to provide your own
+certificate to $AESproductName$.
+
+## Prerequisites
+
+This guide requires you have the following installed:
+
+- A Kubernetes cluster v1.11 or newer
+- The Kubernetes command-line tool,
+[`kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- [openssl](https://www.openssl.org/source/)
+
+## Install $productName$
+
+[Install $productName$ in Kubernetes](../../topics/install).
+
+## Create a listener listening on the correct port and protocol
+We first need to create a listener to tell Emissary which port will be using the HTTPS protocol
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Listener
+metadata:
+ name: emissary-ingress-listener-8443
+spec:
+ port: 8443
+ protocol: HTTPS
+ securityModel: XFP
+ hostBinding:
+ namespace:
+ from: ALL
+```
+
+## Create a self-signed certificate
+
+OpenSSL is a tool that allows us to create self-signed certificates for opening
+a TLS encrypted connection. The `openssl` command below will create a
+create a certificate and private key pair that $productName$ can use for TLS
+termination.
+
+- Create a private key and certificate.
+
+ ```
+ openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -subj '/CN=ambassador-cert' -nodes
+ ```
+
+ The above command will create a certificate and private key with the common
+ name `ambassador`. Since this certificate is self-signed and only used for testing,
+ the other information requested can be left blank.
+
+- Verify the `key.pem` and `cert.pem` files were created
+
+ ```
+ ls *.pem
+ cert.pem key.pem
+ ```
+
+## Store the certificate and key in a Kubernetes Secret
+
+$productName$ dynamically loads TLS certificates by reading them from
+Kubernetes secrets. Use `kubectl` to create a `tls` secret to hold the pem
+files we created above.
+
+```
+kubectl create secret tls tls-cert --cert=cert.pem --key=key.pem
+```
+
+## Tell $productName$ to use this secret for TLS termination
+
+Now that we have stored our certificate and private key in a Kubernetes secret
+named `tls-cert`, we need to tell $productName$ to use this certificate
+for terminating TLS on a domain. A `Host` is used to tell $productName$ which
+certificate to use for TLS termination on a domain.
+
+Create the following `Host` to have $productName$ use the `Secret` we created
+above for terminating TLS on all domains.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: wildcard-host
+spec:
+ hostname: "*"
+ acmeProvider:
+ authority: none
+ tlsSecret:
+ name: tls-cert
+```
+
+**Note:** If running multiple instances of $productName$ in one cluster remember to include the `ambassador_id` property in the `spec`, e.g.:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+ name: wildcard-host
+spec:
+ ambassador_id: [ "my_id" ]
+ ...
+```
+
+Apply the `Host` configured above with `kubectl`:
+
+```
+kubectl apply -f wildcard-host.yaml
+```
+
+$productName$ is now configured to listen for TLS traffic on port `8443` and
+terminate TLS using the self-signed certificate we created.
+
+## Send a request Over HTTPS
+
+We can now send encrypted traffic over HTTPS.
+
+First, make sure the $productName$ service is listening on `443` and forwarding
+to port `8443`. Verify this with `kubectl`:
+
+```
+kubectl get service ambassador -o yaml
+
+apiVersion: v1
+kind: Service
+...
+spec:
+ ports:
+ - name: http
+ port: 80
+ protocol: TCP
+ targetPort: 8080
+ - name: https
+ port: 443
+ protocol: TCP
+ targetPort: 8443
+...
+```
+
+If the output to the `kubectl` command is not similar to the example above,
+edit the $productName$ service to add the `https` port.
+
+After verifying $productName$ is listening on port 443, send a request
+to your backend service with curl:
+
+```
+curl -Lk https://{{AMBASSADOR_IP}}/backend/
+
+{
+ "server": "trim-kumquat-fccjxh8x",
+ "quote": "Abstraction is ever present.",
+ "time": "2019-07-24T16:36:56.7983516Z"
+}
+```
+
+**Note:** Since we are using a self-signed certificate, you must set the `-k`
+flag in curl to disable hostname validation.
+
+## Next steps
+
+This guide walked you through how to enable basic TLS termination in $productName$ using a self-signed certificate for simplicity.
+
+### Get a valid certificate from a certificate authority
+
+While a self-signed certificate is a simple and quick way to get $productName$ to terminate TLS, it should not be used by production systems. In order to serve HTTPS traffic without being returned a security warning, you will need to get a certificate from an official Certificate Authority like Let's Encrypt.
+
+Jetstack's `cert-manager` provides a simple
+way to manage certificates from Let's Encrypt. See our documentation for more
+information on how to [use `cert-manager` with $productName$
+](../cert-manager).
+
+### Enable advanced TLS options
+
+$productName$ exposes configuration for many more advanced options
+around TLS termination, origination, client certificate validation, and SNI
+support. See the full [TLS reference](../../topics/running/tls) for more
+information.
diff --git a/docs/emissary/latest/howtos/tracing-datadog.md b/docs/emissary/latest/howtos/tracing-datadog.md
new file mode 100644
index 000000000..d627e29f2
--- /dev/null
+++ b/docs/emissary/latest/howtos/tracing-datadog.md
@@ -0,0 +1,63 @@
+# Distributed Tracing with Datadog
+
+In this tutorial, we'll configure $productName$ to initiate a trace on some sample requests, and use DataDog APM to visualize them.
+
+## Before you get started
+
+This tutorial assumes you have already followed $productName$ [Getting Started](../../tutorials/getting-started) guide. If you haven't done that already, you should do that now.
+
+After completing the Getting Started guide you will have a Kubernetes cluster running $productName$ and the Quote service. Let's walk through adding tracing to this setup.
+
+## 1. Configure the DataDog agent
+
+You will need to configure the DataDog agent so that it uses a host-port and accepts non-local APM traffic, you can follow the DataDog [documentation](https://docs.datadoghq.com/agent/kubernetes/apm/?tab=daemonset) on how to do this.
+
+## 2. Configure Envoy JSON logging
+
+DataDog APM can [correlate traces with logs](https://docs.datadoghq.com/tracing/advanced/connect_logs_and_traces/) if you propagate the current span and trace IDs with your logs.
+
+When using JSON logging with Envoy, $productName$ will automatically append the `dd.trace_id` and `dd.span_id` properties to all logs so that correlation works:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Module
+metadata:
+ name: ambassador
+spec:
+ config:
+ envoy_log_type: json
+```
+
+## 3. Configure the TracingService
+
+Next configure a TracingService that will write your traces using the DataDog tracing driver, as you want to write traces to your host-local DataDog agent you can use the `${HOST_IP}` interpolation to get the host IP address from the $productName$ containers environment.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TracingService
+metadata:
+ name: tracing
+spec:
+ service: "${HOST_IP}:8126"
+ driver: datadog
+ config:
+ service_name: test
+```
+
+## 4. Generate some requests
+
+Use `curl` to generate a few requests to an existing $productName$ mapping. You may need to perform many requests, since only a subset of random requests are sampled and instrumented with traces.
+
+```
+$ curl -L $AMBASSADOR_IP/httpbin/ip
+```
+
+## 5. Test traces
+
+Once you have made some requests you should be able to [view your traces](https://app.datadoghq.com/apm/traces) within a few minutes in the DataDog UI. If you would like more information on DataDog APM to learn about its features and benefits you can view the [documentation](https://docs.datadoghq.com/tracing/).
+
+## More
+
+For more details about configuring the external tracing service, read the documentation on [external tracing](../../topics/running/services/tracing-service).
diff --git a/docs/emissary/latest/howtos/tracing-lightstep.md b/docs/emissary/latest/howtos/tracing-lightstep.md
new file mode 100644
index 000000000..30353e71d
--- /dev/null
+++ b/docs/emissary/latest/howtos/tracing-lightstep.md
@@ -0,0 +1,230 @@
+# Distributed Tracing with OpenTelemetry and Lightstep
+
+In this tutorial, we'll configure [$productName$](https://www.getambassador.io/products/edge-stack/api-gateway) to initiate a trace on some sample requests, collect them with the OpenTelemetry Collector and use Lightstep to visualize them.
+
+TracingService no longer supports the native Envoy Lightstep tracing driver as of $productName$ version 3.4.0. If you are currently using the native Lightstep tracing driver, please refer to the bottom of the page on how to migrate.
+ambassador namespace):
+
+```bash
+ kubectl -n ambassador rollout restart deploy
+```
+
+ambassador namespace):
+
+```
+$ kubectl -n ambassador rollout restart deploy
+```
+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. 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.
+ - title: Upgrade to Golang 1.20.3
+ type: security
+ body: >-
+ Upgrading to the latest release of Golang as part of our general dependency upgrade process. This includes security fixes for CVE-2023-24537, CVE-2023-24538, CVE-2023-24534, CVE-2023-24536.
+
+ - version: 3.5.1
+ date: '2023-02-24'
+ notes:
+ - title: 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/emissary/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.emissary-apiext server is a Kubernetes Conversion Webhook that converts between the $productName$ CRD versions. On startup, it ensures that a self-signed cert is available so that K8s API Server can talk to the conversion webhook (*TLS is required by K8s*). We have introduced a startupProbe to ensure that emissary-apiext server has enough time to configure the webhooks before running liveness and readiness probes. This is to ensure
+ slow first-time startup doesn't cause K8s to needlessly restart the pod.
+
+ - title: Upgraded to Python 3.10
+ type: change
+ body: >-
+ Upgraded to Python 3.10 as part of continued investment in keeping dependencies updated.
+
+ - title: Upgraded base image to alpine-3.17
+ type: change
+ body: >-
+ Upgraded base image to alpine-3.17 as part of continued investment in keeping dependencies updated.
+
+ - title: Shipped Helm chart v8.5.0
+ type: change
+ body: >-
+ Here are a list of changes to the helm chart:startupProbes on the emissary-ingress deployment.podSecurityPolicy value because support has been removed in Kubernetes 1.25.
+
+ docs: https://github.com/emissary-ingress/emissary/blob/master/charts/emissary-ingress/CHANGELOG.md
+
+ - 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); 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 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.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: 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.
+ docs: topics/running/services/rate-limit-service/
+
+ - 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: 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: 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 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: Add new secrets sync directive to the Agent
+ type: feature
+ body: >-
+ Adds a new command to the agent directive service to manage secrets. This allows a third party product to manage CRDs that depend upon a secret.
+ - title: Add additional pprof endpoints
+ type: feature
+ body: >-
+ Add additional pprof endpoints to allow for profiling $productName$:
+ - CPU profiles (/debug/pprof/profile)
+ - tracing (/debug/pprof/trace)
+ - command line running (/debug/pprof/cmdline)
+ - program counters (/debug/pprof/symbol)
+ - 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: 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
+ - version: 3.0.0
+ date: '2022-06-28'
+ notes:
+ - title: Upgrade to Envoy 1.22
+ type: change
+ body: >-
+ $productName$ has been upgraded to the latest Envoy 1.22 patch release 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 xDS Transport Protocol support. See below for additional information.
+ - 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 AuthServices, LogServices and RatelimitServices 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/running/services/auth-service/
+ - title: HTTP/3 Downstream Support
+ type: feature
+ body: >-
+ With the upgrade to Envoy, $productName$ is now able to provide downstream support for HTTP/3.
+
+ HTTP/3 is built on the QUIC protocol which communicates using the UDP network protocol. QUIC requires TLS v1.3 be used when communicating between client and server.
+ docs: topics/running/http3
+ - title: Zipkin driver for TracingService removed support for HTTP_JSON_V1
+ type: change
+ body: >-
+ When using the zipkin driver for the TracingService. The collector_endpoint_version no longer accepts `HTTP_JSON_V1` due to the Envoy upgrade. The new default value is `HTTP_JSON`.
+ docs: topics/running/services/tracing-service/
+
+ - 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. $productName$ does not expose any of these golang servers to external clients directly.
+
+ - version: 2.5.0
+ date: '2022-11-03'
+ 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: 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.1
+ 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.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`.
+
+ - 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: 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: 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: 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
+
+
+ - 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: 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: Deprecated v2 transport protocol for AuthServices
+ type: change
+ body: >-
+ A future release of $productName$ will remove support for the now deprecated v2 transport protocol in AuthServices. Instructions for migrating existing AuthServices from v2 to v3 can be found on the AuthService page. This change only impacts gRPC AuthServices. HTTP AuthServices are unaffected by this change.
+ docs: topics/running/services/auth-service/
+
+ edgeStackNotes:
+ - title: Improved performance processing OAuth2 Filters
+ type: change
+ body: >-
+ When each OAuth2 Filter that references a Kubernetes secret is loaded, $AESproductName$ previously needed to communicate with the API server to request and validate that secret before loading the next Filter. To improve performance, $AESproductName$ will now load and validate all secrets required by OAuth2 Filters at once prior to loading the filters.
+
+ - 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 $AESproductName$ will now only operate with transport protocol v3. In order to support existing External Filters using v2, $AESproductName$ 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.
+
+ - title: Deprecated v2 transport protocol for External Filters
+ type: change
+ body: >-
+ A future release of $AESproductName$ will remove support for the now deprecated v2 transport protocol in 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.
+
+ - 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: Emissary-ingress 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
+
+ edgeStackNotes:
+ - 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.
+
+ - version: 2.1.2
+ prevVersion: 2.1.0
+ 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 support for for v2 Mappings with CORS
+ type: bugfix
+ body: >-
+ Emissary-ingress 2.1.0 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: 'N/A'
+ notes:
+ - title: Never issued
+ type: change
+ isHeadline: true
+ body: >-
+ Emissary-ingress 2.1.1 was not issued; Ambassador Edge Stack 2.1.1 uses
+ Emissary-ingress 2.1.0.
+
+ - version: 2.1.0
+ date: '2021-12-16'
+ notes:
+ - title: Not recommended; upgrade to 2.1.2 instead
+ type: change
+ isHeadline: true
+ body: >-
+ Emissary-ingress 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: 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: '2021-11-08'
+ notes:
+ - 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: 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: ./emissary-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: 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/
+
+ - 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 Major Changes in 2.X 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/
+
+ edgeStackNotes:
+ - 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/emissary/latest/topics/concepts/architecture.md b/docs/emissary/latest/topics/concepts/architecture.md
new file mode 100644
index 000000000..fe9e0bd31
--- /dev/null
+++ b/docs/emissary/latest/topics/concepts/architecture.md
@@ -0,0 +1,27 @@
+# The $productName$ architecture
+
+## $productName$ is a control plane
+
+$productName$ is a specialized [control plane for Envoy Proxy](https://blog.getambassador.io/the-importance-of-control-planes-with-service-meshes-and-front-proxies-665f90c80b3d). In this architecture, $productName$ translates configuration (in the form of Kubernetes Custom Resources) to Envoy configuration. All actual traffic is directly handled by the high-performance [Envoy Proxy](https://www.envoyproxy.io).
+
+
+
+## Details
+
+1. The service owner defines configuration in Kubernetes manifests.
+2. When the manifest is applied to the cluster, the Kubernetes API notifies $productName$ of the change.
+3. $productName$ parses the change and transforms the configuration into a semantic intermediate representation. Envoy configuration is generated from this IR.
+4. The new configuration is passed to Envoy via the gRPC-based Aggregated Discovery Service (ADS) API.
+5. Traffic flows through the reconfigured Envoy, without dropping any connections.
+
+## Scaling and availability
+
+$productName$ relies on Kubernetes for scaling, high availability, and persistence. All $productName$ configuration is stored directly in Kubernetes; there is no database. $productName$ is packaged as a single container that contains both the control plane and an Envoy Proxy instance. By default, $productName$ is deployed as a Kubernetes `deployment` and can be scaled and managed like any other Kubernetes deployment.
+
+### Stateless architecture
+
+By design, $productName$ is an entirely stateless architecture. Each individual $productName$ instance operates independently of other instances. These $productName$ instances rely on Kubernetes to coordinate the configuration between the different $productName$ instances. This enables $productName$ to sidestep the need to engineer a safe, highly available centralized control plane (and if you don't think that this is hard, check out [Jepsen](https://jepsen.io)). By contrast, other control plane architectures rely on a single centralized control plane to manage multiple instances of the data plane. This means that these control plane architectures must engineer resilience and availability into their central control plane.
+
+## Envoy Proxy
+
+$productName$ closely tracks Envoy Proxy releases. A stable branch of Envoy Proxy is maintained that enables the team to cherry-pick specific fixes into $productName$.
diff --git a/docs/emissary/latest/topics/concepts/gitops-continuous-delivery.md b/docs/emissary/latest/topics/concepts/gitops-continuous-delivery.md
new file mode 100644
index 000000000..336a1c66b
--- /dev/null
+++ b/docs/emissary/latest/topics/concepts/gitops-continuous-delivery.md
@@ -0,0 +1,66 @@
+# The Ambassador operating model: GitOps and continuous delivery
+
+Containerized applications deployed in Kubernetes generally follow the microservices design pattern, where an application composed of dozens or even hundreds of services communicate with each other. Independent application development teams are responsible for the full lifecycle of a service, including coding, testing, deployment, release, and operations. By giving these teams independence, microservices enable organizations to scale their development without sacrificing agility.
+
+## Policies, declarative configuration, and Custom Resource Definitions
+
+$productName$ configuration is built on the concept of _policies_. A policy is a statement of intent and codified in a declarative configuration file. $productName$ takes advantage of Kubernetes Custom Resource Definitions (CRDs) to provide a declarative configuration workflow that is idiomatic with Kubernetes.
+
+Both operators and application developers can write policies. Typically, operators are responsible for global policies that affect all microservices. Common examples of these types of policies include TLS configuration and metrics. Application development teams will want to own the policies that affect their specific service, as these settings will vary from service to service. Examples of these types of service-specific settings include protocols (e.g., HTTP, gRPC, TCP, WebSockets), timeouts, and cross-origin resource sharing settings.
+
+Because many different teams may need to write policies, $productName$ supports a decentralized configuration model. Individual policies are written in different files. $productName$ aggregates all policies into one master policy configuration for the edge.
+
+## Continuous delivery and GitOps
+
+Code cannot provide value to end-users until it is running in production. [Continuous Delivery](https://continuousdelivery.com/) is the ability to get changes of all types -- including new features, configuration changes, bug fixes, and experiments -- into production, and in front of customers safely and quickly in a sustainable way.
+
+[GitOps](https://www.weave.works/technologies/gitops/) is an approach to continuous delivery that relies on using a source control system as a single source of truth for all infrastructure and configuration. **In the GitOps model, configuration changes go through a specific workflow:**
+
+1. All configuration is stored in source control.
+2. A configuration change is made via pull request.
+3. The pull request is approved and merged into the production branch.
+4. Automated systems (e.g., a continuous integration pipeline) ensure the configuration of the production branch is in full sync with actual production systems.
+
+Critically, no human should ever directly apply configuration changes to a live
+cluster. Instead, any changes happen via the source control system. This entire
+workflow is also self-service; an operations team does not need to be
+directly involved in managing the change process (except in the review/approval
+process, if desirable).
+
+Contrast this a **traditional, manual workflow:**
+
+1. App developer defines configuration.
+2. App developer opens a ticket for operations.
+3. Operations team reviews ticket.
+4. Operations team initiates infrastructure change management process.
+5. Operations team executes change using UI or REST API.
+6. Operations team notifies app developer of the change.
+7. App developer tests change, and opens a ticket to give feedback to operations if necessary.
+
+The self-service, continuous delivery model is critical for ensuring that edge operations can scale.
+
+## Continuous delivery, GitOps, and $productName$
+
+Adopting a continuous delivery workflow with $productName$ via GitOps provides several advantages:
+
+1. **Reduced deployment risk**: By immediately deploying approved configuration into production, configuration issues can be rapidly identified. Resolving any issue is as simple as rolling back the change in source control.
+2. **Auditability**: Understanding the specific configuration of $productName$ is as simple as reviewing the configuration in the source control repository. Moreover, any changes made to the configuration will also be recorded, providing context on previous configurations.
+3. **Simpler infrastructure upgrades**: Upgrading any infrastructure component,
+ whether the component is Kubernetes, $productName$, or some other piece of
+ infrastructure, is straightforward. A replica environment can be easily
+ created and tested directly from your source control system. Once the
+ upgrade has been validated, the replica environment can be swapped into
+ production, or production can be live upgraded.
+4. **Security**: Access to production cluster(s) can be restricted to senior operators and an automated system, reducing the number of individuals who can directly modify the cluster.
+
+In a typical $productName$ GitOps workflow:
+
+* Each service has its own $productName$ policy. This policy consists of one or more $productName$ custom resource definitions, specified in YAML.
+* This policy is stored in the same repository as the service, and managed by the service team.
+* Changes to the policy follow the GitOps workflow discussed above (e.g., pull request, approval, and continuous delivery).
+* Global configuration that is managed by operations are stored in a central repository alongside other cluster configuration. This repository is also set up for continuous delivery with a GitOps workflow.
+
+## Further reading
+
+* The [AppDirect engineering team](https://blog.getambassador.io/fireside-chat-with-alex-gervais-accelerating-appdirect-developer-workflow-with-ambassador-7586597b1c34) writes $productName$ configurations within each team's Kubernetes service YAML manifests. These are stored in git and follow the same review/approval process as any other code unit, and a continuous delivery pipeline listens on changes to the repository and applies changes to Kubernetes.
+* Netflix introduces [full cycle development](https://netflixtechblog.com/full-cycle-developers-at-netflix-a08c31f83249), a model for developing microservices
diff --git a/docs/emissary/latest/topics/concepts/index.md b/docs/emissary/latest/topics/concepts/index.md
new file mode 100644
index 000000000..2d02a0277
--- /dev/null
+++ b/docs/emissary/latest/topics/concepts/index.md
@@ -0,0 +1,10 @@
+# Core concepts
+
+This section of the documentation introduces core concepts of Kubernetes and Ambassador. Kubernetes and microservices introduce a number of new, powerful paradigms for software development, and Ambassador takes full advantage of these paradigms.
+
+This section discusses:
+
+* [The Kubernetes Network Architecture and Ambassador](kubernetes-network-architecture)
+* [The Ambassador Operating Model: Continuous Delivery, GitOps, and Declarative Configuration](gitops-continuous-delivery)
+* [Progressive Delivery](progressive-delivery)
+* [Microservices API Gateways](microservices-api-gateways)
diff --git a/docs/emissary/latest/topics/concepts/kubernetes-network-architecture.md b/docs/emissary/latest/topics/concepts/kubernetes-network-architecture.md
new file mode 100644
index 000000000..2239a24fc
--- /dev/null
+++ b/docs/emissary/latest/topics/concepts/kubernetes-network-architecture.md
@@ -0,0 +1,52 @@
+# Kubernetes Network architecture
+
+## Kubernetes has its own isolated network
+
+Each Kubernetes cluster provides its own isolated network namespace. This approach has a number of benefits. For example, each pod can be easily accessed with its own IP address. One of the consequences of this approach, however, is that a network bridge is required in order to route traffic from outside the Kubernetes cluster to services inside the cluster.
+
+## Routing traffic to your Kubernetes cluster
+
+While there are a number of techniques for routing traffic to a Kubernetes cluster, by far the most common and popular method involves deploying an in-cluster edge proxy / ingress controller along with an external load balancer. In this architecture, the network topology looks like this:
+
+getambassador.io/v3alpha1
+ immediately, you should ultimately update them all for full functionality with $productName$
+Listener
+ListenerHost
+HostMapping
+Mapping that specifies host_regex: true is associated with
+ all Hosts. This is generally far less desirable than using hostname
+ with a DNS glob.
+host and host_regex will be removed before
+ v3alpha1 is promoted to v3.
+HostTLSContext
+Mapping
+Mapping that specifies host_regex: true will be associated with
+ all Hosts. This is generally far less desirable than using
+ hostname with a DNS glob.
+Mapping
+Mapping
+Mapping
+AuthServiceMappingRateLimitServiceTCPMapping
+Listener
+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$/$AESproductName$ 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 emissary image from any of the following registries:
+
+- `docker.io/emissaryingress/`
+- `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/emissary/latest/topics/install/migrate-to-2-alternate.md b/docs/emissary/latest/topics/install/migrate-to-2-alternate.md
new file mode 100644
index 000000000..edc42916a
--- /dev/null
+++ b/docs/emissary/latest/topics/install/migrate-to-2-alternate.md
@@ -0,0 +1,40 @@
+---
+ Title: Migrate to $productName$ $versionTwoX$
+ description: "Instructions for how to upgrade $productName$ to $versionTwoX$. Transfer your current configuration of $AESproductName$ or $OSSproductName$ to $versionTwoX$."
+---
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$ $versionTwoX$ 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$ $versionTwoX$:
+
+1. Install $productName$ $versionTwoX$ in a completely new cluster.
+
+2. **Create `Listener`s for $productName$ $versionTwoX$.**
+
+ When $productName$ $versionTwoX$ starts, it will not have any `Listener`s, and it will not
+ create any. You must create `Listener` resources by hand, or $productName$ $versionTwoX$
+ will not listen on any ports.
+
+3. Copy the entire configuration from the $productName$ 1.X cluster to the $productName$
+ $versionTwoX$ cluster. This is most simply done with `kubectl get -o yaml | kubectl apply -f -`.
+
+ This will create `getambassador.io/v2` resources in the $productName$ $versionTwoX$ cluster.
+ $productName$ $versionTwoX$ 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$
+ $versionTwoX$ cluster.
diff --git a/docs/emissary/latest/topics/install/migrate-to-3-alternate.md b/docs/emissary/latest/topics/install/migrate-to-3-alternate.md
new file mode 100644
index 000000000..3b9df0c11
--- /dev/null
+++ b/docs/emissary/latest/topics/install/migrate-to-3-alternate.md
@@ -0,0 +1,36 @@
+import Alert from '@material-ui/lab/Alert';
+
+# Upgrading $productName$ $version$ 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/emissary/latest/topics/install/migration-matrix.md b/docs/emissary/latest/topics/install/migration-matrix.md
new file mode 100644
index 000000000..a95382071
--- /dev/null
+++ b/docs/emissary/latest/topics/install/migration-matrix.md
@@ -0,0 +1,46 @@
+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$/$AESproductName$ 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 for $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.
+ 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$/$AESproductName$ 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 for $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$/$AESproductName$ 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 for $productName$ 2.X.
+ Do not use the ambassador Helm chart.
+ AuthServices, LogServices and RateLimitServices to use
+ protocol_version: "v3" or else an error will be posted and a static response will be returned in $version$.
+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$/$AESproductName$ 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 for $productName$ 3.Y.
+ 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$/$AESproductName$ 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 for $productName$ 3.Y.
+ 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$/$AESproductName$ 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 for $productName$ 3.Y.
+ 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$/$AESproductName$ 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.
+ 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$/$AESproductName$ 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-emissaryns.yaml file
+ uses the `emissary` namespace, since this is the default for $productName$.
+ We also publish emissary-defaultns.yaml for the
+ `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.
+ 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$/$AESproductName$ 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-emissaryns.yaml file
+ uses the `emissary` namespace, since this is the default for $productName$.
+ We also publish emissary-defaultns.yaml for the
+ `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.
+ AuthServices, LogServices and RateLimitServices to use
+ protocol_version: "v3" or else an error will be posted and a static response will be returned in $version$.
+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$/$AESproductName$ 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-emissaryns.yaml file
+ uses the `emissary` namespace, since this is the default for $productName$.
+ We also publish emissary-defaultns.yaml for the
+ `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.
+ 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$/$AESproductName$ 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-emissaryns.yaml file
+ uses the `emissary` namespace, since this is the default for $productName$.
+ We also publish emissary-defaultns.yaml for the
+ `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.
+ 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$/$AESproductName$ 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-emissaryns.yaml file
+ uses the `emissary` namespace, since this is the default for $productName$.
+ We also publish emissary-defaultns.yaml for the
+ `default` namespace. For any other namespace, you should download one of these files and edit the namespaces manually.
+ 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$/$AESproductName$ 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.
+ 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.% symbol is not escaped as above (%%), it may
+ only be as part of an
+ AccessLog substitution, for example %RESPONSE_CODE% or
+ %PROTOCOL%. If a % is neither part of a valid
+ substitution nor an escape, $productName$ will ignore the custom error response.
+Uh oh, looks like you found a bad link.
+Click here to go back home.
+ +``` + +Finally, mount the configmap to the $productName$ pod: + +> **NOTE:** The following YAML is in [patch format](https://kubernetes.io/docs/tasks/manage-kubernetes-objects/update-api-object-kubectl-patch/) +and does not represent the entire deployment spec. + +```yaml +spec: + template: + spec: + containers: + - name: aes + volumeMounts: + - name: ambassador-errorpages + mountPath: /ambassador/ambassador-errorpages + volumes: + - name: ambassador-errorpages + configMap: + name: ambassador-errorpages +``` + +## Known limitations + +- `text_format`and `text_format_source` perform no string +escaping on expanded variables. This may break the structural integrity of your +response body if, for example, the variable contains HTML data and the response +content type is `text/html`. Be careful when using variables in this way, and +consider whether the value may be coming from an untrusted source like request +or response headers. +- The `json_format` field does not support sourcing from a file. Instead +consider using `text_format_source` with a JSON file and `content_type` set to +`application/json`. + +## Rule precedence + +If rules are set on both the `Module` and on a `Mapping`, the rule set on +the `Mapping` will take precedence, ignoring any `Module` rules. This is true +even if the rules are for different status codes. For example, consider this +configuration: + +```yaml +apiVersion: getambassador.io/v3alpha1 +kind: Module +metadata: + name: ambassador + namespace: ambassador +spec: + config: + error_response_overrides: + - on_status_code: 404 + body: + text_format: "Global 404" +--- +apiVersion: getambassador.io/v3alpha1 +kind: Mapping +metadata: + name: ambassador + namespace: ambassador +spec: + hostname: "*" + prefix: /api/ + service: quote + error_response_overrides: + - on_status_code: 429 + body: + text_format: "Per-mapping 429" +``` +The `Mapping` rule will prevent an override on the 404 rule defined on the +`Module` for this `Mapping`. The rule on the `Mapping` will cause all rules on +the `Module` to be ignored, regardless of the status codes specified. A seperate +`Mapping` with no override rules defined will follow the 404 rule on the `Module`. + +## Disabling response overrides + +If error response overrides are set on the `Module`, they can be disabled on +individual mappings by setting +`bypass_error_response_overrides: true` on those mappings: + +```yaml +--- +apiVersion: getambassador.io/v3alpha1 +kind: Mapping +metadata: + name: quote-backend + namespace: ambassador +spec: + hostname: "*" + prefix: /api/ + service: quote + bypass_error_response_overrides: true +``` + +This is useful if a portion of the domain serves an API whose errors should not +be rewritten, but all other APIs should contain custom errors. diff --git a/docs/emissary/latest/topics/running/debugging.md b/docs/emissary/latest/topics/running/debugging.md new file mode 100644 index 000000000..bd376483f --- /dev/null +++ b/docs/emissary/latest/topics/running/debugging.md @@ -0,0 +1,192 @@ +# Debugging + +If you’re experiencing issues with the $productName$ and cannot diagnose the issue through the `/ambassador/v0/diag/` diagnostics endpoint, this document covers various approaches and advanced use cases for debugging $productName$ issues. + +We assume that you already have a running $productName$ installation in the following sections. + +## A Note on TLS + +[TLS] can appear intractable if you haven't set up [certificates] correctly. If you're +having trouble with TLS, always [check the logs] of your $productName$ Pods and look for +certificate errors. + +[TLS]: ../tls +[certificates]: ../tls#certificates-and-secrets +[check the logs]: #review-logs + +## Check $productName$ status + +1. First, check the $productName$ Deployment with the following: `kubectl get -n $productNamespace$ deployments` + + After a brief period, the terminal will print something similar to the following: + + ``` + $ kubectl get -n $productNamespace$ deployments + NAME DESIRED CURRENT UP-TO-DATE AVAILABLE AGE + $productDeploymentName$ 3 3 3 3 1m + $productDeploymentName$-apiext 3 3 3 3 1m + ``` + +2. Check that the “desired” number of Pods matches the “current” and “available” number of Pods. + +3. If they are **not** equal, check the status of the associated Pods with the following command: `kubectl get pods -n $productNamespace$`. + + The terminal should print something similar to the following: + + ``` + $ kubectl get pods -n $productNamespace$ + NAME READY STATUS RESTARTS AGE + $productDeploymentName$-85c4cf67b-4pfj2 1/1 Running 0 1m + $productDeploymentName$-85c4cf67b-fqp9g 1/1 Running 0 1m + $productDeploymentName$-85c4cf67b-vg6p5 1/1 Running 0 1m + $productDeploymentName$-apiext-736f8497d-j34pf 1/1 Running 0 1m + $productDeploymentName$-apiext-736f8497d-9gfpq 1/1 Running 0 1m + $productDeploymentName$-apiext-736f8497d-p5wgx 1/1 Running 0 1m + ``` + + The actual names of the Pods will vary. All the Pods should indicate `Running`, and all should show 1/1 containers ready. + +4. If the Pods do not seem reasonable, use the following command for details about the history of the Deployment: `kubectl describe -n $productNamespace$ deployment $productDeploymentName$` + + * Look for data in the “Replicas” field near the top of the output. For example: + `Replicas: 3 desired | 3 updated | 3 total | 3 available | 0 unavailable` + + * Look for data in the “Events” log field near the bottom of the output, which often displays data such as a fail image pull, RBAC issues, or a lack of cluster resources. For example: + + ``` + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal ScalingReplicaSet 2m deployment-controller Scaled up replica set $productDeploymentName$-85c4cf67b to 3 + ``` + +5. Additionally, use the following command to “describe” the individual Pods: `kubectl describe pods -n $productNamespace$ <$productDeploymentName$-pod-name>` + + * Look for data in the “Status” field near the top of the output. For example, `Status: Running` + + * Look for data in the “Events” field near the bottom of the output, as it will often show issues such as image pull failures, volume mount issues, and container crash loops. For example: + ``` + Events: + Type Reason Age From Message + ---- ------ ---- ---- ------- + Normal Scheduled 4m default-scheduler Successfully assigned $productDeploymentName$-85c4cf67b-4pfj2 to gke-ambassador-demo-default-pool-912378e5-dkxc + Normal SuccessfulMountVolume 4m kubelet, gke-ambassador-demo-default-pool-912378e5-dkxc MountVolume.SetUp succeeded for volume "$productDeploymentName$-token-tmk94" + Normal Pulling 4m kubelet, gke-ambassador-demo-default-pool-912378e5-dkxc pulling image "docker.io/datawire/ambassador:0.40.0" + Normal Pulled 4m kubelet, gke-$productDeploymentName$-demo-default-pool-912378e5-dkxc Successfully pulled image "docker.io/datawire/ambassador:0.40.0" + Normal Created 4m kubelet, gke-$productDeploymentName$-demo-default-pool-912378e5-dkxc Created container + Normal Started 4m kubelet, gke-$productDeploymentName$-demo-default-pool-912378e5-dkxc Started container + ``` + +In both the Deployment Pod and the individual Pods, take the necessary action to address any discovered issues. + +## Review logs + +$productName$ logging can provide information on anything that might be abnormal or malfunctioning. While there may be a large amount of data to sort through, look for key errors such as the $productName$ process restarting unexpectedly, or a malformed Envoy configuration. + +$productName$ has two major log mechanisms: $productName$ logging and Envoy logging. Both appear in the normal `kubectl logs` output, and both can have additional debug-level logging enabled. + +AES_REPORT_DIAGNOSTICS_TO_CLOUD environment variable is set to `"true"` on the Agent deployment to allow diagnostics information to be reported to the cloud.
+
+ ```shell
+ # Namespace and deployment name depend on your current install
+
+ kubectl set env deployment/edge-stack-agent -n ambassador AES_REPORT_DIAGNOSTICS_TO_CLOUD="true"
+ ```
+
+Finally, set the `AES_DIAGNOSTICS_URL` environment variable to `"http://emissary-ingress-admin:8877/ambassador/v0/diag/?json=true"`
+
+ ```shell
+ # Namespace, deployment name, and pod url/port depend on your current install
+
+ kubectl set env deployment/edge-stack-agent -n ambassador AES_DIAGNOSTICS_URL="http://emissary-ingress-admin:8877/ambassador/v0/diag/?json=true"
+ ```
+
+After setting up `AES_DIAGNOSTICS_URL`, you can access diagnostics information by using the same URL value.
+
+### Still can't see $productName$ Diagnostics?
+
+Do a port forward on your $productName$ pod
+
+ ```shell
+ # Namespace, deployment name, and pod url/port depend on your current install
+
+ kubectl port-forward edge-stack-76f785767-n2l2v -n ambassador 8877
+ ```
+
+You will be able to access the diagnostics overview page by going to `http://localhost:8877/ambassador/v0/diag/`
+
+### $productName$ not routing your services as expected?
+
+You will need to examine the logs and $productName$ pod status. See [Debugging](../debugging) for more information.
diff --git a/docs/emissary/latest/topics/running/environment.md b/docs/emissary/latest/topics/running/environment.md
new file mode 100644
index 000000000..265fceddc
--- /dev/null
+++ b/docs/emissary/latest/topics/running/environment.md
@@ -0,0 +1,366 @@
+# $productName$ Environment variables
+
+Use the following variables for the environment of your $productName$ container:
+
+| Variable | Default value | Value type |
+|----------------------------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------|
+| [`AMBASSADOR_ID`](#ambassador_id) | `[ "default" ]` | List of strings |
+| [`AES_LOG_LEVEL`](#aes_log_level) | `warn` | Log level |
+| [`AGENT_CONFIG_RESOURCE_NAME`](#agent_config_resource_name) | `ambassador-agent-cloud-token` | String |
+| [`AMBASSADOR_AMBEX_NO_RATELIMIT`](#ambassador_ambex_no_ratelimit) | `false` | Boolean: `true`=true, any other value=false |
+| [`AMBASSADOR_AMBEX_SNAPSHOT_COUNT`](#ambassador_ambex_snapshot_count) | `30` | Integer |
+| [`AMBASSADOR_CLUSTER_ID`](#ambassador_cluster_id) | Empty | String |
+| [`AMBASSADOR_CONFIG_BASE_DIR`](#ambassador_config_base_dir) | `/ambassador` | String |
+| [`AMBASSADOR_DISABLE_FEATURES`](#ambassador_disable_features) | Empty | Any |
+| [`AMBASSADOR_DRAIN_TIME`](#ambassador_drain_time) | `600` | Integer |
+| [`AMBASSADOR_ENVOY_API_VERSION`](#ambassador_envoy_api_version) | `V3` | String Enum; `V3` or `V2` |
+| [`AMBASSADOR_GRPC_METRICS_SINK`](#ambassador_grpc_metrics_sink) | Empty | String (address:port) |
+| [`AMBASSADOR_HEALTHCHECK_BIND_ADDRESS`](#ambassador_healthcheck_bind_address)| `0.0.0.0` | String |
+| [`AMBASSADOR_HEALTHCHECK_BIND_PORT`](#ambassador_healthcheck_bind_port)| `8877` | Integer |
+| [`AMBASSADOR_HEALTHCHECK_IP_FAMILY`](#ambassador_healthcheck_ip_family)| `ANY` | String Enum; `IPV4_ONLY` or `IPV6_ONLY`|
+| [`AMBASSADOR_ISTIO_SECRET_DIR`](#ambassador_istio_secret_dir) | `/etc/istio-certs` | String |
+| [`AMBASSADOR_JSON_LOGGING`](#ambassador_json_logging) | `false` | Boolean; non-empty=true, empty=false |
+| [`AMBASSADOR_READY_PORT`](#ambassador_ready_port) | `8006` | Integer |
+| [`AMBASSADOR_READY_LOG`](#ambassador_ready_log) | `false` | Boolean; [Go `strconv.ParseBool`] |
+| [`AMBASSADOR_LABEL_SELECTOR`](#ambassador_label_selector) | Empty | String (label=value) |
+| [`AMBASSADOR_NAMESPACE`](#ambassador_namespace) | `default` ([^1]) | Kubernetes namespace |
+| [`AMBASSADOR_RECONFIG_MAX_DELAY`](#ambassador_reconfig_max_delay) | `1` | Integer |
+| [`AMBASSADOR_SINGLE_NAMESPACE`](#ambassador_single_namespace) | Empty | Boolean; non-empty=true, empty=false |
+| [`AMBASSADOR_SNAPSHOT_COUNT`](#ambassador_snapshot_count) | `4` | Integer |
+| [`AMBASSADOR_VERIFY_SSL_FALSE`](#ambassador_verify_ssl_false) | `false` | Boolean; `true`=true, any other value=false |
+| [`DD_ENTITY_ID`](#dd_entity_id) | Empty | String |
+| [`DOGSTATSD`](#dogstatsd) | `false` | Boolean; Python `value.lower() == "true"` |
+| [`SCOUT_DISABLE`](#scout_disable) | `false` | Boolean; `false`=false, any other value=true |
+| [`STATSD_ENABLED`](#statsd_enabled) | `false` | Boolean; Python `value.lower() == "true"` |
+| [`STATSD_PORT`](#statsd_port) | `8125` | Integer |
+| [`STATSD_HOST`](#statsd_host) | `statsd-sink` | String |
+| [`STATSD_FLUSH_INTERVAL`](#statsd_flush_interval) | `1` | Integer |
+| [`_AMBASSADOR_ID`](#_ambassador_id) | Empty | String |
+| [`_AMBASSADOR_TLS_SECRET_NAME`](#_ambassador_tls_secret_name) | Empty | String |
+| [`_AMBASSADOR_TLS_SECRET_NAMESPACE`](#_ambassador_tls_secret_namespace) | Empty | String |
+| [`_CONSUL_HOST`](#_consul_host) | Empty | String |
+| [`_CONSUL_PORT`](#_consul_port) | Empty | Integer |
+| [`AMBASSADOR_DISABLE_SNAPSHOT_SERVER`](#ambassador_disable_snapshot_server) | `false` | Boolean; non-empty=true, empty=false |
+| [`AMBASSADOR_ENVOY_BASE_ID`](#ambassador_envoy_base_id) | `0` | Integer | | `false` | Boolean; Python `value.lower() == "true"` |
+
+
+## Feature Flag Environment Variables
+
+| Variable | Default value | Value type |
+|----------------------------------------------------------------------------------------- |-----------------------------------------------------|-------------------------------------------------------------------------------|
+| [`AMBASSADOR_EDS_BYPASS`](#ambassador_eds_bypass) | `false` | Boolean; Python `value.lower() == "true"` |
+| [`AMBASSADOR_FORCE_SECRET_VALIDATION`](#ambassador_force_secret_validation) | `false` | Boolean: `true`=true, any other value=false |
+| [`AMBASSADOR_KNATIVE_SUPPORT`](#ambassador_knative_support) | `false` | Boolean; non-empty=true, empty=false |
+| [`AMBASSADOR_UPDATE_MAPPING_STATUS`](#ambassador_update_mapping_status) | `false` | Boolean; `true`=true, any other value=false |
+| [`ENVOY_CONCURRENCY`](#envoy_concurrency) | Empty | Integer |
+| [`DISABLE_STRICT_LABEL_SELECTORS`](#disable_strict_label_selectors) | `false` | Boolean; `true`=true, any other value=false |
+
+### `AMBASSADOR_ID`
+
+$productName$ supports running multiple installs in the same cluster without restricting a given instance of $productName$ to a single namespace.
+The resources that are visible to an installation can be limited with the `AMBASSADOR_ID` environment variable.
+
+[More information](../../running/running#ambassador_id)
+
+### `AES_LOG_LEVEL`
+
+Adjust the log level by setting the `AES_LOG_LEVEL` environment variable; from least verbose to most verbose, the valid values are `error`, `warn`/`warning`, `info`, `debug`, and `trace`. The default is `info`.
+Log level names are case-insensitive.
+
+[More information](../../running/running#log-levels-and-debugging)
+
+### `AGENT_CONFIG_RESOURCE_NAME`
+
+Allows overriding the default config_map/secret that is used for extracting the CloudToken for connecting with Ambassador cloud. It allows all
+components (and not only the Ambassador Agent) to authenticate requests to Ambassador Cloud.
+If unset it will just fallback to searching for a config map or secret with the name of `ambassador-agent-cloud-token`. Note: the secret will take precedence if both a secret and config map are set.
+
+### `AMBASSADOR_AMBEX_NO_RATELIMIT`
+
+Completely disables 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.
+
+[More information](../../../topics/concepts/rate-limiting-at-the-edge/)
+
+### `AMBASSADOR_AMBEX_SNAPSHOT_COUNT`
+
+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.
+
+[More information](../../running/debugging#examine-pod-and-container-contents)
+
+### `AMBASSADOR_CLUSTER_ID`
+
+Each $productName$ installation generates a unique cluster ID based on the UID of its Kubernetes namespace and its $productName$ ID: the resulting cluster ID is a UUID which cannot be used
+to reveal the namespace name nor $productName$ ID itself. $productName$ needs RBAC permission to get namespaces for this purpose, as shown in the default YAML files provided by Datawire;
+if not granted this permission it will generate a UUID based only on the $productName$ ID. To disable cluster ID generation entirely, set the environment variable
+`AMBASSADOR_CLUSTER_ID` to a UUID that will be used for the cluster ID.
+
+[More information](../../running/running#emissary-ingress-update-checks-scout)
+
+### `AMBASSADOR_CONFIG_BASE_DIR`
+
+Controls where $productName$ will store snapshots. By default, the latest configuration will be in `/ambassador/snapshots`. If you have overridden it, $productName$ saves configurations in `$AMBASSADOR_CONFIG_BASE_DIR/snapshots`.
+
+[More information](../../running/debugging#examine-pod-and-container-contents)
+
+### `AMBASSADOR_DISABLE_FEATURES`
+
+To completely disable feature reporting, set the environment variable `AMBASSADOR_DISABLE_FEATURES` to any non-empty value.
+
+[More information](../../running/running/#emissary-ingress-update-checks-scout)
+
+### `AMBASSADOR_DRAIN_TIME`
+
+At each reconfiguration, $productName$ keeps around the old version of it's envoy config for the duration of the configured drain time.
+The `AMBASSADOR_DRAIN_TIME` variable controls how much of a grace period $productName$ provides active clients when reconfiguration happens.
+Its unit is seconds and it defaults to 600 (10 minutes). This can impact memory usage because $productName$ needs to keep around old versions of its configuration
+for the duration of the drain time.
+
+[More information](../../running/scaling#ambassador_drain_time)
+
+### `AMBASSADOR_ENVOY_API_VERSION`
+
+By default, $productName$ will configure Envoy using the [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api).
+In $productName$ 2.0, you were able switch back to Envoy V2 by setting the `AMBASSADOR_ENVOY_API_VERSION` environment variable to "V2".
+$productName$ 3.0 has removed support for the V2 API and only the V3 API is used. While this variable cannot be set to another value in 3.0, it may
+be used when introducing new API versions that are not yet available in $productName$ such as V4.
+
+### `AMBASSADOR_GRPC_METRICS_SINK`
+
+Configures Edgissary (envoy) to send metrics to the Agent which are then relayed to the Cloud. If not set then we don’t configure envoy to send metrics to the agent. If set with a bad address:port then we log an error message. In either scenario, it just stops metrics from being sent to the Agent which has no negative effect on general routing or Edgissary uptime.
+
+### `AMBASSADOR_HEALTHCHECK_BIND_ADDRESS`
+
+Configures $productName$ to bind its health check server to the provided address. If not set $productName$ will bind to all addresses (`0.0.0.0`).
+
+### `AMBASSADOR_HEALTHCHECK_BIND_PORT`
+
+Configures $productName$ to bind its health check server to the provided port. If not set $productName$ will listen on the admin port(`8877`).
+
+### `AMBASSADOR_HEALTHCHECK_IP_FAMILY`
+
+Allows the IP Family used by health check server to be overriden. By default, the health check server will listen for both IPV4 and IPV6 addresses. In some clusters you may want to force `IPV4_ONLY` or `IPV6_ONLY`.
+
+### `AMBASSADOR_ISTIO_SECRET_DIR`
+
+$productName$ will read the mTLS certificates from `/etc/istio-certs` unless configured to use a different directory with the `AMBASSADOR_ISTIO_SECRET_DIR`
+environment variable and create a secret in that location named `istio-certs`.
+
+[More information](../../../howtos/istio#configure-an-mtls-tlscontext)
+
+### `AMBASSADOR_JSON_LOGGING`
+
+When `AMBASSADOR_JSON_LOGGING` is set to `true`, JSON format will be used for most of the control plane logs.
+Some (but few) logs from `gunicorn` and the Kubernetes `client-go` package will still be in text only format.
+
+[More information](../../running/running#log-format)
+
+### `AMBASSADOR_READY_PORT`
+
+A dedicated Listener is created for non-blocking readiness checks. By default, the Listener will listen on the loopback address
+and port `8006`. `8006` is part of the reserved ports dedicated to $productName$. If their is a conflict then setting
+`AMBASSADOR_READY_PORT` to a valid port will configure Envoy to Listen on that port.
+
+### `AMBASSADOR_READY_LOG`
+
+When `AMBASSADOR_READY_LOG` is set to `true`, the envoy `/ready` endpoint will be logged. It will honor format
+provided in the `Module` resource or default to the standard log line format.
+
+### `AMBASSADOR_LABEL_SELECTOR`
+
+Restricts $productName$'s configuration to only the labelled resources. For example, you could apply a `version-two: true` label
+to all resources that should be visible to $productName$, then set `AMBASSADOR_LABEL_SELECTOR=version-two=true` in its Deployment.
+Resources without the specified label will be ignored.
+
+### `AMBASSADOR_NAMESPACE`
+
+Controls namespace configuration for Amabssador.
+
+[More information](../../running/running#namespaces)
+
+### `AMBASSADOR_RECONFIG_MAX_DELAY`
+
+Controls up to how long Ambassador will wait to receive changes before doing an Envoy reconfiguration. The unit is
+in seconds and must be > 0.
+
+### `AMBASSADOR_SINGLE_NAMESPACE`
+
+When set, configures $productName$ to only work within a single namespace.
+
+[More information](../../running/running#namespaces)
+
+### `AMBASSADOR_SNAPSHOT_COUNT`
+
+The number of snapshots that $productName$ should save.
+
+### `AMBASSADOR_VERIFY_SSL_FALSE`
+
+By default, $productName$ will verify the TLS certificates provided by the Kubernetes API. In some situations, the cluster may be
+deployed with self-signed certificates. In this case, set `AMBASSADOR_VERIFY_SSL_FALSE` to `true` to disable verifying the TLS certificates.
+
+[More information](../../running/running#ambassador_verify_ssl_false)
+
+### `DD_ENTITY_ID`
+
+$productName$ supports setting the `dd.internal.entity_id` statitics tag using the `DD_ENTITY_ID` environment variable. If this value
+is set, statistics will be tagged with the value of the environment variable. Otherwise, this statistics tag will be omitted (the default).
+
+[More information](../../running/statistics/envoy-statsd#using-datadog-dogstatsd-as-the-statsd-sink)
+
+### `DOGSTATSD`
+
+If you are a user of the [Datadog](https://docs.datadoghq.com/) monitoring system, pulling in the Envoy statistics from $productName$ is very easy.
+Because the DogStatsD protocol is slightly different than the normal StatsD protocol, in addition to setting $productName$'s
+`STATSD_ENABLED=true` environment variable, you also need to set the`DOGSTATSD=true` environment variable.
+
+[More information](../../running/statistics/envoy-statsd#using-datadog-dogstatsd-as-the-statsd-sink)
+
+### `SCOUT_DISABLE`
+
+$productName$ integrates Scout, a service that periodically checks with Datawire servers to advise of available updates. Scout also sends anonymized usage
+data and the $productName$ version. This information is important to us as we prioritize test coverage, bug fixes, and feature development. Note that the $productName$ will
+run regardless of the status of Scout.
+
+We do not recommend you disable Scout, since we use this mechanism to notify users of new releases (including critical fixes and security issues). This check can be disabled by setting
+the environment variable `SCOUT_DISABLE` to `1` in your $productName$ deployment.
+
+[More information](../../running/running#emissary-ingress-update-checks-scout)
+
+### `STATSD_ENABLED`
+
+If enabled, then $productName$ has Envoy expose metrics information via the ubiquitous and well-tested [StatsD](https://github.com/etsy/statsd)
+protocol. To enable this, you will simply need to set the environment variable `STATSD_ENABLED=true` in $productName$'s deployment YAML
+
+[More information](../../running/statistics/envoy-statsd#envoy-statistics-with-statsd)
+
+### `STATSD_HOST`
+
+When this variable is set, $productName$ by default sends statistics to a Kubernetes service named `statsd-sink` on UDP port 8125 (the usual
+port of the StatsD protocol). You may instead tell $productName$ to send the statistics to a different StatsD server by setting the
+`STATSD_HOST` environment variable. This can be useful if you have an existing StatsD sink available in your cluster.
+
+[More information](../../running/statistics/envoy-statsd#envoy-statistics-with-statsd)
+
+### `STATSD_PORT`
+
+Allows for configuring StatsD on a port other than the default (8125)
+
+[More information](../../running/statistics/envoy-statsd#envoy-statistics-with-statsd)
+
+### `STATSD_FLUSH_INTERVAL`
+
+How often, in seconds, to submit statsd reports (if `STATSD_ENABLED`)
+
+[More information](../../running/statistics/envoy-statsd#envoy-statistics-with-statsd)
+
+### `_AMBASSADOR_ID`
+
+Used with the Ambassador Consul connector. Sets the Ambassador ID so multiple instances of this integration can run per-Cluster when there are multiple $productNamePlural$ (Required if `AMBASSADOR_ID` is set in your $productName$ `Deployment`
+
+[More information](../../../howtos/consul#environment-variables)
+
+### `_AMBASSADOR_TLS_SECRET_NAME`
+
+Used with the Ambassador Consul connector. Sets the name of the Kubernetes `v1.Secret` created by this program that contains the Consul-generated TLS certificate.
+
+[More information](../../../howtos/consul#environment-variables)
+
+### `_AMBASSADOR_TLS_SECRET_NAMESPACE`
+
+Used with the Ambassador Consul connector. Sets the namespace of the Kubernetes `v1.Secret` created by this program.
+
+[More information](../../../howtos/consul#environment-variables)
+
+### `_CONSUL_HOST`
+
+Used with the Ambassador Consul connector. Sets the IP or DNS name of the target Consul HTTP API server
+
+[More information](../../../howtos/consul#environment-variables)
+
+### `_CONSUL_PORT`
+
+Used with the Ambassador Consul connector. Sets the port number of the target Consul HTTP API server.
+
+[More information](../../../howtos/consul#environment-variables)
+
+### `AMBASSADOR_DISABLE_SNAPSHOT_SERVER`
+
+Disables the built-in snapshot server
+
+### `AMBASSADOR_ENVOY_BASE_ID`
+
+Base ID of the Envoy process
+
+### `AMBASSADOR_EDS_BYPASS`
+
+Bypasses EDS handling of endpoints and causes endpoints to be inserted to clusters manually. This can help resolve with `503 UH`
+caused by certification rotation relating to a delay between EDS + CDS.
+
+### `AMBASSADOR_FORCE_SECRET_VALIDATION`
+
+If you set the `AMBASSADOR_FORCE_SECRET_VALIDATION` environment variable, invalid Secrets will be rejected,
+and a `Host` or `TLSContext` resource attempting to use an invalid certificate will be disabled entirely.
+
+[More information](../../running/tls#certificates-and-secrets)
+
+### `AMBASSADOR_KNATIVE_SUPPORT`
+
+Enables support for knative
+
+### `AMBASSADOR_UPDATE_MAPPING_STATUS`
+
+If `AMBASSADOR_UPDATE_MAPPING_STATUS` is set to the string `true`, $productName$ will update the `status` of every `Mapping`
+CRD that it accepts for its configuration. This has no effect on the proper functioning of $productName$ itself, and can be a
+performance burden on installations with many `Mapping`s. It has no effect for `Mapping`s stored as annotations.
+
+The default is `false`. We recommend leaving `AMBASSADOR_UPDATE_MAPPING_STATUS` turned off unless required for external systems.
+
+[More information](../../running/running#ambassador_update_mapping_status)
+
+### `ENVOY_CONCURRENCY`
+
+Configures the optional [--concurrency](https://www.envoyproxy.io/docs/envoy/latest/operations/cli#cmdoption-concurrency) command line option when launching Envoy.
+This controls the number of worker threads used to serve requests and can be used to fine-tune system resource usage.
+
+### `DISABLE_STRICT_LABEL_SELECTORS`
+
+In $productName$ version `3.2`, a bug with how `Hosts` are associated with `Mappings` was fixed and with how `Listeners` are assocaited with `Hosts`. The `mappingSelector`\\`selector` fields in `Hosts` and `Listeners` were not
+properly being enforced in prior versions. If any single label from the selector was matched then the resources would be associated with each other instead
+of requiring all labels in the selector to be present. Additonally, if the `hostname` of a `Mapping` matched the `hostname` of a `Host` then they would be associated
+regardless of the configuration of `mappingSelector`\\`selector`.
+
+In version `3.2` this bug was fixed and resources that configure a selector will only be associated if **all** labels required by the selector are present.
+This brings the `mappingSelector` and `selector` fields in-line with how label selectors are used throughout Kubernetes. To avoid unexpected behavior after the upgrade,
+add all labels that configured in any `mappingSelector`\\`selector` to `Mappings` you want to associate with the `Host` or the `Hosts` you want to be associated with the `Listener`. You can opt-out of this fix and return to the old
+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.
+
+> **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`.
+
+See The [Host documentation](../../running/host-crd#controlling-association-with-mappings) for more information about `Host` / `Mapping` association.
+
+## Port assignments
+
+$productName$ uses the following ports to listen for HTTP/HTTPS traffic automatically via TCP:
+
+| Port | Process | Function |
+|------|----------|---------------------------------------------------------|
+| 8001 | envoy | Internal stats, logging, etc.; not exposed outside pod |
+| 8002 | watt | Internal watt snapshot access; not exposed outside pod |
+| 8003 | ambex | Internal ambex snapshot access; not exposed outside pod |
+| 8004 | diagd | Internal `diagd` access; not exposed outside pod |
+| 8005 | snapshot | Exposes a scrubbed $productName$ snapshot outside of the pod |
+| 8080 | envoy | Default HTTP service port |
+| 8443 | envoy | Default HTTPS service port |
+| 8877 | diagd | Direct access to diagnostics UI; provided by `busyambassador entrypoint` |
+
+[^1]: This may change in a future release to reflect the Pods's
+ namespace if deployed to a namespace other than `default`.
+ https://github.com/emissary-ingress/emissary/issues/1583
+
+[Go `net.Dial`]: https://golang.org/pkg/net/#Dial
+[Go `strconv.ParseBool`]: https://golang.org/pkg/strconv/#ParseBool
+[Go `time.ParseDuration`]: https://pkg.go.dev/time#ParseDuration
+[Redis 6 ACL]: https://redis.io/topics/acl
diff --git a/docs/emissary/latest/topics/running/gzip.md b/docs/emissary/latest/topics/running/gzip.md
new file mode 100644
index 000000000..e3005c836
--- /dev/null
+++ b/docs/emissary/latest/topics/running/gzip.md
@@ -0,0 +1,55 @@
+# Gzip compression
+
+Gzip enables $productName$ to compress upstream data upon client request. Compression is useful in situations where large payloads need to be transmitted without compromising the response time. Compression can also save on bandwidth costs at the expense of increased computing costs.
+
+## How does it work?
+
+When the gzip filter is enabled, request and response headers are inspected to determine whether or not the content should be compressed. If so, and the request and response headers allow, the content is compressed and then sent to the client with the appropriate headers. It also uses the zlib module, which provides `Deflate` compression and decompression code.
+
+For more details see [Envoy - Gzip](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/compressor_filter).
+
+## The `gzip` API
+
+- `memory_level`: A value from 1 to 9 that controls the amount of internal memory used by zlib. Higher values use more memory, but are faster and produce better compression results. The default value is 5.
+- `min_content_length`: A minimum response length, in bytes, which will trigger compression. The default value is 30.
+- `compression_level`: A value used for selecting the zlib compression level. This setting will affect the speed and amount of compression applied to the content. “BEST” provides higher compression at the cost of higher latency, “SPEED” provides lower compression with minimum impact on response time. “DEFAULT” provides an optimal result between speed and compression. This field will be set to “DEFAULT” if not specified.
+- `compression_strategy`: A value used for selecting the zlib compression strategy which is directly related to the characteristics of the content. Most of the time “DEFAULT” will be the best choice, though there are situations in which changing this parameter might produce better results. For example, run-length encoding (RLE) is typically used when the content is known for having sequences in which the same data occurs many consecutive times. For more information about each strategy, please refer to the zlib manual.
+- `window_bits`: A value from 9 to 15 that represents the base two logarithmic of the compressor’s window size. Larger window results in better compression at the expense of memory usage. The default is 12 which will produce a 4096 bytes window. For more details about this parameter, please refer to zlib manual > deflateInit2.
+- `content_type`: A set of strings that specify which mime-types yield compression; e.g., application/json, text/html, etc. When this field is not defined, compression will be applied to the following mime-types: “application/javascript”, “application/json”, “application/xhtml+xml”, “image/svg+xml”, “text/css”, “text/html”, “text/plain”, “text/xml”.
+- `disable_on_etag_header`: A Boolean, if true, disables compression when the response contains an ETag header. When it is false, the filter will preserve weak ETags and remove the ones that require strong validation.
+- `remove_accept_encoding_header`: A Boolean, if true, removes accept-encoding from the request headers before dispatching it to the upstream so that responses do not get compressed before reaching the filter.
+
+## Example
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Module
+metadata:
+ name: ambassador
+spec:
+ config:
+ gzip:
+ memory_level: 2
+ min_content_length: 32
+ compression_level: BEST
+ compression_strategy: RLE
+ content_type:
+ - application/javascript
+ - application/json
+ - text/plain
+ disable_on_etag_header: false
+ remove_accept_encoding_header: false
+```
+
+Minimum configuration:
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: Module
+metadata:
+ name: ambassador
+spec:
+ config:
+ gzip:
+ enabled: true
+```
diff --git a/docs/emissary/latest/topics/running/host-crd.md b/docs/emissary/latest/topics/running/host-crd.md
new file mode 100644
index 000000000..cd187ebe6
--- /dev/null
+++ b/docs/emissary/latest/topics/running/host-crd.md
@@ -0,0 +1,279 @@
+import Alert from '@material-ui/lab/Alert';
+
+# The **Host** CRD
+
+The custom `Host` resource defines how $productName$ will be
+visible to the outside world. It collects all the following information in a
+single configuration resource:
+
+* The hostname by which $productName$ will be reachable
+* How $productName$ should handle TLS certificates
+* How $productName$ should handle secure and insecure requests
+* Which `Mappings` should be associated with this `Host`
+
+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$ Communications](../../../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 Mappings 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:
+
+### `tlsSecret` enables TLS termination
+
+`tlsSecret` specifies a Kubernetes `Secret` is **required** for any TLS termination to occur. No matter what other TLS
+configuration is present, 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/v2.1.0/api/getambassador.io/v2/Host.proto).
diff --git a/docs/emissary/latest/topics/running/http3.md b/docs/emissary/latest/topics/running/http3.md
new file mode 100644
index 000000000..9aeb6cac8
--- /dev/null
+++ b/docs/emissary/latest/topics/running/http3.md
@@ -0,0 +1,149 @@
+---
+title: "HTTP/3 configuration in $productName$"
+description: "Configure HTTP/3 support with $productName$. Create services to handle UDP and TCP traffic and setup HTTP/3 with your cloud service provider."
+---
+
+# HTTP/3 in $productName$
+
+HTTP/3 is the third version of the Hypertext Transfer Protocol (HTTP). It is built on the [QUIC](https://www.chromium.org/quic/) network protocol rather than Transmission Control Protocol (TCP) like previous versions.
+
+## The changes and challenges of HTTP/3
+
+Since the QUIC network protocol is built on UDP, most clients will require $productName$ to advertise its support for HTTP/3 using the `alt-svc` response header. This header is added to the response of the HTTP/2 and HTTP/1.1 connections. When the client sees the `alt-svc` it can choose to upgrade to HTTP/3 and connect to $productName$ using the QUIC protocol.
+
+QUIC requires Transport Layer Security (TLS) version 1.3 to communicate. Otherwise, $productName$ will fall back to HTTP/2 or HTTP/1.1, both of which support other TLS versions if client does not support TLS v1.3. Due to this restriction, some clients also require valid certificatesand will not upgrade to HTTP/3 traffic with self-signed certificates.
+
+Because HTTP/3 adoption is still growing and and changing, the $productName$ team will continue update this documentation as features change and mature.
+
+## Setting up HTTP/3 with $productName$
+
+To configure $productName$ for HTTP/3 you need to do the following:
+
+1. Configure `Listener` resources.
+2. Configure a `Host`.
+3. Have a valid certificate.
+4. Setup an external load balancer.
+
+### Configuring the Listener resources
+
+To make $productName$ listen for HTTP/3 connections over the QUIC network protocol, you need to configure a `Listener` with `TLS`, `HTTP`, and `UDP` configured within `protocolStack`.
+
+protocolStack elements need to be entered in the specific order of TLS, HTTP, UDP.
+alt-svc: h3=":443"; ma=86400, h3-29=":443"; ma=86400 means that the external load balancer must be configured to accept traffic on port :443 for the client to upgrade the request.
+apiVersion: networking.k8s.io/v1beta1 when defining an Ingress. Since both are still supported in all 1.14+ versions of Kubernetes, this document will use extensions/v1beta1 for compatibility reasons.
+ If you are using 1.18 and above, sample usage of the IngressClass resource and pathType field are available on our blog.
+ TracingService which is configured during Envoy bootstrap. $productName$ must be restarted for changes to the
+TracingService manifest to take affect. If you have multiple instances of $productName$ in your cluster, ensure [ambassador_id](../../running#ambassador_id)
+is set correctly in the TracingService manifest.
+LightStep driver was removed. As of $productName$ 3.4.0, the TracingService no longer supports the lightstep tracing driver. If you are currently using the native Lightstep tracing driver, please refer to Distributed Tracing with Open Telemetry and LightStep
+TracingService. Envoy still considers this driver experimental.
+tag_headers and custom_tags are set then tag_headers will be ignored.
+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.
+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.
+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.
+
+x-sample-header:true. Since 2.0, the same functionality is achieved by using regex_headers.
+Listener and Host resources are
+ required for a functioning $productName$ installation that can route traffic!Listener.Host.
+labels require Mapping resources with apiVersion
+ getambassador.io/v2 or newer — if you're updating an old installation, check the
+ apiVersion!
+
+http://ambassador.example.com/backend-api/foo/bar
+
+
+* ```prefix```: /backend-api/ which rewrites to / by default.
+* ```rewrite```: /
+* ```remainder```: foo/bar
+
+
+would effectively be written to
+
+
+http://service1/foo/bar
+
+
+* ```prefix```: was /backend-api/
+* ```rewrite```: / (by default)
+
+You can change the rewriting: for example, if you choose to rewrite the prefix as /v1/ in this example, the final target would be:
+
+
+
+http://service1/v1/foo/bar
+
+
+* ```prefix```: was /backend-api/
+* ```rewrite```: /v1/
+
+And, of course, you can choose to rewrite the prefix to the prefix itself, so that
+
+
+http://ambassador.example.com/backend-api/foo/bar
+
+
+* ```prefix```: /backend-api/
+* ```rewrite```: /backend-api/
+
+would be "rewritten" as:
+
+
+http://service1/backend-api/foo/bar
+
+
+To prevent $productName$ rewrite the matched prefix to `/` by default, it can be configured to not change the prefix as it forwards a request to the upstream service. To do that, specify an empty `rewrite` directive:
+
+- `rewrite: ""`
+
+In this case requests that match the prefix /backend-api/ will be forwarded to the service without any rewriting:
+
+
+http://ambassador.example.com/backend-api/foo/bar
+
+
+would be forwarded to:
+
+
+http://service1/backend-api/foo/bar
+
+
+## `regex_rewrite`
+
+In some cases, a portion of URL needs to be extracted before making the upstream service URL. For example, suppose that when a request is made to `foo/12345/list`, the target URL must be rewritten as `/bar/12345`. We can do this as follows:
+
+```
+prefix: /foo/
+regex_rewrite:
+ pattern: '/foo/([0-9]*)/list'
+ substitution: '/bar/\1'
+```
+`([0-9]*)` can be replaced with `(\d)` for simplicity.
+
+
+http://ambassador.example.com/foo/12345/list
+
+
+* ```prefix```: /foo/
+* ```pattern```: /foo/12345/list where `12345` captured by `([0-9]*)`
+* ```substitution```: /bar/12345 where `12345` substituted by `\1`
+
+would be forwarded to:
+
+
+http://service1/bar/12345
+
+
+More than one group can be captured in the `pattern` to be referenced by `\2`, `\3` and `\n` in the `substitution` section.
+
+For more information on how `Mapping` can be configured, see [Mappings](../mappings).
diff --git a/docs/emissary/latest/topics/using/shadowing.md b/docs/emissary/latest/topics/using/shadowing.md
new file mode 100644
index 000000000..dd95fbbaf
--- /dev/null
+++ b/docs/emissary/latest/topics/using/shadowing.md
@@ -0,0 +1,78 @@
+# Traffic shadowing
+
+Traffic shadowing is a deployment pattern where production traffic is asynchronously copied to a non-production service for testing. Shadowing is a close cousin to two other commonly known deployment patterns, [canary releases](../canary) and blue/green deployments. Shadowing traffic has several important benefits over blue/green and canary testing:
+
+* Zero production impact. Since traffic is duplicated, any bugs in services that are processing shadow data have no impact on production.
+
+* Test persistent services. Since there is no production impact, shadowing provides a powerful technique to test persistent services. You can configure your test service to store data in a test database, and shadow traffic to your test service for testing. Both blue/green deployments and canary deployments require more machinery for testing.
+
+* Test the actual behavior of a service. When used in conjunction with tools such as [Twitter's Diffy](https://github.com/twitter/diffy), shadowing lets you measure the behavior of your service and compare it with an expected output. A typical canary rollout catches exceptions (e.g., HTTP 500 errors), but what happens when your service has a logic error and is not returning an exception?
+
+## Shadowing and $productName$
+
+$productName$ lets you easily shadow traffic to a given endpoint. In $productName$, only requests are shadowed; responses from a service are dropped. All normal metrics are collected for the shadow services. This makes it easy to compare the performance of the shadow service versus the production service on the same data set. $productName$ also prioritizes the production path, i.e., it will return responses from the production service without waiting for any responses from the shadow service.
+
+
+
+## The `shadow` Mapping
+
+In $productName$, you can enable shadowing for a given mapping by setting `shadow: true` in your `Mapping`. One copy proceeds as if the shadowing `Mapping` was not present: the request is handed onward per the `service`(s) defined by the non-shadow `Mapping`s, and the reply from whichever `service` is picked is handed back to the client.
+
+The second copy is handed to the `service` defined by the `Mapping` with `shadow` set. Any reply from this `service` is ignored, rather than being handed back to the client. Only a single `shadow` per resource can be specified (i.e., you can't shadow the same resource to more than 1 additional destination). In this situation, $productName$ will indicate an error in the diagnostic service, and only one `shadow` will be used. If you need to implement this type of use case, you should shadow traffic to a multicast proxy (or equivalent).
+
+You can shadow multiple different services.
+
+During shadowing, the host header is modified such that `-shadow` is appended.
+
+## Example
+
+The following example may help illustrate how shadowing can be used. This first attribute sets up a basic mapping between the `myservice` Kubernetes service and the `/myservice/` prefix, as expected.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: myservice
+spec:
+ hostname: '*'
+ prefix: /myservice/
+ service: myservice.default
+```
+
+What if we want to shadow the traffic to `myservice`, and send that exact same traffic to `myservice-shadow`? We can create a new mapping that does this:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: myservice-shadow
+spec:
+ hostname: '*'
+ prefix: /myservice/
+ service: myservice-shadow.default
+ shadow: true
+```
+
+The `prefix` is set to be the same as the first mapping, which tells $productName$ which production traffic to shadow. The destination service, where the shadow traffic is routed, is a *different* Kubernetes service, `myservice-shadow`. Finally, the `shadow: true` attribute actually enables shadowing.
+
+### Shadow traffic weighting
+
+It is possible to shadow a portion of the traffic by specifying the `weight` in the mapping. For example:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: myservice-shaddow
+spec:
+ hostname: '*'
+ prefix: /myservice/
+ service: myservice-shadow.default
+ shadow: true
+ weight: 10
+```
+
+In the example above, only 10% of the traffic will be forwarded to the shadowing service.
diff --git a/docs/emissary/latest/topics/using/tcpmappings.md b/docs/emissary/latest/topics/using/tcpmappings.md
new file mode 100644
index 000000000..f246e799a
--- /dev/null
+++ b/docs/emissary/latest/topics/using/tcpmappings.md
@@ -0,0 +1,300 @@
+# `TCPMapping` resources
+
+In addition to managing HTTP, gRPC, and WebSockets at layer 7, $productName$ can also manage TCP connections at layer 4. The core abstraction used to support TCP connections is the `TCPMapping`.
+
+An $productName$ `TCPMapping` associates TCP connections with upstream _services_.
+Cleartext TCP connections are defined by destination IP address and/or destination TCP port;
+TLS-encrypted TCP connections can also be defined by the hostname presented using SNI.
+A service is exactly the same as in HTTP [`Mappings`](../mappings/) and other $productName$ resources.
+
+## TCPMapping configuration
+
+Like all native $productName$ resources, `TCPMappings` have an
+`ambassador_id` field to select which $productName$ installations take
+notice of it:
+
+| Attribute | Description | Type | Default value |
+|:----------------|:--------------------------------------------------------------------------------------------------------------|:-----------------|----------------------------------|
+| `ambassador_id` | [A list of `ambassador_id`s which should pay attention to this resource](../../running/running#ambassador_id) | array of strings | optional; default is ["default"] |
+
+### Downstream configuration
+
+The downstream configuration refers to the connection between the end-client and $productName$.
+
+| Attribute | Description | Type | Default value |
+|:----------|:-----------------------------------------------------------------------------------------------------------------------------------------------------|:--------|:-----------------------------------------------------------------|
+| `port` | Which TCP port number $productName$ should listen on this `TCPMapping`; may or may not correspond to a [`Listener` resource](../../running/listener) | string | required; no default |
+| `host` | If non-empty, [terminate TLS](#tls-termination) on this port; using this hostglob for SNI-based for routing | string | optional; if not present, do not terminate TLS on this port |
+| `address` | Which IP address $productName$ should listen on | string | optional; if not present, accept connections on all IP addresses |
+| `weight` | The (integer) percentage of traffic for this resource when [canarying](../canary) between multiple `TCPMappings` | integer | optional; default is to not canary |
+
+If the `port` does not pair with an actual existing
+[`Listener`](../../running/listener), then an appropriate internal
+`Listener` is automatically created.
+
+If the `Listener` does *not* terminate TLS (controlled by
+`Listener.spec.protocolStack` and by `TCPMapping.spec.host`), then no
+[`Hosts`](../../running/host-crd) may associate with the `Listener`,
+and only one `TCPMapping` (or set of [canaried](../canary)
+`TCPMappings`; see the `weight` attribute) may associate with the
+`Listener`.
+
+If the `Listener` *does* terminate TLS, then any number of
+`TCPMappings` and `Hosts` may associate with the `Listener`, and are
+selected between using SNI.
+
+It is an error if the `TCPMapping.spec.host` and
+`Listener.spec.protocolStack` do not agree about whether TLS should be
+terminated, and the `TCPMapping` will be discarded.
+
+#### TLS termination
+
+If the `host` field is non-empty, then the `TCPMapping` will terminate
+TLS when listening for connections from end-clients
+
+To do this, $productName$ needs a TLS certificate and configuration;
+there are two ways that this can be provided:
+
+First, $productName$ checks for any [`Host`
+resources](../../running/host-crd) with TLS configured whose
+`Host.spec.hostname` glob-matches the `TCPMapping.spec.host`; if such
+a `Host` exists, then its TLS certificate and configuration is used.
+
+Second, if such a `Host` is not found, then $productName$ checks for
+any [`TLSContext` resources](../../running/tls) who have an item in
+`TLSContext.spec.hosts` that exact-matches the `TCPMapping.spec.host`;
+if such a `TLSContext` exists, then it and its certificate are used.
+These host fields may _contain_ globs, but they are not considered
+when matching; for example, a `TLSContext` host string of
+`*.example.com` would not match with a `TCPMapping` host of
+`foo.example.com`, but would match with a `TCPMapping` host of
+`*.example.com`.
+
+It is an error if no such `Host` or `TLSContext` is found, then the
+`TCPMapping` is discarded.
+
+### Upstream configuration
+
+The upstream configuration refers to the connection between
+$productName$ and the service that it is a gateway to.
+
+| Attribute | Description | Type | Default value |
+|:-------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:-----------------|:--------------------------------------------------------------------------------------------------------|
+| `service` | The service to talk to; a string of the format `scheme://host:port`, where `scheme://` and `:port` are optional. If the scheme is `https`, then TLS is originated, otherwise the scheme is ignored. | string | required; no default; if originating TLS the default port is 443, otherwise the default port is 80 |
+| `resolver` | The [resolver](../../running/resolvers) to use when resolving the hostname in `service` | string | optional |
+| `enable_ipv4` | Whether to enable IPv4 DNS lookups when resolving the hostname in `service`; has no affect if the hostname is an IP address or using a non-DNS `resolver`. | Boolean | optional; default is true unless set otherwise by the [`ambassador` `Module`](../../running/ambassador) |
+| `enable_ipv6` | Whether to enable IPv6 DNS lookups when resolving the hostname in `service`; has no affect if the hostname is an IP address or using a non-DNS `resolver`. | Boolean | optional; default is true unless set otherwise by the [`ambassador` `Module`](../../running/ambassador) |
+| `tls` | The name of a [`TLSContext`](../../running/tls) to originate TLS; TLS is originated if `tls` is non-empty. | string | optional; default is to not use a `TLSContext` |
+| `circuit_breakers` | Circuit breakers, same as for [HTTP `Mappings`](../circuit-breakers) | array of objects | optional; default is set by the [`ambassador` `Module`](../../running/ambassador) |
+| `idle_timeout_ms` | The timeout, in milliseconds, after which the connection will be terminated if no traffic is seen. | integer | optional; default is no timeout |
+
+If both `enable_ipv4` and `enable_ipv6` are true, $productName$ will prefer IPv6 to IPv4. See the [`ambassador` `Module`](../../running/ambassador) documentation for more information.
+
+The values for the scheme-part of the `service` are a bit of a
+misnomer; despite the `https://` string being recognized, it does not
+imply anything about whether the traffic is HTTP; just whether it is
+encrypted.
+
+If `service` does not specify a port number: if TLS is *not* being
+originated, then a default port number of `80` is used; if TLS *is*
+being originated (either because the `service` says `https://` or
+because `tls` is set), then a default port number of `443` is used
+(even if the service says `http://`).
+
+The default `resolver` is a KubernetesServiceResolver, which takes a [namespace-qualified DNS name](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#namespaces-of-services).
+Given that `AMBASSADOR_NAMESPACE` is correctly set, $productName$ can map to services in other namespaces:
+- `service: servicename` will route to a service in the same namespace as $productName$, and
+- `service: servicename.namespace` will route to a service in a different namespace.
+
+#### TLS origination
+
+If the `TCPMapping.spec.service` starts with `https://`, or if the
+`TCPMapping.spec.tls` is set, then the `TCPMapping` will originate TLS
+when dialing out to the service.
+
+If originating TLS, but `TCPMapping.spec.tls` is not set, then
+$productName$ will use a default TLS client configuration, and will
+not provide a client certificate.
+
+If `TCPMapping.spec.tls` is set, then $productName$ looks for a
+[`TLSContext` resource](../../running/tls) with that name (the
+`TLSContext` may be found in _any_ namespace).
+
+### `TCPMapping` and TLS
+
+The `TCPMapping.spec.host` attribute determines whether $productName$ will _terminate_ TLS when a client connects to $productName$.
+The `TCPMapping.spec.service` and `TCPMapping.spec.tls` attributes work together to determine whether $productName$ will _originate_ TLS when connecting to an upstream.
+The two are _totally_ independent.
+See the sections on [TLS termination](#tls-termination) and [TLS origination](#tls-origination), respectively.
+
+## Examples
+
+### neither terminating nor originating TLS
+
+If `host` is not set, then TLS is not terminated.
+If `service` does not start with `https://` and `tls` is empty, then TLS is not originated.
+So, if both of these are true, then$productName$ simply proxies bytes between the client and the upstream; TLS may or may not be involved, $productName$ doesn't care.
+You should specify in `service` which port to dial to; if you don't, $productName$ will use port 80 because it is not originating TLS.
+
+So, for example,
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: ssh
+spec:
+ port: 2222
+ service: upstream:22
+```
+
+could be used to relay an SSH connection on port 2222, or
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: cockroach
+spec:
+ port: 26257
+ service: cockroach:26257
+```
+
+could proxy a CockroachDB connection.
+
+### terminating TLS, but not originating it
+
+If `host` is set, then TLS is terminated.
+If `service` does not start with `https://` and `tls` is empty, then TLS is not originated.
+In this case, $productName$ will terminate the TLS connection, require that the host offered with SNI match the `host` attribute, and then make a **cleartext** connection to the upstream host.
+You should specify in `service` which port to dial to; if you don't, $productName$ will use port 80 because it is not originating TLS.
+
+This can be useful for doing host-based TLS proxying of arbitrary protocols, allowing the upstream to not have to care about TLS.
+
+Note that this case **requires** that you have created a termination `TLSContext` or `Host` that matches the `TCPMapping.spec.host`.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TLSContext
+metadata:
+ name: my-context
+spec:
+ hosts:
+ - my-host-1
+ - my-host-2
+ secret: supersecret
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: my-host-1
+spec:
+ port: 2222
+ host: my-host-1
+ service: upstream-host-1:9999
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: my-host-2
+spec:
+ port: 2222
+ host: my-host-2
+ service: upstream-host-2:9999
+```
+
+The above will accept a TLS connection with SNI on port 2222.
+If the client requests SNI host `my-host-1`, the decrypted traffic will be relayed to `upstream-host-1`, port 9999.
+If the client requests SNI host `my-host-2`, the decrypted traffic will be relayed to `upstream-host-2`, port 9999.
+Any other SNI host will cause the TLS handshake to fail.
+
+#### both terminating and originating TLS, with and without a client certificate
+
+If `host` is set, then TLS is terminated.
+In this case, $productName$ will terminate the incoming TLS connection, require that the host offered with SNI match the `host` attribute, and then make a **TLS** connection to the upstream host.
+
+If `tls` is non-empty, then TLS is originated with a client certificate.
+In this case, $productName$ will use the `TLSContext` referred to by `tls` to determine the certificate offered to the upstream service.
+
+If `service` starts with `https://`, then then TLS is originated without a client certificate (unless `tls` is also set)
+
+In either case, you should specify in `service` which port to dial to; if you don't, $productName$ will use port 443 because it is originating TLS.
+
+This is useful for doing host routing while ensuring that data is always encrypted while in-transit.
+
+Note that this case **requires** that you have created a termination `TLSContext` or `Host` that matches the `TCPMapping.spec.host`.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TLSContext
+metadata:
+ name: my-context
+spec:
+ hosts:
+ - my-host-1
+ - my-host-2
+ secret: supersecret
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TLSContext
+metadata:
+ name: origination-context
+spec:
+ secret: othersecret
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: test-1
+spec:
+ port: 2222
+ host: my-host-1
+ service: https://upstream-host-1:9999
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: test-2
+spec:
+ port: 2222
+ host: my-host-2
+ tls: origination-context
+ service: https://upstream-host-2:9999
+```
+
+The above will accept a TLS connection with SNI on port 2222.
+
+If the client requests SNI host `my-host-1`, the traffic will be relayed over a TLS connection to `upstream-host-1`, port 9999. No client certificate will be offered for this connection.
+
+If the client requests SNI host `my-host-2`, the decrypted traffic will be relayed to `upstream-host-2`, port 9999. The client certificate from `origination-context` will be offered for this connection.
+
+Any other SNI host will cause the TLS handshake to fail.
+
+#### originating TLS, but not terminating it
+
+Here, $productName$ will accept the connection **without terminating TLS**, then relay traffic over a **TLS** connection upstream. This is probably useful only to accept unencrypted traffic and force it to be encrypted when it leaves $productName$.
+
+Example:
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TLSContext
+metadata:
+ name: origination-context
+spec:
+ secret: othersecret
+---
+apiVersion: getambassador.io/v3alpha1
+kind: TCPMapping
+metadata:
+ name: test
+spec:
+ port: 2222
+ service: https://upstream-host:9999
+```
+
+The example above will accept **any** connection to port 2222 and relay it over a **TLS** connection to `upstream-host` port 9999. No client certificate will be offered.
diff --git a/docs/emissary/latest/topics/using/timeouts.md b/docs/emissary/latest/topics/using/timeouts.md
new file mode 100644
index 000000000..ae0041024
--- /dev/null
+++ b/docs/emissary/latest/topics/using/timeouts.md
@@ -0,0 +1,66 @@
+# Timeouts
+
+$productName$ enables you to control timeouts in several different ways.
+
+## Request timeout: `timeout_ms`
+
+`timeout_ms` is the end-to-end timeout for an entire user-level transaction in milliseconds. It begins after the full incoming request is received up until the full response stream is returned to the client. This timeout includes all retries. It can be disabled by setting the value to `0`.
+
+Default: `3000`
+
+## Idle timeout: `idle_timeout_ms`
+
+`idle_timeout_ms` controls how long a connection should remain open when no traffic is being sent through the connection. `idle_timeout_ms` is distinct from `timeout_ms`, as the idle timeout applies on either down or upstream request events and is reset every time an encode/decode event occurrs or data is processed for the stream. `idle_timeout_ms` operates on a per-route basis and will overwrite behavior of the `cluster_idle_timeout_ms`. If not set, $productName$ will default to the value set by `cluster_idle_timeout_ms`. It can be disabled by setting the value to `0`.
+
+## Cluster max connection lifetime: `cluster_max_connection_lifetime_ms`
+
+`cluster_max_connection_lifetime_ms` controls how long upstream connections should remain open, regardless of whether traffic is currently being sent through it or not. By setting this value, you can control how long Envoy will hold open healthy connections to upstream services before it is forced to recreate them, providing natural connection churn. This helps in situations where the upstream cluster is represented by a service discovery mechanism that requires new connections in order to discover new backends. In particular, this helps with Kubernetes Service-based routing where the set of upstream Endpoints changes, either naturally due to pod scale up or explicitly because the label selector changed.
+
+## Cluster idle timeout: `cluster_idle_timeout_ms`
+
+`cluster_idle_timeout_ms` controls how long a connection stream will remain open if there are no active requests. This timeout operates based on outgoing requests to upstream services. It can be disabled by setting the value to `0`.
+
+Default `3600000` (1 hour).
+
+## Connect timeout: `connect_timeout_ms`
+
+`connect_timeout_ms` sets the connection-level timeout for $productName$ to an upstream service at the network layer. This timeout runs until $productName$ can verify that a TCP connection has been established, including the TLS handshake. This timeout cannot be disabled.
+
+Default: `3000`
+
+## Module only
+
+## Listener idle timeout: `listener_idle_timeout_ms`
+
+`listener_idle_timeout_ms` configures the [`idle_timeout`](https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/upstreams/http/v3/http_protocol_options.proto.html#extensions-upstreams-http-v3-httpprotocoloptions)
+in the Envoy HTTP Connection Manager and controls how long a connection from the
+downstream client to $productName$ will remain open if there are no active
+requests. Only full requests will be counted towards this timeout so clients
+sending TCP keepalives will not guarantee a connection remains open. This
+timeout It can be disabled by setting the value to `0`.
+
+
+Default: `3600000` (1 hour)
+
+
+**Caution** Disabling this timeout increases the likelihood of stream leaks due
+to missed FINs in the TCP connection.
+
+### Example
+
+The various timeouts are applied to a Mapping resource and can be combined.
+
+```yaml
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Mapping
+metadata:
+ name: quote-backend
+spec:
+ hostname: '*'
+ prefix: /backend/
+ service: quote
+ timeout_ms: 4000
+ idle_timeout_ms: 500000
+ connect_timeout_ms: 2000
+```
diff --git a/docs/emissary/latest/tutorials/dev-portal-tutorial.md b/docs/emissary/latest/tutorials/dev-portal-tutorial.md
new file mode 100644
index 000000000..d3c0d0a8a
--- /dev/null
+++ b/docs/emissary/latest/tutorials/dev-portal-tutorial.md
@@ -0,0 +1,29 @@
+# Dev Portal tutorial
+
+In this tutorial, you will access and explore some of the key features of the Dev Portal.
+
+## Prerequisites
+
+You must have [$productName$ installed](../getting-started/) in your
+Kubernetes cluster. This tutorial assumes you have connected your cluster to Ambassador Cloud and deployed the `quote` app with the
+`Mapping` from the [$productName$ tutorial](../getting-started/).
+
+
+ ```
+ export AMBASSADOR_LB_ENDPOINT=$(kubectl -n ambassador get svc ambassador -o "go-template={{range .status.loadBalancer.ingress}}{{or .ip .hostname}}{{end}}")
+ ```
+
+## Developer API documentation
+
+The `quote` service you just deployed publishes its API as an
+[OpenAPI (formerly Swagger)](https://swagger.io/solutions/getting-started-with-oas/)
+document. $productName$ automatically detects and publishes this documentation.
+This can help with internal and external developer onboarding by serving as a
+single point of reference for of all your microservice APIs.
+
+1. To visualize your service's API doc, go to [Ambassador Cloud](https://app.getambassador.io/cloud/), navigate to your service's detailed view, and click on the "API" tab.
+
+1. Navigate to `https://Listener will associate with all Hosts in your cluster. This is fine for the quickstart, but is likely not what you really want for production use.Listener.Host.
+
+
+2. Apply the YAML for the "Quote" service.
+
+ ```
+ kubectl apply -f https://app.getambassador.io/yaml/v2-docs/$ossVersion$/quickstart/qotm.yaml
+ ```
+
+ kubectl get services,deployments quote to see their status.Listener and Mapping, routing a request from your cluster's edge to a service!
+
+## What's next?
+
+Explore some of the popular tutorials on $productName$:
+
+* [Configuring $productName$ communications](../../howtos/configure-communications): configure how $productName$ handles communication with clients
+* [Intro to `Mappings`](../../topics/using/intro-mappings/): declaratively routes traffic from
+the edge of your cluster to a Kubernetes service
+* [`Listener` resource](../../topics/running/listener/): configure ports, protocols, and security options for your ingress.
+* [`Host` resource](../../topics/running/host-crd/): configure a hostname and TLS options for your ingress.
+
+$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/emissary/latest/tutorials/gs-tabs.js b/docs/emissary/latest/tutorials/gs-tabs.js
new file mode 100644
index 000000000..e9b2ad7be
--- /dev/null
+++ b/docs/emissary/latest/tutorials/gs-tabs.js
@@ -0,0 +1,134 @@
+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:
+ --mount=true is the default if a mount option is not specified, use --mount=false to disable mounting volumes.--mount=true without a command, you can use either environment variable flag to retrieve the variable.--mount=true is the default if a mount option is not specified, use --mount=false to disable mounting volumes.--mount=true without a command, you can use either environment variable flag to retrieve the variable.--mount=true is the default if a mount option is not specified, use --mount=false to disable mounting volumes.--mount=true without a command, you can use either environment variable flag to retrieve the variable.<service name>.<namespace>) before you start an intercept. After you start an intercept, only <service name> is required.
What's Next?
+
+Follow one of our [quick start guides](../quick-start/) to start using Telepresence, either with our sample app or in your own environment.
+
+## Installing older versions of Telepresence
+
+Use these URLs to download an older version for your OS (including older nightly builds), replacing `x.y.z` with the versions you want.
+
+
diff --git a/docs/telepresence-oss/2.16/install/manager.md b/docs/telepresence-oss/2.16/install/manager.md
new file mode 100644
index 000000000..9a747d895
--- /dev/null
+++ b/docs/telepresence-oss/2.16/install/manager.md
@@ -0,0 +1,53 @@
+# Install/Uninstall the Traffic Manager
+
+Telepresence uses a traffic manager to send/recieve cloud traffic to the user. Telepresence uses [Helm](https://helm.sh) under the hood to install the traffic manager in your cluster.
+
+## Prerequisites
+
+Before you begin, you need to have [Telepresence installed](../../install/).
+In addition, you may need certain prerequisites depending on your cloud provider and platform.
+See the [cloud provider installation notes](../../install/cloud) for more.
+
+## Install the Traffic Manager
+
+The telepresence cli can install the traffic manager for you. The basic install will install the same version as the client used.
+
+1. Install the Telepresence Traffic Manager with the following command:
+
+ ```shell
+ telepresence helm install
+ ```
+
+### Customizing the Traffic Manager.
+
+For details on what the Helm chart installs and what can be configured, see the Helm chart [README](https://github.com/telepresenceio/telepresence/tree/release/v2/charts/telepresence).
+
+1. Create a values.yaml file with your config values.
+
+2. Run the install command with the values flag set to the path to your values file.
+
+ ```shell
+ telepresence helm install --values values.yaml
+ ```
+
+
+## Upgrading/Downgrading the Traffic Manager.
+
+1. Download the cli of the version of Telepresence you wish to use.
+
+2. Run the install command with the upgrade flag.
+
+ ```shell
+ telepresence helm install --upgrade
+ ```
+
+
+## Uninstall
+
+The telepresence cli can uninstall the traffic manager for you using the `telepresence helm uninstall` command (previously `telepresence uninstall --everything`).
+
+1. Uninstall the Telepresence Traffic Manager and all of the agents installed by it using the following command:
+
+ ```shell
+ telepresence helm uninstall
+ ```
diff --git a/docs/telepresence-oss/2.16/install/migrate-from-legacy.md b/docs/telepresence-oss/2.16/install/migrate-from-legacy.md
new file mode 100644
index 000000000..94307dfa1
--- /dev/null
+++ b/docs/telepresence-oss/2.16/install/migrate-from-legacy.md
@@ -0,0 +1,110 @@
+# Migrate from legacy Telepresence
+
+[Telepresence](/products/telepresence/) (formerly referenced as Telepresence 2, which is the current major version) has different mechanics and requires a different mental model from [legacy Telepresence 1](https://www.telepresence.io/docs/v1/) when working with local instances of your services.
+
+In legacy Telepresence, a pod running a service was swapped with a pod running the Telepresence proxy. This proxy received traffic intended for the service, and sent the traffic onward to the target workstation or laptop. We called this mechanism "swap-deployment".
+
+In practice, this mechanism, while simple in concept, had some challenges. Losing the connection to the cluster would leave the deployment in an inconsistent state. Swapping the pods would take time.
+
+Telepresence 2 introduces a [new
+architecture](../../reference/architecture/) built around "intercepts"
+that addresses these problems. With the new Telepresence, a sidecar
+proxy ("traffic agent") is injected onto the pod. The proxy then
+intercepts traffic intended for the Pod and routes it to the
+workstation/laptop. The advantage of this approach is that the
+service is running at all times, and no swapping is used. By using
+the proxy approach, we can also do personal intercepts, where rather
+than re-routing all traffic to the laptop/workstation, it only
+re-routes the traffic designated as belonging to that user, so that
+multiple developers can intercept the same service at the same time
+without disrupting normal operation or disrupting eacho.
+
+Please see [the Telepresence quick start](../../quick-start/) for an introduction to running intercepts and [the intercept reference doc](../../reference/intercepts/) for a deep dive into intercepts.
+
+## Using legacy Telepresence commands
+
+First please ensure you've [installed Telepresence](../).
+
+Telepresence is able to translate common legacy Telepresence commands into native Telepresence commands.
+So if you want to get started quickly, you can just use the same legacy Telepresence commands you are used
+to with the Telepresence binary.
+
+For example, say you have a deployment (`myserver`) that you want to swap deployment (equivalent to intercept in
+Telepresence) with a python server, you could run the following command:
+
+```
+$ telepresence --swap-deployment myserver --expose 9090 --run python3 -m http.server 9090
+< help text >
+
+Legacy telepresence command used
+Command roughly translates to the following in Telepresence:
+telepresence intercept echo-easy --port 9090 -- python3 -m http.server 9090
+running...
+Connecting to traffic manager...
+Connected to context
diff --git a/docs/telepresence-oss/2.16/quick-start/TelepresenceQuickStartLanding.js b/docs/telepresence-oss/2.16/quick-start/TelepresenceQuickStartLanding.js
new file mode 100644
index 000000000..9a68e9bbf
--- /dev/null
+++ b/docs/telepresence-oss/2.16/quick-start/TelepresenceQuickStartLanding.js
@@ -0,0 +1,64 @@
+import queryString from 'query-string';
+import React, { useEffect, useState } from 'react';
+
+import Embed from '../../../../src/components/Embed';
+import Icon from '../../../../../src/components/Icon';
+import Link from '../../../../../src/components/Link';
+
+import './telepresence-quickstart-landing.less';
+
+/** @type React.FC+ Set up your ideal development environment for Kubernetes in seconds. + Accelerate your inner development loop with hot reload using your + existing IDE, and workflow. +
+ +Telepresence gives Kubernetes application developers:
+ What's Next?
+
+You've intercepted a service in one of our demo clusters, now you can use Telepresence to [intercept a service in your own environment](https://www.getambassador.io/docs/telepresence/latest/howtos/intercepts/)!
diff --git a/docs/telepresence-oss/2.16/quick-start/index.md b/docs/telepresence-oss/2.16/quick-start/index.md
new file mode 100644
index 000000000..9a481d427
--- /dev/null
+++ b/docs/telepresence-oss/2.16/quick-start/index.md
@@ -0,0 +1,182 @@
+---
+description: "Start using Telepresence in your own environment. Follow these steps to intercept your service in your cluster."
+---
+
+import Alert from '@material-ui/lab/Alert';
+import Platform from '@src/components/Platform';
+import QSCards from '../quick-start/qs-cards'
+
+# Telepresence Quickstart
+
+Telepresence is an open source tool that enables you to set up remote development environments for Kubernetes where you can still use all of your favorite local tools like IDEs, debuggers, and profilers.
+
+## Prerequisites
+
+ - [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/), the Kubernetes command-line tool, or the OpenShift Container Platform command-line interface, [oc](https://docs.openshift.com/container-platform/4.2/cli_reference/openshift_cli/getting-started-cli.html#cli-installing-cli_cli-developer-commands).
+ - A Kubernetes Deployment and Service.
+
+ targetPort of your intercepted service is pointing at a port number, in addition to
+injecting the Traffic Agent sidecar, Telepresence will also inject an initContainer that will
+reconfigure the pod's firewall rules to redirect traffic to the Traffic Agent.
+
+