datawire · d6e-automaton · Sep 30, 2023
diff --git a/docs/edge-stack/latest b/docs/edge-stack/latest
diff --git a/docs/edge-stack/latest/about/aes-emissary-eol.md b/docs/edge-stack/latest/about/aes-emissary-eol.md
@@ -0,0 +1,56 @@
+# $productName$ End of Life Policy
+
+This document describes the End of Life policy and maintenance windows for Ambassador Edge Stack, and to the open source project Emissary Ingress.
+
+## Supported Versions
+
+Ambassador Edge Stack and Emissary-ingress versions are expressed as **x.y.z**, where **x** is the major version, **y** is the minor version, and **z** is the patch version, following [Semantic Versioning](https://semver.org/) terminology.
+
+**X-series (Major Versions)**
+
+- **1.y**: 1.0 GA on January 2020
+- **2.y**: 2.0.4 GA on October 2021, and 2.1.0 in December 2021.
+
+**Y-release (Minor versions)**
+
+- For 1.y, that is **1.14.z**
+- For 2.y, that is **2.3.z**
+
+In this document, **Current** refers to the latest X-series release.
+
+Maintenance refers to the previous X-series release, including security and Sev1 defect patches.
+
+## CNCF Ecosystem Considerations
+
+- Envoy releases a major version every 3 months and supports its previous releases for 12 months. Envoy does not support any release longer than 12 months.
+- Kubernetes 1.19 and newer receive 12 months of patch support (The [Kubernetes Yearly Support Period](https://github.com/kubernetes/enhancements/blob/master/keps/sig-release/1498-kubernetes-yearly-support-period/README.md)).
+
+# The Policy
+
+> We will offer a 6 month maintenance window for the latest Y-release of an X-series after a new X-series goes GA and becomes the current release. For example, we will support 2.3 for severity 1 and defect patches for six months after 3.0 is released.
+>
+
+> During the maintenance window, Y-releases will only receive security and Sev1 defect patches. Users desiring new features or bug fixes for lower severity defects will need to upgrade to the current X-series.
+>
+
+> The current X-series will receive as many Y-releases as necessary and as often as we have new features or patches to release.
+>
+
+> Ambassador Labs offers no-downtime migration to current versions from maintenance releases. Migration from releases that are outside of the maintenance window may be subject to downtime.
+>
+
+> Artifacts of releases outside of the maintenance window will be frozen and will remain available publicly for download with the best effort. These artifacts include Docker images, application binaries, Helm charts, etc.
+>
+
+### When we say support with “defect patches”, what do we mean?
+
+- We will fix security issues in our Emissary-ingress and Ambassador Edge Stack code
+- We will pick up security fixes from dependencies as they are made available
+- We will not maintain forks of our major dependencies
+- We will not attempt our own back ports of critical fixes to dependencies which are out of support from their own communities
+
+## Extended Maintenance for 1.14
+
+Given this policy, we should have dropped maintenance for 1.14 in March 2022, however we recognize that the introduction of an EOL policy necessitates a longer maintenance window. For this reason, we do offer an "extended maintenance" window for 1.14 until the end of September 2022, 3 months after the latest 2.3 release. Please note that this extended maintenance window will not apply to customers using Kubernetes 1.22 and above, and this extended maintenance will also not provide a no-downtime migration path from 1.14 to 3.0.
+
+After September 2022, the current series will be 3.x, and the maintenance series will be 2.y.
diff --git a/docs/edge-stack/latest/about/changes-2.x.md b/docs/edge-stack/latest/about/changes-2.x.md
@@ -0,0 +1,243 @@
+import Alert from '@material-ui/lab/Alert';
+
+Major Changes in $productName$ 2.X
+==================================
+
+The 2.X family introduces a number of changes to allow $productName$
+to more gracefully handle larger installations, reduce global configuration to
+better handle multitenant or multiorganizational installations, reduce memory
+footprint, and improve performance. We welcome feedback!! Join us on
+[Slack](http://a8r.io/slack) and let us know what you think.
+
+While $productName$ 2 is functionally compatible with $productName$ 1.14, note
+that this is a **major version change** and there are important differences between
+$productName$ 1.X and $productName$ $version$. For details, read on.
+
+## 1. Configuration API Version `getambassador.io/v3alpha1`
+
+$productName$ 2.0 introduced API version `getambassador.io/v3alpha1` to allow
+certain changes in configuration resources that are not backwards compatible with
+$productName$ 1.X. The most notable example of change is the addition of the
+**mandatory** `Listener` resource; however, there are important changes
+in `Host` and `Mapping` as well.
+
+<Alert severity="info">
+  $productName$ 2.X supports only API versions <code>getambassador.io/v2</code>
+  and <code>getambassador.io/v3alpha1</code>. If you are using any resources with
+  older API versions, you will need to upgrade them.
+</Alert>
+
+API version `getambassador.io/v3alpha1` replaces `x.getambassador.io/v3alpha1` from
+the 2.0 developer previews. `getambassador.io/v3alpha1` may still change as we receive
+feedback.
+
+## 2. Kubernetes 1.22 and Structural CRDs
+
+Kubernetes 1.22 requires [<i>structural CRDs</i>](https://kubernetes.io/blog/2019/06/20/crd-structural-schema/).
+This change is primarily meant to support better CRD validation, but it also has the
+effect that union types are no longer allowed in CRDs: for example, an element that can be
+either a string or a list of strings is not allowed. Several such elements appeared in the
+`getambassador.io/v2` CRDs, requiring changes. In `getambassador.io/v3alpha1`:
+
+- `ambassador_id` must always be a list of strings
+- `Host.mappingSelector` supersedes `Host.selector`, and controls association between Hosts and Mappings
+- `Mapping.hostname` supersedes `Mapping.host` and `Mapping.host_regex`
+- `Mapping.tls` can only be a string
+- `Mapping.labels` always requires maps instead of strings
+
+## 2. `Listener`s, `Host`s, and `Mapping`s
+
+$productName$ 2.0 introduced the new **mandatory** `Listener` CRD, and made some changes
+to the `Host` and `Mapping` resources.
+
+### The `Listener` CRD
+
+The new [`Listener` CRD](../../topics/running/listener) defines where and how $productName$ should listen for requests from the network, and which `Host` definitions should be used to process those requests.
+
+**Note that `Listener`s are never created by $productName$, and must be defined by the user.** If you do not
+define any `Listener`s, $productName$ will not listen anywhere for connections, and therefore won't do
+anything useful. It will log a `WARNING` to this effect.
+
+A `Listener` specifically defines
+
+- `port`: a port number on which to listen for new requests;
+- `protocol` and `securityModel`: the protocol stack and security model to use (e.g. `HTTPS` using the `X-Forwarded-Proto` header); and
+- `hostBinding`: how to tell if a given `Host` should be associated with this `Listener`:
+   - a `Listener` can choose to consider all `Host`s, or only `Host`s in the same namespace as the `Listener`, or
+   - a `Listener` can choose to consider only `Host`s with a particular Kubernetes `label`.
+
+**Note that the `hostBinding ` is mandatory.** A `Listener` _must_ specify how to identify the `Host`s to associate with the `Listener`', or the `Listener` will be rejected. This is intended to help prevent cases where a `Listener` mistakenly grabs too many `Host`s: if you truly need a `Listener` that associates with all `Host`s, the easiest way is to tell the `Listener` to look for `Host`s in all namespaces, with no further selectors, for example:
+
+```yaml
+apiVersion: getambassador.io/v3alpha1
+kind: listener
+metadata:
+  name: all-hosts-listener
+spec:
+  port: 8080
+  securityModel: XFP
+  protocol: HTTPS
+  hostBinding:
+    namespace:
+      from: ALL
+```
+
+A `Listener` that has no associated `Host`s will be logged as a `WARNING`, and will not be included in the Envoy configuration generated by $productName$.
+
+Note also that there is no limit on how many `Listener`s may be created, and as such no limit on the number of ports to which a `Host` may be associated.
+
+<Alert severity="info">
+  <a href="../../topics/running/listener">Learn more about <code>Listener</code></a>.<br/>
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.
+</Alert>
+
+### Wildcard `Host`s No Longer Created
+
+In $productName$ 1.X, $productName$ would make sure that a wildcard `Host`, with a `hostname` of `"*"`, was always present.
+$productName$ 2.X does **not** force a wildcard `Host`: if you need the wildcard behavior, you will need to create
+a `Host` with a hostname of `"*"`.
+
+Of particular note is that $productName$ **will not** respond to queries to an IP address unless a wildcard
+`Host` is present. If `foo.example.com` resolves to `10.11.12.13`, and the only `Host` has a
+`hostname` of `foo.example.com`, then:
+
+- requests to `http://foo.example.com/` will work, but
+- requests to `http://10.11.12.13/` will **not** work.
+
+Adding a `Host` with a `hostname` of `"*"` will allow the second query to work.
+
+<Alert severity="info">
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.
+</Alert>
+
+### `Host` and `Mapping` Association
+
+The [`Host` CRD](../../topics/running/host-crd) continues to define information about hostnames, TLS certificates, and how to handle requests that are "secure" (using HTTPS) or "insecure" (using HTTP). The [`Mapping` CRD](../../topics/using/intro-mappings) continues to define how to map the URL space to upstream services.
+
+However, as of $productName$ 2.0, 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.
+
+   - Note that a `getambassador.io/v2` `Mapping` has `host` and `host_regex`, rather than `hostname`.
+      - A `getambassador.io/v3alpha1` `Mapping` will honor `host` and `host_regex` as a transition aid, but `host` and `host_regex` are deprecated in favor of `hostname`.
+      - A `Mapping` that specifies `host_regex: true` will be associated with all `Host`s. This is generally far less desirable than using `hostname` with a DNS glob.
+
+- The `Host` specifies a `mappingSelector` that matches the `Mapping`'s Kubernetes `label`s.
+
+   - Note that a `getambassador.io/v2` `Host` has a `selector`, rather than a `mappingSelector`.
+      - A `getambassador.io/v3alpha1` `Host` ignores `selector` and, instead, looks only at `mappingSelector`.
+      - Where a `selector` got a default value if not specified, `mappingSelector` must be explicitly stated.
+
+Without either a `hostname` match or a `label` match, 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.
+
+<Alert severity="info">
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.<br/>
+  <a href="../../topics/using/intro-mappings">Learn more about <code>Mapping</code></a>.
+</Alert>
+
+### Independent `Host` Actions
+
+Each `Host` can specify its `requestPolicy.insecure.action` independently of any other `Host`, allowing for HTTP routing as flexible as HTTPS routing.
+
+<Alert severity="info">
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.
+</Alert>
+
+### `Host`, `TLSContext`, and TLS Termination
+
+As of $productName$ 2.0, **`Host`s are required for TLS termination**. It is no longer sufficient to create a [`TLSContext`](../../topics/running/tls/#tlscontext) by itself; the [`Host`](../../topics/running/host-crd) is required.
+
+The minimal setup for TLS termination is therefore a Kubernetes `Secret` of type `kubernetes.io/tls`, and a `Host` that uses it:
+
+```yaml
+---
+kind: Secret
+type: kubernetes.io/tls
+metadata:
+  name: minimal-secret
+data:
+  tls secret goes here
+---
+apiVersion: getambassador.io/v3alpha1
+kind: Host
+metadata:
+  name: minimal-host
+spec:
+  hostname: minimal.example.com
+  tlsSecret:
+    name: minimal-secret
+```
+
+It is **not** necessary to explicitly state a `TLSContext` in the `Host`: setting `tlsSecret` is enough. Of course, `TLSContext` is still the ideal way to share TLS configuration between more than one `Host`. For further examples, see [Configuring $productName$ Communications](../../howtos/configure-communications).
+
+<Alert severity="info">
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.<br/>
+  <a href="../../topics/running/tls/#tlscontext">Learn more about <code>TLSContext</code></a>.
+</Alert>
+
+### `Mapping`s, `TCPMapping`s, and TLS Origination
+
+A `getambassador.io/v2` `Mapping` or `TCPMapping` could specify `tls: true` to indicate TLS origination without supplying a certificate. This is not supported in `getambassador.io/v3alpha1`: instead, use an `https://` prefix on the `service`. In the [Mapping](../../topics/using/mappings/#using-tls), this is straightforward, but [there are more details for the `TCPMapping` when using TLS](../../topics/using/tcpmappings/#tcpmapping-and-tls).
+
+<Alert severity="info">
+  <a href="../../topics/using/intro-mappings">Learn more about <code>Mapping</code></a>.
+</Alert>
+
+### `Mapping`s and `labels`
+
+The `Mapping` CRD includes a `labels` field, used with rate limiting. The
+[syntax of the `labels`](../../topics/using/rate-limits#attaching-labels-to-requests) has changed
+for compatibility with Kubernetes 1.22.
+
+<Alert severity="info">
+  <a href="../../topics/using/intro-mappings">Learn more about <code>Mapping</code></a>.
+</Alert>
+
+### `Host`s and ACME
+
+In $productName$ 2.0, ACME will be disabled if a `Host` does not set `acmeProvider` at all (prior to $productName$ 2.0, not mentioning `acmeProvider` would result in the ACME client attempting, and failing, to start). If `acmeProvider` is set, but `acmeProvider.authority` is not set, the ACME client will continue to default to Let's Encrypt, in order to preserve compatibility with $productName$ prior to $productName$ 2.0. For further examples, see [Configuring $productName$ to Communicate](../../howtos/configure-communications).
+
+<Alert severity="info">
+  <a href="../../topics/running/host-crd">Learn more about <code>Host</code></a>.
+</Alert>
+
+## 3. Other Changes
+
+### Envoy V3 API by Default
+
+By default, $productName$ 2.X will configure Envoy using the
+[V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api).
+
+### More Performant Reconfiguration by Default
+
+In $productName$ 1.X, the environment variable `AMBASSADOR_FAST_RECONFIGURE` could be used to enable a higher performance implementation of the code $productName$ uses to validate and generate Envoy configuration. In $productName$ 2.X, this higher-performance mode is always enabled.
+
+### Changes to the `ambassador` `Module`, and the `tls` `Module`
+
+It is no longer possible to configure TLS using the `tls` element of the `ambassador` `Module` or using the `tls` `Module`. Both of these cases are correctly covered by the `TLSContext` resource.
+
+With the introduction of the `Listener` resource, a few settings have moved from the `Module` to the `Listener`.
+
+Configuration for the `PROXY` protocol is part of the `Listener` resource in $productName$ 2.X, so the `use_proxy_protocol` element of the `ambassador` `Module` is no longer supported. Note that the `Listener` resource can configure `PROXY` resource per-`Listener`, rather than having a single global setting. For further information, see the [`Listener` documentation](../../topics/running/listener).
+
+`xff_num_trusted_hops` has been removed from the `Module`, and its functionality has been moved to the `l7Depth` setting in the `Listener` resource.
+
+<Alert severity="info">
+  <a href="../../topics/running/listener">Learn more about <code>Listener</code></a>.
+</Alert>
+
+### `TLSContext` `redirect_cleartext_from` and `Host` `insecure.additionalPort`
+
+`redirect_cleartext_from` has been removed from the `TLSContext` resource; `insecure.additionalPort` has been removed from the `Host` CRD. Both of these cases are covered by adding additional `Listener`s. For further examples, see [Configuring $productName$ Communications](../../howtos/configure-communications).
+
+### Service Preview No Longer Supported
+
+Service Preview is no longer supported as of $productName$ 2.X, as its use cases are supported by Telepresence.
+
+### Edge Policy Console No Longer Supported
+
+The Edge Policy Console has been removed as of $productName$ 2.X, in favor of Ambassador Cloud.
+
+### `Project` CRD No Longer Supported
+
+The `Project` CRD has been removed as of $productName$ 2.X, in favor of Argo.
diff --git a/docs/edge-stack/latest/about/changes-3.y.md b/docs/edge-stack/latest/about/changes-3.y.md
@@ -0,0 +1,56 @@
+import Alert from '@material-ui/lab/Alert';
+
+Major Changes in $productName$ 3.X
+==================================
+
+The 3.X family introduces a number of changes to ensure $productName$
+keeps up with latest Envoy versions and to support new features such as HTTP/3.
+We welcome feedback! Join us on [Slack](http://a8r.io/slack) and let us know what you think.
+
+$productName$ 3 is functionally compatible with $productName$ 2.x, but with any major upgrade there are some changes to consider. Such as, Envoy removing support for V2 Transport Protocol features. Below we will outline some of these changes and things to consider when upgrading.
+
+## 1. Envoy Upgraded to 1.22
+
+$productName$ 3.X has been upgraded from Envoy 1.17.X to Envoy **1.22** which keeps $productName$ up-to-date with
+the latest security fixes, bug fixes, performance improvements and feature enhancements provided by Envoy Proxy. Most of the changes are under the hood but the most notable change to developers is the removal of support for Envoy V2 Transport Protocol. This means all external filters and LogServices must be updated to use the V3 Protocol.
+
+This also means some of the v2 runtime bootstrap flags have been removed as well:
+
+```yaml
+# No longer necessary because this was removed from Envoy
+# $productName$ already was converted to use the compressor API
+# https://www.envoyproxy.io/docs/envoy/v1.22.0/configuration/http/http_filters/compressor_filter#config-http-filters-compressor
+"envoy.deprecated_features.allow_deprecated_gzip_http_filter": true,
+
+# Upgraded to v3, all support for V2 Transport Protocol removed
+"envoy.deprecated_features:envoy.api.v2.route.HeaderMatcher.regex_match": true,
+"envoy.deprecated_features:envoy.api.v2.route.RouteMatch.regex": true,
+
+# Developer will need to upgrade TracingService to V3 protocol which no longer supports HTTP_JSON_V1
+"envoy.deprecated_features:envoy.config.trace.v2.ZipkinConfig.HTTP_JSON_V1": true,
+
+# V2 protocol removed so flag no longer necessary
+"envoy.reloadable_features.enable_deprecated_v2_api": true,
+```
+
+<Alert severity="info">
+  <a href="https://www.envoyproxy.io">Learn more about Envoy Proxy changes</a>.
+</Alert>
+
+## 2. Envoy V2 xDS Transport Protocol Support Removed
+
+With the upgrade to Envoy **1.22**, the V2 Envoy Transport Protocol is no longer supported and has been removed.
+$productName$ 3.X **only** supports [V3 Envoy API](https://www.envoyproxy.io/docs/envoy/latest/api-v3/api).
+
+The `AuthService`, `RatelimitService`, `LogService` and `ExternalFilters` that use the `grpc` protocol will now need to explicilty set `protocol_version: "v3"`. If not set or set to `v2` then an error will be posted and a static response will be returned.
+
+
+## 3. Envoy V2 xDS Configration Support Removed
+
+Envoy can no longer be configured to use the v2 xDS configuration and will always use v3 xDS configuration. This change removes the <code>AMBASSADOR_ENVOY_API_VERSION</code> 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`.